Boxc Shops API
The Shops resource allows a user to manage their fulfillment shop. A shop with orders or SKUs cannot be deleted. Clients should use a third party platform for integrating their ecommerce marketplaces with the BoxC API.
OpenAPI Specification
swagger: '2.0'
info:
x-logo:
url: https://storage.googleapis.com/boxc_cdn/public/boxc-logo.png
altText: BoxC
title: BoxC CalculateDuty Shops API
version: '1.123'
description: 'A simple but powerful logistics API that drives international ecommerce by utilizing a single integration with access to dozens of carriers and global markets. BoxC can complete every leg or only select steps of a shipment''s journey on your behalf with our routing engine.
'
schemes:
- https
tags:
- name: Shops
x-displayName: Shops
description: The Shops resource allows a user to manage their fulfillment shop. A shop with orders or SKUs cannot be deleted. Clients should use a third party platform for integrating their ecommerce marketplaces with the BoxC API.
paths:
/shops:
get:
tags:
- Shops
summary: GET /shops
description: Retrieves a list of shops.
operationId: getShops
consumes:
- application/json
produces:
- application/json
security:
- JWT:
- read_shops
parameters:
- in: query
name: limit
description: The number of results to return.
required: false
type: integer
default: 50
maximum: 100
- in: query
name: name
description: Filter that searches for shops with a similar name.
default: null
required: false
type: string
- in: query
name: page_token
description: Used for selecting the page after the initial query.
required: false
type: string
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n -H \"Accept: application/json\" \\\n https://api.boxc.com/v1/shops\\?limit=50\\&name=PhoneBlox\n"
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
shops:
type: array
items:
$ref: '#/definitions/Shop'
next_page:
type: string
description: Page token. Set by the system.
example: null
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/definitions/BadRequest'
examples:
invalidToken:
summary: Bad Request
description: Invalid page token
value:
code: 1025
message: Invalid page token
errors:
- Invalid page token
'401':
$ref: '#/definitions/Unauthorized'
'403':
$ref: '#/definitions/Forbidden'
'429':
$ref: '#/definitions/RateLimit'
post:
tags:
- Shops
summary: POST /shops
description: Creates a new shop.
operationId: addShop
consumes:
- application/json
produces:
- application/json
security:
- JWT:
- write_shops
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -X POST https://api.boxc.com/v1/shops \\\n -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"shop\": {\n \"id\": \"my-shop\",\n \"active\": true,\n \"name\": \"Appleseeds\",\n \"settings\": {\n \"delay_processing\": 240\n },\n \"type\": \"BoxC\"\n }\n }'\n"
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
shop:
$ref: '#/definitions/Shop'
required:
- shop
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
description: Shop object
properties:
shop:
$ref: '#/definitions/Shop'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/definitions/BadRequest'
examples:
validation:
summary: Validation error
description: The request schema is invalid.
value:
code: 1000
message: 'Validation Error. /shop: The required properties (name) are missing'
status: error
errors:
- '/shop: The required properties (name) are missing'
badRequest:
summary: Bad Request
description: Shop ID is already in use
value:
code: 1373
message: Shop ID is already in use
errors:
- Shop ID is already in use
'401':
$ref: '#/definitions/Unauthorized'
'403':
$ref: '#/definitions/Forbidden'
'429':
$ref: '#/definitions/RateLimit'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/definitions/InternalServerError'
examples:
internalServerError:
summary: Internal Server Error
description: Shop can't be created
value:
code: 1372
message: Shop can't be created
errors:
- Shop can't be created
/shops/{id}:
get:
tags:
- Shops
summary: GET /shops/{id}
description: Retrieves a shop.
operationId: getShopsById
consumes:
- application/json
produces:
- application/json
security:
- JWT:
- read_shops
parameters:
- name: id
in: path
description: The shop ID
required: true
type: string
maxLength: 32
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n -H \"Accept: application/json\" \\\n https://api.boxc.com/v1/shops/{id}\n"
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
shop:
$ref: '#/definitions/Shop'
'401':
$ref: '#/definitions/Unauthorized'
'403':
$ref: '#/definitions/Forbidden'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/definitions/NotFound'
examples:
notFound:
summary: Not Found
description: Shop not found
value:
code: 1370
message: Shop not found
errors:
- Shop not found
'429':
$ref: '#/definitions/RateLimit'
put:
tags:
- Shops
summary: PUT /shops/{id}
description: Updates a shop.
operationId: updateShop
consumes:
- application/json
produces:
- application/json
security:
- JWT:
- write_shops
parameters:
- name: id
in: path
description: The shop ID
required: true
type: string
maxLength: 32
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -X PUT https://api.boxc.com/v1/shops/{id} \\\n -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"shop\": {\n \"active\": true,\n \"name\": \"Appleseeds\",\n \"settings\": {\n \"delay_processing\": 200\n },\n \"type\": \"BoxC\"\n }\n }'\n"
requestBody:
required: true
content:
application/json:
schema:
type: object
description: Shop object
properties:
shop:
$ref: '#/definitions/ShopPut'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
description: Shop object
properties:
shop:
$ref: '#/definitions/Shop'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/definitions/BadRequest'
examples:
validation:
summary: Validation error
description: The request schema is invalid.
value:
code: 1000
message: Request is malformed.
status: error
errors:
- Request is malformed.
'401':
$ref: '#/definitions/Unauthorized'
'403':
$ref: '#/definitions/Forbidden'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/definitions/NotFound'
examples:
notFound:
summary: Not Found
description: Shop not found
value:
code: 1370
message: Shop not found
errors:
- Shop not found
'429':
$ref: '#/definitions/RateLimit'
delete:
tags:
- Shops
summary: DELETE /shops/{id}
description: Deletes a shop.
operationId: deleteShop
consumes:
- application/json
produces:
- application/json
security:
- JWT:
- write_shops
parameters:
- name: id
in: path
description: The shop ID
required: true
type: string
maxLength: 32
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -X DELETE https://api.boxc.com/v1/shops/{id} \\\n -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n -H \"Content-Type: application/json\"\n"
responses:
'200':
description: OK
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/definitions/BadRequest'
examples:
cannotDelete:
summary: Bad Request
description: Shop can't be deleted
value:
code: 1371
message: Shop can't be deleted
errors:
- Shop can't be deleted
'401':
$ref: '#/definitions/Unauthorized'
'403':
$ref: '#/definitions/Forbidden'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/definitions/NotFound'
examples:
notFound:
summary: Not Found
description: Shop not found
value:
code: 1370
message: Shop not found
errors:
- Shop not found
'429':
$ref: '#/definitions/RateLimit'
definitions:
settings:
type: object
description: Default settings for the shop.
properties:
delay_processing:
type: integer
description: 'The number of <u>hours</u> an order should remain unprocessed in the system before packing. Orders will be processed if their <em>created</em> value plus the shop''s <em>delay_processing</em> value is greater than the current time. Max: 240.'
example: 240
default: 0
bad-request:
type: object
summary: Bad Request
description: Validation error with the request
properties:
code:
description: Error code. Refer to the list of [Errors](/#tag/Errors).
type: integer
message:
description: Error message explaining the code.
type: string
status:
type: string
enum:
- error
example: error
errors:
description: Lists validation errors with the schema or the resource being operated on.
type: array
minItems: 1
maxItems: 5
items:
type: string
shop:
allOf:
- type: object
properties:
id:
type: string
description: The shop ID. This property is immutable and must be unique.
minLength: 3
maxLength: 32
pattern: A-Za-z0-9-_
example: my-shop
required:
- id
- name
- $ref: '#/definitions/ShopPut'
Shop:
$ref: '#/definitions/shop'
InternalServerError:
$ref: '#/definitions/internal-server-error'
Settings:
$ref: '#/definitions/settings'
NotFound:
$ref: '#/definitions/not-found'
shop-put:
type: object
properties:
active:
type: boolean
description: Whether or not the shop is active. This only applies to third party shops. An inactive third party shop will no longer have its orders imported into the system.
example: true
default: true
created:
type: string
description: The date and time the shop was created.
example: '2024-06-17 13:22:44'
readOnly: true
name:
type: string
description: The shop name.
minLength: 3
maxLength: 32
example: Appleseeds
settings:
$ref: '#/definitions/Settings'
type:
type: string
description: The type of shop. Always "BoxC".
example: BoxC
deprecated: true
enum:
- BoxC
BadRequest:
$ref: '#/definitions/bad-request'
unauthorized:
description: Unauthorized
content:
application/json:
schema:
type: object
summary: Unauthorized
description: Lack of valid authentication credentials for the resource
properties:
code:
description: Error code. Refer to the list of [Errors](/#tag/Errors).
type: integer
message:
description: Error message explaining the code.
type: string
status:
type: string
enum:
- error
example: error
errors:
description: Displays processing error.
type: array
minItems: 1
maxItems: 1
items:
type: string
examples:
accessToken:
summary: Invalid access token
description: Invalid access token
value:
code: 1005
message: Invalid access token
errors:
- Invalid access token
not-found:
type: object
summary: Not Found
description: Object not found or not owned by the user
properties:
code:
description: Error code. Refer to the list of [Errors](/#tag/Errors).
type: integer
message:
description: Error message explaining the code.
type: string
status:
type: string
enum:
- error
example: error
errors:
description: Duplicate of the error message
type: array
items:
type: string
internal-server-error:
type: object
summary: Internal Server Error
description: Processing Error
properties:
code:
description: Error code. Refer to the list of [Errors](/#tag/Errors).
type: integer
message:
description: Error message explaining the code.
type: string
status:
type: string
enum:
- error
example: error
errors:
description: Displays processing error.
type: array
minItems: 1
maxItems: 1
items:
type: string
rate-limit:
description: Too Many Requests
content:
application/json:
schema:
type: object
summary: Too Many Requests
description: Error for too many requests in a given time frame. See [Rate Limits](/#tag/RateLimit) for more information.
properties:
code:
description: Error code. Refer to the list of [Errors](/#tag/Errors).
type: integer
message:
description: Error message explaining the code.
type: string
status:
type: string
enum:
- error
example: error
errors:
description: Displays processing error.
type: array
minItems: 1
maxItems: 1
items:
type: string
examples:
rateLimit:
summary: Too Many Requests
description: Too many requests. Please wait before trying again.
value:
code: 1015
message: Too many requests. Please wait before trying again.
errors:
- Too many requests. Please wait before trying again.
ShopPut:
$ref: '#/definitions/shop-put'
Unauthorized:
$ref: '#/definitions/unauthorized'
Forbidden:
$ref: '#/definitions/forbidden'
RateLimit:
$ref: '#/definitions/rate-limit'
forbidden:
description: Forbidden
content:
application/json:
schema:
type: object
summary: Forbidden
description: Error relating to insufficient permissions for a resource
properties:
code:
description: Error code. Refer to the list of [Errors](/#tag/Errors).
type: integer
message:
description: Error message explaining the code.
type: string
status:
type: string
enum:
- error
example: error
errors:
description: Displays processing error.
type: array
minItems: 1
maxItems: 1
items:
type: string
examples:
revoked:
summary: Forbidden Authorization Revoked
description: 'Forbidden: Authorization revoked'
value:
code: 1008
message: 'Forbidden: Authorization revoked'
errors:
- 'Forbidden: Authorization revoked'
scope:
summary: Forbidden Scope
description: 'Forbidden: Missing required scope'
value:
code: 1009
message: 'Forbidden: Missing required scope'
errors:
- 'Forbidden: Missing required scope'
securityDefinitions:
JWT:
type: http
scheme: bearer
bearerScheme: JWT
in: header
description: All operations require a JSON Web Token after completing an [OAuth2 flow](#tag/Authentication).
PrivilegedClient:
type: http
scheme: bearer
bearerScheme: JWT
description: Some clients require special privileges to use operations. No additional scope is needed.
x-servers:
- url: https://api.boxc.com/v1
x-tagGroups:
- name: Overview
tags:
- Introduction
- Authentication
- RateLimit
- Paginate
- Changelog
- name: Operations
tags:
- CalculateDuty
- Classify
- Invoices
- Users
- ValidateAddress
- Webhooks
- name: Shipping
tags:
- Credentials
- CustomsProducts
- EntryPoints
- Estimate
- Labels
- Manifests
- Overpacks
- Shipments
- Track
- name: Fulfillment
tags:
- Inbound
- Orders
- Products
- Shops
- Warehouses
- name: Returns
tags:
- Reshipments
- Returns
- name: Data
tags:
- CarrierCredentials
- DangerousGoods
- Errors
- Languages
- CarrierParameters
- ReturnsProcess
- TrackingEvents