Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
x-logo:
url: https://storage.googleapis.com/boxc_cdn/public/boxc-logo.png
altText: BoxC
title: BoxC CalculateDuty Shipments 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.
'
servers:
- url: https://api.boxc.com/v1
tags:
- name: Shipments
x-displayName: Shipments
description: 'The Shipments resource allows a user to create, update, retrieve, and delete shipments. Only test shipments and shipments without labels can be deleted. Shipments with uncancelled or processed labels cannot be updated. All shipments require address verification on the shipping address. Cancelling a label will refund the cost. Test shipments and shipments without labels are routinely purged from the system.
There are some weight and volumetric constraints for shipments that is dependant on the route. For example, if a Shipment''s length + girth is greater than a certain size then the user is charged an additional fee per KG. The length is the measurement of the longest dimension, and girth is the distance around the thickest part (perpendicular to the length). If the Shipment''s weight or volume exceeds the limit for a route an error will be returned.
**Note:** Set the `overpack_id` to null when unassigning it from an overpack. You won''t be allowed to update a labelled shipment beyond that.
'
paths:
/shipments:
get:
tags:
- Shipments
summary: GET /shipments
description: Retrieves a paginated list of shipments.
operationId: getShipments
security:
- JWT:
- read_shipments
parameters:
- in: query
name: created_min
description: The inclusive date to begin the search.
required: false
schema:
type: string
format: YYYY-MM-DD
default: null
- in: query
name: created_max
description: The inclusive date to end the search.
required: false
schema:
type: string
format: YYYY-MM-DD
default: null
- in: query
name: labeled
description: Filter to return only shipments that have labels.
required: false
schema:
type: string
enum:
- 'yes'
- 'no'
- both
default: both
- in: query
name: limit
description: The number of results to return.
required: false
schema:
type: integer
default: 50
maximum: 100
minimum: 50
- in: query
name: order
description: The sort order of the results.
required: false
schema:
type: string
enum:
- asc
- desc
default: desc
- in: query
name: order_number
description: Filter that searches for shipments by the order_number.
required: false
schema:
type: string
default: null
- in: query
name: overpack_id
description: Filter that searches for shipments by their overpack ID.
required: false
schema:
type: integer
default: null
- in: query
name: packed
description: Filter to return only shipments that are in an overpack.
required: false
schema:
type: string
enum:
- 'yes'
- 'no'
- both
default: both
- in: query
name: page_token
description: Used for selecting the page after the initial query.
required: false
schema:
type: string
default: null
- in: query
name: processed
description: Filter to return only shipments that are processed.
required: false
schema:
type: string
enum:
- 'yes'
- 'no'
- both
default: both
- in: query
name: tracking_number
description: Filter that searches for shipments by tracking number. Date filters are ignored if this is provided.
required: false
schema:
type: string
default: null
maxLength: 40
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n -H \"Accept: application/json\" \\\n https://api.boxc.com/v1/shipments\\?limit=50\\&order=desc\\&labeled=both\\&packed=both\\&processed=both\\&comments=1+phone+case\\&tracking_number=\n"
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
shipments:
type: array
items:
$ref: '#/components/schemas/Shipment'
next_page:
type: string
description: Page token
example: ZGF0ZV9lbmQ9MjAyMy0wNy0yOCZsaW1pdD01MCZvcmRlcj1kZXNjJnBhZ2U9MSZsYXN0X2lkPTE1Mzg0Nw
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/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: '#/components/schemas/Unauthorized'
'403':
$ref: '#/components/schemas/Forbidden'
'429':
$ref: '#/components/schemas/RateLimit'
post:
tags:
- Shipments
summary: POST /shipments
description: Creates a shipment.
operationId: addShipment
security:
- JWT:
- write_shipments
x-codeSamples:
- lang: cURL
label: cURL Example 1
source: "curl -X POST https://api.boxc.com/v1/shipments \\\n -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"shipment\": {\n \"carrier\": null,\n \"carrier_params\": null,\n \"comments\": [\n \"Test comment\"\n ],\n \"cod\": {\n \"amount\": 0\n },\n \"consignee\": {\n \"name\": \"Addressee John\",\n \"phone\": \"555-987-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\": \"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 \"create_label\": false,\n \"currency\": \"USD\",\n \"entry_point\": \"TEST01\",\n \"exit_point\": \"ORD\",\n \"freight_charge\": {\n \"amount\": 12.26,\n \"currency\": \"USD\"\n },\n \"from\": null,\n \"height\": 3.9,\n \"ignore_bad_address\": false,\n \"insurance\": false,\n \"irregular\": false,\n \"is_return\": false,\n \"length\": 10,\n \"line_items\": [\n {\n \"coo\": \"CN\",\n \"currency\": \"USD\",\n \"description\": \"Phone case\",\n \"dg_code\": null,\n \"hts_code\": null,\n \"origin_description\": \"手机外壳\",\n \"product_id\": null,\n \"quantity\": 1,\n \"url\": null,\n \"supplier\": \"US23123131\",\n \"value\": 9.95,\n \"weight\": 0.276\n }\n ],\n \"nature_type\": null,\n \"service\": \"BoxC Parcel\",\n \"signature_confirmation\": false,\n \"terms\": \"DDU\",\n \"test\": true,\n \"to\": {\n \"company_name\": null,\n \"name\": \"John Smith\",\n \"phone\": \"555-123-456\",\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 \"weight\": 0.4,\n \"width\": 5\n }\n }'\n"
- lang: cURL
label: cURL Example 2
source: "curl -X POST https://api.boxc.com/v1/shipments \\\n -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"shipment\": {\n \"carrier\": \"PostPlus\",\n \"comments\": [\n \"SKU #10292301\"\n ],\n \"consignee\": {\n \"name\": \"Addressee John\",\n \"phone\": \"555-987-6543\",\n \"email\": null,\n \"id\": null,\n \"street1\": \"123 Main Ave.\",\n \"street2\": null,\n \"city\": \"Amsterdam\",\n \"province\": null,\n \"postal_code\": \"1234 AB\",\n \"country\": \"NL\"\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\": \"Indianapolis\",\n \"province\": \"IN\",\n \"postal_code\": 60601,\n \"country\": \"US\"\n },\n \"create_label\": false,\n \"currency\": \"USD\",\n \"entry_point\": \"TEST01\",\n \"exit_point\": \"AMS\",\n \"from\": null,\n \"height\": 16.00,\n \"ignore_bad_address\": false,\n \"insurance\": false,\n \"irregular\": false,\n \"is_return\": false,\n \"length\": 13,\n \"line_items\": [\n {\n \"coo\": \"CN\",\n \"currency\": \"USD\",\n \"description\": \"Phone case\",\n \"dg_code\": null,\n \"hts_code\": null,\n \"origin_description\": \"手机外壳\",\n \"product_id\": null,\n \"quantity\": 1,\n \"supplier\": \"US23123131\",\n \"url\": null,\n \"value\": 19.95,\n \"weight\": 0.276\n }\n ],\n \"nature_type\": null,\n \"order_number\": \"23018721-ABC\",\n \"overpack_id\": 1291028,\n \"service\": \"BoxC Parcel\",\n \"signature_confirmation\": false,\n \"terms\": \"DDP\",\n \"test\": true,\n \"to\": {\n \"company_name\": null,\n \"name\": \"John Smith\",\n \"phone\": \"555-888-4444\",\n \"email\": \"john@example.com\",\n \"street1\": \"108 N WESTGATE WAY\",\n \"street2\": null,\n \"city\": \"Amsterdam\",\n \"province\": null,\n \"postal_code\": \"1234 AB\",\n \"country\": \"NL\"\n },\n \"weight\": 0.276,\n \"width\": 10,\n \"zonos_customer_id\": \"<YOUR ZONOS ID>\"\n }\n }'\n"
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
shipment:
$ref: '#/components/schemas/Shipment'
required:
- shipment
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
shipment:
$ref: '#/components/schemas/Shipment'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/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.
notFound:
summary: Not Found
description: Credential not found
value:
code: 1450
message: Credential not found
errors:
- Credential not found
languageError:
summary: Entry Point Language
description: Origin description must be in the entry point's language
value:
code: 1222
message: Origin description must be in the entry point's language
errors:
- Origin description must be in the entry point's language
descriptionError:
summary: Description Unacceptable
description: Description isn't acceptable
value:
code: 1223
message: Description isn't acceptable
errors:
- Description isn't acceptable
htsCode:
summary: HTS Code Error
description: Line item HTS code error with a reason
value:
code: 1224
message: 'HTS Code error: code is too long after validation (''0102294064220'')'
errors:
- 'HTS Code error: code is too long after validation (''0102294064220'')'
noRoutes:
summary: Bad Routes Request
description: No routes found
value:
code: 1050
message: No routes found
errors:
- No routes found
addressError:
summary: Bad Address Request
description: Address Error
value:
code: 1012
message: Address Error
errors:
- Address Error
hsCodeMissing:
summary: Missing Requirements
description: An HS Code and description are required for all products.
value:
code: 1215
message: Shipment requires an HS Code and description for all line items
errors:
- Shipment requires an HS Code and description for all line items
dutyRates:
summary: Duty Rates
description: Unable to get tax and/or duty rates for this shipment
value:
code: 1243
message: Unable to get tax and/or duty rates for this shipment
errors:
- Unable to get tax and/or duty rates for this shipment
'401':
$ref: '#/components/schemas/Unauthorized'
'403':
$ref: '#/components/schemas/Forbidden'
'429':
$ref: '#/components/schemas/RateLimit'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
examples:
internalServerError:
summary: Internal Server Error
description: Error while checking for denied parties
value:
code: 1010
message: Error while checking for denied parties
errors:
- Error while checking for denied parties
labelError:
summary: Server Error Creating Label
description: Label could not be created.
value:
code: 1203
message: Label could not be created.
errors:
- Label could not be created.
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/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.
/shipments/{id}:
get:
tags:
- Shipments
summary: GET /shipments/{id}
description: Gets a shipment by its `id`. Clients can print a generic BoxC shipment label by changing the `Accept` header to <em>application/pdf</em> or providing `type=PDF` in the query parameters. The label is not a carrier label and should only be used for internal operations.
operationId: getShipmentsById
security:
- JWT:
- read_shipments
parameters:
- name: Accept
in: header
required: false
schema:
type: string
example: application/pdf
enum:
- application/json
- application/pdf
description: Optionally download the generic shipment label.
- in: query
name: type
description: Allows a client to print the BoxC generic shipment label.
required: false
deprecated: true
example: PDF
schema:
type: string
enum:
- PDF
- name: id
in: path
description: The shipment ID
required: true
schema:
type: integer
x-codeSamples:
- lang: cURL
label: cURL JSON
source: "curl -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n -H \"Accept: application/json\" \\\n https://api.boxc.com/v1/shipments/{id}\n"
- lang: cURL
label: cURL PDF
source: "curl -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n -H \"Accept: application/pdf\" \\\n https://api.boxc.com/v1/shipments/{id}\n"
responses:
'200':
description: Returns application/json or a PDF depending on the Accept request header.
content:
application/json:
schema:
type: object
properties:
shipment:
$ref: '#/components/schemas/Shipment'
application/pdf:
type: string
'401':
$ref: '#/components/schemas/Unauthorized'
'403':
$ref: '#/components/schemas/Forbidden'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
examples:
notFound:
summary: Not Found
description: Shipment not found
value:
code: 1210
message: Shipment not found
errors:
- Shipment not found
'429':
$ref: '#/components/schemas/RateLimit'
put:
tags:
- Shipments
summary: PUT /shipments/{id}
description: Updates a shipment. Only shipments with no labels or cancelled labels can be updated.
operationId: updateShipment
security:
- JWT:
- write_shipments
parameters:
- name: id
in: path
description: The shipment ID
required: true
schema:
type: integer
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -X PUT https://api.boxc.com/v1/shipments/{id} \\\n -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"shipment\": {\n \"carrier\": \"PostPlus\",\n \"carrier_params\": null,\n \"comments\": [\n \"SKU #10292301\"\n ],\n \"cod: {\n \"amount\": 0\n },\n \"consignee\": {\n \"name\": \"Addressee John\",\n \"phone\": \"555-987-6543\",\n \"email\": null,\n \"id\": null,\n \"street1\": \"2959 ANCHOR DR\",\n \"street2\": null,\n \"city\": \"Amsterdam\",\n \"province\": null,\n \"postal_code\": \"1234 AB\",\n \"country\": \"NL\"\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\": \"Indianapolis\",\n \"province\": \"IN\",\n \"postal_code\": 60601,\n \"country\": \"US\"\n },\n \"create_label\": false,\n \"currency\": \"USD\",\n \"entry_point\": \"TEST01\",\n \"exit_point\": \"AMS\",\n \"freight_charge\": {\n \"amount\": 12.26,\n \"currency\": \"USD\"\n },\n \"from\": null,\n \"height\": 16.00,\n \"ignore_bad_address\": false,\n \"insurance\": false,\n \"irregular\": false,\n \"is_return\": false,\n \"length\": 13,\n \"line_items\": [\n {\n \"coo\": \"CN\",\n \"currency\": \"USD\",\n \"description\": \"Phone case\",\n \"dg_code\": null,\n \"hts_code\": null,\n \"origin_description\": \"手机外壳\",\n \"product_id\": null,\n \"quantity\": 1,\n \"supplier\": \"US23123131\",\n \"url\": null,\n \"value\": 19.95,\n \"weight\": 0.276\n }\n ],\n \"order_number\": \"23018721-ABC\",\n \"overpack_id\": 1291028,\n \"service\": \"BoxC Parcel\",\n \"signature_confirmation\": false,\n \"terms\": \"DDP\",\n \"test\": false,\n \"to\": {\n \"company_name\": null,\n \"name\": \"John Smith\",\n \"phone\": \"555-888-4444\",\n \"email\": \"john@example.com\",\n \"street1\": \"108 N WESTGATE WAY\",\n \"street2\": null,\n \"city\": \"Amsterdam\",\n \"province\": null,\n \"postal_code\": \"1234 AB\",\n \"country\": \"NL\"\n },\n \"weight\": 0.276,\n \"width\": 10,\n \"zonos_customer_id\": \"<YOUR ZONOS ID>\"\n }\n }'\n"
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
shipment:
$ref: '#/components/schemas/Shipment'
required:
- shipment
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
shipment:
$ref: '#/components/schemas/Shipment'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/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
description: Shipment has uncancelled or processed labels
value:
code: 1201
message: Shipment has uncancelled or processed labels
errors:
- Shipment has uncancelled or processed labels
notFound:
summary: Not Found
description: Credential not found
value:
code: 1450
message: Credential not found
errors:
- Credential not found
languageError:
summary: Entry Point Language
description: Origin description must be in the entry point's language
value:
code: 1222
message: Origin description must be in the entry point's language
errors:
- Origin description must be in the entry point's language
descriptionError:
summary: Description Unacceptable
description: Description isn't acceptable
value:
code: 1223
message: Description isn't acceptable
errors:
- Description isn't acceptable
noRoutes:
summary: Bad Routes Request
description: No routes found
value:
code: 1050
message: No routes found
errors:
- No routes found
addressError:
summary: Bad Address Request
description: Address Error
value:
code: 1012
message: Address Error
errors:
- Address Error
hsCode:
summary: Missing Requirements
description: An HS Code and description are required for all products.
value:
code: 1215
message: Shipment requires an HS Code and description for all line items
errors:
- Shipment requires an HS Code and description for all line items
dutyRates:
summary: Duty Rates
description: Unable to get tax and/or duty rates for this shipment
value:
code: 1243
message: Unable to get tax and/or duty rates for this shipment
errors:
- Unable to get tax and/or duty rates for this shipment
'401':
$ref: '#/components/schemas/Unauthorized'
'403':
$ref: '#/components/schemas/Forbidden'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
examples:
notFound:
summary: Not Found
description: Shipment not found
value:
code: 1210
message: Shipment not found
errors:
- Shipment not found
'429':
$ref: '#/components/schemas/RateLimit'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
examples:
internalServerError:
summary: Internal Server Error
description: Error while checking for denied parties
value:
code: 1010
message: Error while checking for denied parties
errors:
- Error while checking for denied parties
labelError:
summary: Server Error Creating Label
description: Label could not be created.
value:
code: 1203
message: Label could not be created.
errors:
- Label could not be created.
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceUnavailable'
examples:
ServerError:
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.
delete:
tags:
- Shipments
summary: DELETE /shipments/{id}
description: Deletes a shipment.
operationId: deleteShipment
security:
- JWT:
- write_shipments
parameters:
- name: id
in: path
description: The shipment ID
required: true
schema:
type: integer
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -X DELETE https://api.boxc.com/v1/shipments/{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: '#/components/schemas/BadRequest'
examples:
cannotDelete:
summary: Bad Request
description: Shipment can't be deleted
value:
code: 1212
message: Shipment can't be deleted
errors:
- Shipment can't be deleted
cannotDeleteOverpack:
summary: Bad Request Overpack
description: Shipments that are linked to an overpack can't be deleted
value:
code: 1218
message: Shipments that are linked to an overpack can't be deleted
errors:
- Shipments that are linked to an overpack can't be deleted
'401':
$ref: '#/components/schemas/Unauthorized'
'403':
$ref: '#/components/schemas/Forbidden'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
examples:
notFound:
summary: Not Found
description: Shipment not found
value:
code: 1210
message: Shipment not found
errors:
- Shipment not found
'429':
$ref: '#/components/schemas/RateLimit'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
examples:
internalServerError:
summary: Internal Server Error
description: Shipment can't be deleted
value:
code: 1212
message: Shipment can't be deleted
errors:
- Shipment can't be deleted
/shipments/{id}/process:
put:
tags:
- Shipments
summary: PUT /shipments/{id}/process
description: Process a shipment with the final measured weight and dimensions. Useful for clients that process shipments at their own facilities. Only select clients are authorized to perform this action. This changes shipment status to <em>Processed</em> and can't be reversed.<p><strong>Note:</strong> Multi-package shipments can't be processed this way as of now.</p>
operationId: processShipment
security:
- JWT:
- write_shipments
PrivilegedClient: []
paramete
# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/boxc/refs/heads/main/openapi/boxc-shipments-api-openapi.yml