swagger: '2.0'
info:
x-logo:
url: https://storage.googleapis.com/boxc_cdn/public/boxc-logo.png
altText: BoxC
title: BoxC CalculateDuty Orders 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: Orders
x-displayName: Orders
description: 'The Orders resource allows you to create, read, update, and delete orders that are meant to be fulfilled by BoxC. If you wish to manually create an order for a third party shop you must provide the `shop.id` and `shop.order_id`. Neither property can be updated. The system will push tracking information to the shop when the order is fulfilled if both properties are set. Clients can force which warehouse is used for order fulfillment by setting the `warehouse.id` property.
### Order Status
The following table lists all possible states of an order indicated by its `status` property. Updating an order that is ''Ready'' will reset its status to ''Processing'' and restore product quantities until it''s processed by the system again.
| Status | Description |
|--------|-------------|
| Backordered | There is insufficient quantity for one or more line items. The system will change the status once more inventory is added. |
| Exception | There is a problem with the order such as missing or invalid information. The user must correct the problem before the order can be processed by the system. |
| Holding | The order is being delayed from processing by the user. |
| Processing | The order is waiting for the system to process it. Default state. |
| Ready | The order is assigned to a warehouse for packing and quantities were deducted. |
| Packing | One or more line items are being packed. <em>It can''t be edited in this state</em>. |
| Partial | The order was partially fulfilled. The remaining line items will be fulfilled when more inventory arrives. |
| Fulfilled | The order was completely fulfilled. |
| Archived | The system archives orders that were fulfilled at least 90 days in the past. |
### Pruning Orders
The system routinely prunes or closes out orders in the system more than **365 days** ago. The start time is based on the `placed_at` and not the `created` datetime. What happens to the order depends on its current state at the time of pruning.
- Unfulfilled (not Packing, Partial, Fulfilled) orders are deleted.
- Partially fulfilled orders (Holding, Packing, Partial) are bumped to Fulfilled.
- Orders in Packing have their unfulfilled line items and fulfillment objects deleted, and are bumped to Fulfilled.
'
paths:
/orders:
get:
tags:
- Orders
summary: GET /orders
description: Retrieves a paginated list of orders.
operationId: getOrders
consumes:
- application/json
produces:
- application/json
security:
- JWT:
- read_orders
parameters:
- in: query
name: created_min
description: The inclusive date to begin the search in YYYY-MM-DD format.
required: false
default: null
type: string
- in: query
name: created_max
description: The inclusive date to end the search in YYYY-MM-DD format.
required: false
type: string
default: null
- in: query
name: limit
description: The number of results to return.
required: false
type: integer
default: 50
minimum: 50
maximum: 100
- in: query
name: order
description: The sort order of the results.
required: false
type: string
default: desc
enum:
- asc
- desc
- in: query
name: page_token
description: Used for selecting the page after the initial query.
required: false
type: string
- in: query
name: product.id
description: Filter to return only orders containing the matching product.
required: false
type: integer
- in: query
name: shipping_address.name
description: Filter to return only orders matching the shipping addressee's name.
required: false
type: string
- in: query
name: shop.id
description: Filter to return only orders belonging to a particular shop you own.
required: false
type: string
- in: query
name: shop.order_id
description: Filter to return only orders with a matching shop order ID.
required: false
type: string
- in: query
name: status
description: Filter to return only orders with a particular status. Returns all by default.
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/orders\\?limit=50\\&order=desc\\&status=Processing\\&shop.id=\\&shop.order_id=\\&shipping_address.name=\\&product.id=\n"
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
orders:
type: array
items:
$ref: '#/definitions/Order'
next_page:
type: string
description: Page token. Set by the system.
example: ZGF0ZV9lbmQ9MjAyMy0wNy0yOCZsaW1pdD01MCZvcmRlcj1kZXNjJnBhZ2U9MSZsYXN0X2lkPTE1Mzg0Nw
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/definitions/BadRequest'
examples:
invalidToken:
summary: Bad Request Page Token
description: Invalid page token
value:
code: 1025
message: Invalid page token
errors:
- Invalid page token
invalidParameter:
summary: Bad Request Query Parameter
description: Query parameter is invalid
value:
code: 1031
message: Invalid query parameter
errors:
- Invalid query parameter
'401':
$ref: '#/definitions/Unauthorized'
'403':
$ref: '#/definitions/Forbidden'
'429':
$ref: '#/definitions/RateLimit'
post:
tags:
- Orders
summary: POST /orders
description: Creates an order.
operationId: addOrder
consumes:
- application/json
produces:
- application/json
security:
- JWT:
- write_orders
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -X POST https://api.boxc.com/v1/orders \\\n -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"order\": {\n \"consignee\": {\n \"name\": \"Addressee John\",\n \"phone\": \"555-444-7890\",\n \"email\": null,\n \"id\": null,\n \"street1\": \"2959 ANCHOR DR\",\n \"street2\": null,\n \"city\": \"MESQUITE\",\n \"province\": \"TX\",\n \"postal_code\": 75150,\n \"country\": \"US\"\n },\n \"consignor\": {\n \"name\": \"Generic Company, LLC\",\n \"phone\": \"555-123-4567\",\n \"email\": null,\n \"id\": null,\n \"street1\": \"1 WORLD WAY\",\n \"street2\": \"\",\n \"city\": \"SHENZHEN\",\n \"province\": \"GUANGDONG\",\n \"postal_code\": 518000,\n \"country\": \"CN\"\n },\n \"created\": \"2024-11-17 15:43:03\",\n \"exception_on_failure\": false,\n \"from\": {\n \"name\": \"My Company Name\",\n \"street1\": \"113 INTL BROADWAY\",\n \"street2\": \"\",\n \"city\": \"LOS ANGELES\",\n \"province\": \"CA\",\n \"postal_code\": \"91013\",\n \"country\": \"US\"\n },\n \"gift_message\": \"Thanks for the laughs. -Sansa\",\n \"ignore_bad_address\": false,\n \"insurance\": false,\n \"line_items\": [\n {\n \"quantity\": 1,\n \"sku\": \"<PRODUCT SKU>\",\n \"sold_for\": 9.95\n }\n ],\n \"packing_slip\": true,\n \"partial_fulfillment\": false,\n \"service\": \"BoxC Priority\",\n \"shop\": {\n \"id\": \"<YOUR SHOP ID>\",\n \"order_id\": <YOUR ORDER ID>\n },\n \"signature_confirmation\": false,\n \"status\": \"Processing\",\n \"terms\": \"DDU\",\n \"to\": {\n \"company_name\": null,\n \"name\": \"John Smith\",\n \"phone\": \"555-123-4562\",\n \"email\": \"john@example.com\",\n \"street1\": \"108 N WESTGATE WAY\",\n \"street2\": null,\n \"city\": \"WYLIE\",\n \"province\": \"TX\",\n \"postal_code\": \"75098\",\n \"country\": \"US\"\n },\n \"warehouse\": {\n \"id\": \"WH0SZ001\"\n },\n \"wholesale\": false\n }\n }'\n"
requestBody:
required: true
content:
application/json:
schema:
properties:
order:
$ref: '#/definitions/Order'
required:
- order
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
order:
$ref: '#/definitions/Order'
'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.
badRequest:
summary: Bad Request Inactive Shop
description: Shop is inactive
value:
code: 1374
message: Shop is inactive
errors:
- Shop is inactive
missingShop:
summary: Bad Shop Request
description: Shop not found
value:
code: 1370
message: Shop not found
errors:
- Shop not found
badOrderID:
summary: Bad Request Order ID
description: Duplicate shop.order_id
value:
code: 1326
message: Duplicate shop.order_id
errors:
- Duplicate shop.order_id
giftMessage:
summary: Bad Request Gift Message
description: Packing slip is required for a gift message
value:
code: 1340
message: Packing slip is required for a gift message
errors:
- Packing slip is required for a gift message
lineItems:
summary: Bad Request Line Items
description: Line items in the order must be unique
value:
code: 1325
message: Line items in the order must be unique
errors:
- Line items in the order must be unique
addressError:
summary: Bad Address Request
description: Address Error
value:
code: 1012
message: Address Error
errors:
- Address Error
missingSku:
summary: Bad Request Missing SKU
description: SKU does not exist in Shop
value:
code: 1330
message: SKU does not exist in Shop
errors:
- SKU does not exist in Shop
inactiveSku:
summary: Bad Request Inactive SKU
description: SKU is inactive
value:
code: 1331
message: SKU is inactive
errors:
- SKU is inactive
packaging:
summary: Bad Request Packaging
description: Packaging is not allowed in orders
value:
code: 1341
message: Packaging is not allowed in orders
errors:
- Packaging is not allowed in orders
'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: Order could not be created.
value:
code: 1323
message: Order could not be created.
errors:
- Order could not be created.
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/definitions/ServiceUnavailable'
examples:
internalServerError:
summary: Service Unavailable
description: Address resolution service unavailable at this time.
value:
code: 503
message: Address resolution service unavailable at this time.
errors:
- Address resolution service unavailable at this time.
/orders/{id}:
get:
tags:
- Orders
summary: GET /orders/{id}
description: Retrieves an order.
operationId: getOrdersById
consumes:
- application/json
produces:
- application/json
security:
- JWT:
- read_orders
parameters:
- name: id
in: path
description: The order ID
required: true
type: integer
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n -H \"Accept: application/json\" \\\n https://api.boxc.com/v1/orders/{id}\n"
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
order:
$ref: '#/definitions/Order'
'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: Order not found
value:
code: 1320
message: Order not found
errors:
- Order not found
'429':
$ref: '#/definitions/RateLimit'
put:
tags:
- Orders
summary: PUT /orders/{id}
description: Updates an order.
operationId: updateOrder
consumes:
- application/json
produces:
- application/json
security:
- JWT:
- write_orders
parameters:
- name: id
in: path
description: The order ID
required: true
type: integer
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -X PUT https://api.boxc.com/v1/orders/{id} \\\n -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"order\": {\n \"consignee\": {\n \"name\": \"Addressee John\",\n \"phone\": \"555-456-7890\",\n \"email\": null,\n \"id\": null,\n \"street1\": \"2959 ANCHOR DR\",\n \"street2\": null,\n \"city\": \"MESQUITE\",\n \"province\": \"TX\",\n \"postal_code\": 75150,\n \"country\": \"US\"\n },\n \"consignor\": {\n \"name\": \"Generic Company, LLC\",\n \"phone\": \"555-123-4567\",\n \"email\": null,\n \"id\": null,\n \"street1\": \"1 WORLD WAY\",\n \"street2\": \"\",\n \"city\": \"SHENZHEN\",\n \"province\": \"GUANGDONG\",\n \"postal_code\": 518000,\n \"country\": \"CN\"\n },\n \"from\": {\n \"name\": \"My Company Name\",\n \"street1\": \"113 INTL BROADWAY\",\n \"street2\": \"\",\n \"city\": \"LOS ANGELES\",\n \"province\": \"CA\",\n \"postal_code\": \"91013\",\n \"country\": \"US\"\n },\n \"gift_message\": \"Thanks for the laughs. -Sansa\",\n \"ignore_bad_address\": false,\n \"insurance\": false,\n \"line_items\": [\n {\n \"quantity\": 1,\n \"sku\": \"<PRODUCT SKU>\",\n \"sold_for\": 9.95\n }\n ],\n \"packing_slip\": true,\n \"partial_fulfillment\": false,\n \"service\": \"BoxC Priority\",\n \"shop\": {\n \"id\": \"<YOUR SHOP ID>\",\n \"name\": \"Appleseeds\",\n \"order_id\": <YOUR ORDER ID>,\n \"type\": \"BoxC\"\n },\n \"signature_confirmation\": false,\n \"status\": \"Processing\",\n \"terms\": \"DDU\",\n \"to\": {\n \"company_name\": null,\n \"name\": \"John Smith\",\n \"phone\": \"555-123-4562\",\n \"email\": \"john@example.com\",\n \"street1\": \"108 N WESTGATE WAY\",\n \"street2\": null,\n \"city\": \"WYLIE\",\n \"province\": \"TX\",\n \"postal_code\": \"75098\",\n \"country\": \"US\"\n },\n \"warehouse\": {\n \"id\": \"WH0SZ001\"\n },\n \"wholesale\": false\n }\n }'\n"
requestBody:
content:
application/json:
schema:
type: object
properties:
order:
type: object
properties:
consignee:
$ref: '#/definitions/Consignee'
consignor:
$ref: '#/definitions/Consignor'
from:
$ref: '#/definitions/From'
gift_message:
type: string
description: An optional message to be included on the packing slip if requested. ``` packing_slip ``` must be true.
maxLength: 128
example: Thanks for the laughs. -Sansa
ignore_bad_address:
type: boolean
description: Ignore shipping address verification errors. Setting this to true automatically declines insurance coverage unless the shipping address was valid, in which case the system will change this back to false. BoxC Priority addresses can't be ignored.
default: false
example: false
insurance:
type: boolean
description: Adds more insurance to shipments for a fee based on a percentage of the total value (including shipping cost) of the items in the fulfillment. By default shipments include insurance that covers up to $30 in total value even when insurance is false. Insurance is not available for the BoxC Post service and some accounts.
default: false
example: false
line_items:
description: An array of line items belonging to this order. Not all properties are present when searching.
type: array
items:
$ref: '#/definitions/OrderLineItem'
packing_slip:
type: boolean
description: Whether or not this order requires a packing slip for each fulfillment for an additional fee.
default: false
example: false
partial_fulfillment:
type: boolean
description: Whether or not this order should be fulfilled partially. If true, the warehouse will fulfill line items as their products arrive in the event there is insufficient quantity. This property can't be changed for orders that have already been partially fulfilled.
example: false
service:
type: string
description: The type of shipping service you want to use for this shipment. Not all services exist to all countries. If the selected service does not exist, the service will automatically be downgraded to the next available level of service.
enum:
- BoxC Post
- BoxC Parcel
- BoxC Plus
- BoxC Priority
default: BoxC Parcel
example: BoxC Priority
shop:
type: object
description: Information about the shop this order is linked to. Required. This object is immutable.
properties:
id:
type: string
description: The shop ID.
example: my-shop
name:
type: string
description: A user defined shop name.
maxLength: 32
example: Appleseeds
order_id:
type: string
description: The shop order ID if available. Not required. You must provide this for the system to push tracking information to the third party shop. Must be unique for the shop.
maxLength: 32
example: 30338272
type:
type: string
description: The shop type. Set by the system.
example: BoxC
required:
- id
signature_confirmation:
type: boolean
description: Request signature confirmation from the recipient upon delivery. Not available for all services or routes. An additional fee may apply.
default: false
example: false
status:
type: string
description: The order's current status. You may place an order in Holding to prevent fulfillment or Processing to fulfill the order.
enum:
- Holding
- Processing
example: Processing
terms:
description: The [Incoterms](https://en.wikipedia.org/wiki/Incoterms) for this shipment that affects which routes are available. If terms is not provided then the system will pick DDU or DDP if DDU is not available. DDP shipments will include tax and duty.
type: string
enum:
- DAP
- DDU
- DDP
default: DDU
example: DDU
to:
$ref: '#/definitions/To'
warehouse:
type: object
description: Declare the warehouse where you want this order fulfilled. It will not be fulfilled until sufficient quantity exists at the specified warehouse. View the [Warehouses resource](/#tag/Warehouses) for a list. Optional.
properties:
id:
type: string
description: The unique warehouse ID. Default is null which is default system behavior.
default: null
example: WH0SZ001
required:
- id
wholesale:
type: boolean
description: Indicates this order is for wholesale.
default: false
example: true
required:
- to
- consignor
- service
- line_items
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
order:
$ref: '#/definitions/Order'
'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.
cannotModify:
summary: Bad Modify Request
description: Order can't be modified in its current state
value:
code: 1321
message: Order can't be modified in its current state
errors:
- Order can't be modified in its current state
giftMessage:
summary: Bad Request Gift Message
description: Packing slip is required for a gift message
value:
code: 1340
message: Packing slip is required for a gift message
errors:
- Packing slip is required for a gift message
lineItems:
summary: Bad Request Line Items
description: Line items in the order must be unique
value:
code: 1325
message: Line items in the order must be unique
errors:
- Line items in the order must be unique
packaging:
summary: Bad Request Packaging
description: Packaging is not allowed in orders
value:
code: 1341
message: Packaging is not allowed in orders
errors:
- Packaging is not allowed in orders
inactiveSku:
summary: Bad Request Inactive SKU
description: SKU is inactive
value:
code: 1331
message: SKU is inactive
errors:
- SKU is inactive
missingSku:
summary: Bad Request Missing SKU
description: SKU does not exist in Shop
value:
code: 1330
message: SKU does not exist in Shop
errors:
- SKU does not exist in Shop
address:
summary: Bad Request Address Error
description: Address Error
value:
code: 1012
message: Address Error
errors:
- Address Error
'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: Order not found
value:
code: 1320
message: Order not found
errors:
- Order not found
'429':
$ref: '#/definitions/RateLimit'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/definitions/InternalServerError'
examples:
internalServerError:
summary: Internal Server Error
description: Order could not be updated
value:
code: 1324
message: Order could not be updated
errors:
- Order could not be updated
delete:
tags:
- Orders
summary: DELETE /orders/{id}
description: Deletes an order.
operationId: deleteOrder
consumes:
- application/json
produces:
- application/json
security:
- JWT:
- write_orders
parameters:
- name: id
in: path
description: The order ID
required: true
type: integer
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -X DELETE https://api.boxc.com/v1/orders/{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:
cannotModify:
summary: Bad Modify Request
description: Order can't be modified in its current state
value:
code: 1321
message: Order can't be modified in its current state
errors:
- Order can't be modified in its current state
cannotDelete:
summary: Bad Delete Request
description: Order can't be deleted
value:
code: 1322
message: Order can't be deleted
errors:
- Order 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: Order not found
value:
code: 1320
message: Order not found
errors:
- Order not found
'429':
$ref: '#/definitions/RateLimit'
/orders/status:
post:
tags:
- Orders
summary: POST /orders/status
description: Change the status of up to 100 orders at once. Returns the affected orders with their new status including those that can't be changed. It omits order
# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/boxc/refs/heads/main/openapi/boxc-orders-api-openapi.yml