Shipments
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 for the recipient unless manually overriden by the user. The cost for overriding the verification is $0 per label. 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.
overpack_id
to null when unassigning it from an overpack. You won't be allowed to update a labelled shipment beyond that.Actions
GET /shipments |
Retrieves a paginated list of shipments |
GET /shipments/{id} |
Retrieves a shipment |
POST /shipments |
Creates a shipment |
PUT /shipments/{id} |
Updates a shipment or removes a shipment from an overpack |
DELETE /shipments/{id} |
Deletes a shipment |
Properties
comments |
{ "comments": [ "SKU #10292301", "Comment line 2" ] }Array - Comments for the bottom of the label. Max of 3 items. Each item in the array is a String with max length of 80. Not required. |
consignee |
{ "consignee": { "name": "Addressee John", "phone": "555-456-7890", "email": null, "id": null, "street1": "2959 ANCHOR DR", "street2": null, "city": "MESQUITE", "province": "TX", "postal_code": "75150", "country": "US" } } Object (Optional). Details about the consignee / buyer. The system will use the shipping address as the consignee address if one isn't provided. Some countries require a tax / passport ID from the buyer. name: String(40) - The consignee's name. Required.phone: String(20) - The consignee's phone number. Conditional. email: String(64) - The consignee's email address. Conditional. id: String(20) - The consignee's Tax ID, GSTIN, Passport, ABN, Vendor ID, etc. Conditional. street1: String(40) - The consignee's street address. Required. street2: String(40) - Additional space for the consignee's street address such as apartment, condo, or unit number. Optional. city: String(40) - The consignee's city. Required. province: String(40) - The consignee's province or state code. Conditional. postal_code: String(10) - The consignee's postal code. Conditional. country: String(2) - The consignee's country in ISO 3166-1 alpha-2 format. Required. |
consignor |
{ "consignor": { "name": "Generic Company, LLC", "phone": "555-123-4567", "id": null, "street1": "1 WORLD WAY", "street2": "", "city": "SHENZHEN", "province": "GUANGDONG", "postal_code": "518000", "country": "CN" } } Address and phone number for the consignor (sender) which is used for customs clearance. Required. name: String(40) - The consignor's name. Required.phone: String(20) - The consignor's phone number. Required. id: String(20) - The consignor's Tax ID, GSTIN, Passport, ABN, Vendor ID, etc. Optional. street1: String(40) - The consignor's street address. Required. street2: String(40) - Additional space for the consignor's street address such as apartment, condo, or unit number. Optional. city: String(40) - The consignor's city. Required. province: String(40) - The consignor's province or state code. Optional. postal_code: String(10) - The consignor's postal code. Optional. country: String(2) - The consignor's country in ISO 3166-1 alpha-2 format. Required. |
create_label |
|
created |
|
entry_point |
String - The drop off location for this shipment. Determines the shipping rates and routing. Required. See Entry Points for a list of codes. |
errors |
{ "errors": { "code": 1080, "http_status": 402, "message": "Insufficient funds", "status": "error" } } Object - This property is returned if and only if |
from |
{ "from": { "name": "My Company Name", "street1": "113 INTL BROADWAY", "street2": "", "city": "LOS ANGELES", "province": "CA", "postal_code": "91013", "country": "US" } } This will appear as the return address on labels. Optional. A default return address will be used if one isn't provided in the request.
name: String(40) - Can be a sender's name or company name. Required. |
height |
|
id |
|
irregular |
|
label |
{ "label": { "cancelled": false, "carrier": "USPS", "chargeable_weight": 0.284, "cost": 3.56, "created": "2015-04-30 18:22:00", "delivery_date": "2015-09-15", "events": [ { "time": "2015-09-15 12:46:04", "city": "New York City", "province": "NY", "postal_code": "10001", "code": 200, "description": "DELIVERED" }, { "...": "..." } ], "id": 4248261, "is_ready": true, "override_fee": 0, "oversize_fee": 0, "processed": true, "processed_date": "2015-05-02", "processed_weight": 0.284, "service": "BoxC Parcel", "status": "Delivered", "tax": 0, "tracking_number": "9261299991753900000290" } }Object - The Label created for this shipment. If multiple labels were created, it will return the uncancelled one. Only present when searching shipments. Tracking events are only provided if a single shipment is returned. Set by the system. |
labels |
{ "labels": [ { "...": "..." } ] }Array - A list of all labels created for this shipment. Only present when requesting a single shipment. See the label property for details about the object. Set by the system. |
length |
|
line_items |
{ "line_items": [ { "coo": "CN", "currency": "USD", "description": "Phone case", "dg_code": null, "hts_code": null, "origin_description": "\u624b\u673a\u5916\u58f3", "quantity": 2, "weight": 0.235, "value": 9.95 } ] }Array (Required) - Contents of the shipment.
|
overpack_id |
|
override |
|
service |
|
signature_confirmation |
|
terms |
|
test |
|
to |
{ "to": { "company_name": null, "name": "John Smith", "phone": "555-123-4562", "email": "john@gmail.com", "street1": "108 N WESTGATE WAY", "street2": null, "city": "WYLIE", "province": "TX", "postal_code": "75098", "country": "US" } } The recipient's shipping address. This may or may not be the same as the consignee. Required. company_name: String(40) - The company name. Not required.name: String(40) - The recipient's name. Required. phone: String(20) - The recipient's phone number. Conditional. email: String(64) - The recipient's e-mail address. Conditional. street1: String(40) - The recipient's street address. Required. street2: String(40) - Additional space for the recipient's street address. Not required. city: String(40) - The recipient's city. Required. province: String(40) - The recipient's province or state. Required. postal_code: String(10) - The recipient's postal code or ZIP Code. Required. country: String(2) - The recipient's country in ISO 3166-1 alpha-2 format. Required. |
total_cost |
|
updated |
|
verified |
|
volumetric_weight |
|
weight |
|
width |
|
comments |
Filter that searches each item in comments for an exact match. Default is null. |
date_start |
The inclusive date to begin the search in YYYY-MM-DD format. Default is 90 days ago. |
date_end |
The inclusive date to end the search in YYYY-MM-DD format. Default is now. |
labeled |
Filter to return only shipments that have labels. Options are "yes", "no", or "both" (default). |
limit |
The number of results to return. Max: 100. Default: 50. |
order |
The order of the results. Options are "asc" for ascending, or "desc" (default) for descending. |
packed |
Filter to return only shipments that are in an overpack. Options are "yes", "no", or "both" (default). |
page |
The page number of the results. Default is 1. |
processed |
Filter to return only shipments that are processed. Options are "yes", "no", or "both" (default). |
to.name |
Filter that searches by recipient name. Default is null. |
overpack_id |
Filter that searches for shipments by their overpack_id. Default is null. |
GET /shipments
date_start=2015-04-01&date_end=2015-04-30&page=2=&limit=100&order=desc \ &labeled=both&packed=both&processed=both&comments=1+phone+case
HTTP/1.1 200 OK
{ "shipments": [ { "comments": [ "This is a comment" ], "consignee": { "name": "Addressee John", "phone": "555-456-7890", "email": null, "id": null, "street1": "2959 ANCHOR DR", "street2": null, "city": "MESQUITE", "province": "TX", "postal_code": "75150", "country": "US" }, "consignor": { "name": "Generic Company, LLC", "phone": "555-123-4567", "id": null, "street1": "1 WORLD WAY", "street2": "", "city": "SHENZHEN", "province": "GUANGDONG", "postal_code": "518000", "country": "CN" }, "created": "2015-04-30 18:21:22", "entry_point": "CANI01", "from": { "name": "My Company Name", "street1": "113 INTL BROADWAY", "street2": "", "city": "LOS ANGELES", "province": "CA", "postal_code": "91013", "country": "US" }, "height": 3.5, "id": 1019, "irregular": false, "label": { "cancelled": false, "carrier": "USPS", "chargeable_weight": 0.284, "cost": 3.56, "created": "2015-04-30 18:22:00", "delivery_date": null, "exit_point": "LAX", "id": 898212, "is_ready": true, "override_fee": 0, "oversize_fee": 0, "processed": true, "processed_date": "2015-05-02", "processed_weight": 0.284, "service": "BoxC Parcel", "status": "En Route", "tax": 0, "tracking_number": "9261299991753900000290" }, "length": 10, "line_items": [ { "coo": "CN", "currency": "USD", "description": "Phone case", "dg_code": null, "hts_code": null, "origin_description": "\u624b\u673a\u5916\u58f3", "quantity": 2, "weight": 0.235, "value": 9.95 } ], "overpack_id": 201921, "override": false, "terms": "DDU", "service": "BoxC Parcel", "signature_confirmation": true, "test": false, "to": { "company_name": null, "name": "John Smith", "phone": "555-123-4562", "email": "john@gmail.com", "street1": "108 N Westgate Way", "street2": null, "city": "Wylie", "province": "TX", "postal_code": "75098", "country": "US" }, "total_cost": 3.56, "updated": "2015-04-30 18:21:22", "verified": true, "volumetric_weight": 0.088, "weight": 0.325, "width": 5 }, { "id": 1001, "...": "..." } ], "total_pages": 2, "total_shipments": 120 }
GET /shipments/1014
HTTP/1.1 200 OK
{ "shipment": { "comments": [ "This is a comment" ], "consignee": { "name": "Addressee John", "phone": "555-456-7890", "email": null, "id": null, "street1": "2959 ANCHOR DR", "street2": null, "city": "MESQUITE", "province": "TX", "postal_code": "75150", "country": "US" }, "consignor": { "name": "Generic Company, LLC", "phone": "555-123-4567", "id": null, "street1": "1 WORLD WAY", "street2": "", "city": "SHENZHEN", "province": "GUANGDONG", "postal_code": "518000", "country": "CN" }, "created": "2015-04-30 18:21:59", "entry_point": "SZXI01", "from": { "name": "My Company Name", "street1": "113 INTL BROADWAY", "street2": "", "city": "LOS ANGELES", "province": "CA", "postal_code": "91013", "country": "US" }, "height": 3.5, "id": 1014, "irregular": false, "labels": [ { "cancelled": false, "carrier": "USPS", "chargeable_weight": 0.284, "cost": 3.56, "created": "2015-04-30 18:22:00", "delivery_date": null, "events": [], "exit_point": "CVG", "id": 898212, "is_ready": true, "override_fee": 0, "oversize_fee": 0, "processed": true, "processed_date": "2015-04-05", "processed_weight": 0.284, "service": "BoxC Parcel", "status": "En Route", "tax": 0, "tracking_number": "9261299991753900000290" } ], "length": 10, "line_items": [ { "coo": "CN", "currency": "USD", "description": "Phone case", "dg_code": null, "hts_code": null, "origin_description": "\u624b\u673a\u5916\u58f3", "quantity": 2, "weight": 0.235, "value": 9.95 } ], "overpack_id": null, "override": false, "service": "BoxC Parcel", "signature_confirmation": false, "terms": "DDU", "test": false, "to": { "company_name": null, "name": "John Smith", "phone": "555-123-4562", "email": "john@gmail.com", "street1": "108 N Westgate Way", "street2": null, "city": "Wylie", "province": "TX", "postal_code": "75098", "country": "US" }, "total_cost": 3.56, "updated": "2015-04-30 18:21:59", "verified": true, "volumetric_weight": 0.088, "weight": 0.325, "width": 5 } }
POST /shipments
{ "shipment": { "comments": [ "This is a comment" ], "consignee": { "name": "Addressee John", "phone": "555-456-7890", "email": null, "id": null, "street1": "2959 ANCHOR DR", "street2": null, "city": "MESQUITE", "province": "TX", "postal_code": "75150", "country": "US" }, "create_label": false, "from": { "name": "My Company Name", "street1": "113 INTL BROADWAY", "street2": "", "city": "LOS ANGELES", "province": "CA", "postal_code": "91013", "country": "US" }, "height": 3.9, "irregular": false, "length": 10, "line_items": [ { "coo": "CN", "currency": "USD", "description": "Phone case", "dg_code": null, "hts_code": null, "origin_description": "\u624b\u673a\u5916\u58f3", "quantity": 2, "weight": 0.235, "value": 9.95 } ], "override": false, "service": "BoxC Parcel", "signature_confirmation": false, "terms": "DDU", "test": true, "to": { "company_name": null, "name": "John Smith", "phone": "555-123-456", "email": "john@gmail.com", "street1": "108 N Westgate Way", "street2": null, "city": "Wylie", "province": "TX", "postal_code": "75098", "country": "US" }, "weight": 0.4, "width": 5 } }
HTTP/1.1 201 Created
{ "shipment": { "comments": [ "This is a comment" ], "consignee": { "name": "Addressee John", "phone": "555-456-7890", "email": null, "id": null, "street1": "2959 ANCHOR DR", "street2": null, "city": "MESQUITE", "province": "TX", "postal_code": "75150", "country": "US" }, "consignor": { "name": "Generic Company, LLC", "phone": "555-123-4567", "id": null, "street1": "1 WORLD WAY", "street2": "", "city": "SHENZHEN", "province": "GUANGDONG", "postal_code": "518000", "country": "CN" }, "created": "2015-05-04 08:10:24", "entry_point": "SZXI01", "from": { "name": "My Company Name", "street1": "113 INTL BROADWAY", "street2": "", "city": "LOS ANGELES", "province": "CA", "postal_code": "91013", "country": "US" }, "height": 3, "id": 1015, "irregular": false, "labels": [], "length": 10, "line_items": [ { "coo": "CN", "currency": "USD", "description": "Phone case", "dg_code": null, "hts_code": null, "origin_description": "\u624b\u673a\u5916\u58f3", "quantity": 2, "weight": 0.235, "value": 9.95 } ], "overpack_id": null, "override": false, "service": "BoxC Parcel", "signature_confirmation": false, "terms": "DDU", "test": true, "to": { "company_name": null, "name": "John Smith", "phone": "555-123-456", "email": "john@gmail.com", "street1": "108 N Westgate Way", "street2": null, "city": "Wylie", "province": "TX", "postal_code": "75098", "country": "US" }, "total_cost": 3.8, "updated": "2015-05-04 08:10:24", "verified": true, "volumetric_weight": 0.088, "weight": 0.4, "width": 5.25 } }
PUT /shipments/1014
{ "shipment": { "comments": [ "This is a comment", "This is the second comment" ], "consignee": { "name": "Addressee John", "phone": "555-456-7890", "email": null, "id": null, "street1": "2959 ANCHOR DR", "street2": null, "city": "MESQUITE", "province": "TX", "postal_code": "75150", "country": "US" }, "consignor": { "name": "Generic Company, LLC", "phone": "555-123-4567", "id": null, "street1": "1 WORLD WAY", "street2": "", "city": "SHENZHEN", "province": "GUANGDONG", "postal_code": "518000", "country": "CN" }, "create_label": false, "height": 3.5, "length": 10, "line_items": [ { "coo": "CN", "currency": "USD", "description": "Phone case", "dg_code": null, "hts_code": null, "origin_description": "\u624b\u673a\u5916\u58f3", "quantity": 2, "weight": 0.235, "value": 9.95 } ], "override": true, "service": "BoxC Parcel", "signature_confirmation": false, "terms": "DDU", "to": { "company_name": null, "name": "John Smith", "phone": "555-123-456", "email": "john@gmail.com", "street1": "101 Victory Blvd", "street2": "Ste 210", "city": "Woodland Hills", "province": "CA", "postal_code": "94101", "country": "US" }, "weight": 0.234, "width": 5 } }
HTTP/1.1 200 OK
{ "shipment": { "comments": [ "This is a comment", "This is the second comment" ], "consignee": { "name": "Addressee John", "phone": "555-456-7890", "email": null, "id": null, "street1": "2959 ANCHOR DR", "street2": null, "city": "MESQUITE", "province": "TX", "postal_code": "75150", "country": "US" }, "consignor": { "name": "Generic Company, LLC", "phone": "555-123-4567", "id": null, "street1": "1 WORLD WAY", "street2": "", "city": "SHENZHEN", "province": "GUANGDONG", "postal_code": "518000", "country": "CN" }, "created": "2015-05-04 10:10:10", "entry_point": "SZXI01", "from": { "name": "My Company Name", "street1": "113 INTL BROADWAY", "street2": "", "city": "LOS ANGELES", "province": "CA", "postal_code": "91013", "country": "US" }, "height": 3.5, "id": 1014, "irregular": false, "labels": [], "length": 10, "line_items": [ { "coo": "CN", "currency": "USD", "description": "Phone case", "dg_code": null, "hts_code": null, "origin_description": "\u624b\u673a\u5916\u58f3", "quantity": 2, "weight": 0.235, "value": 9.95 } ], "overpack_id": 123456, "override": true, "service": "BoxC Parcel", "signature_confirmation": false, "terms": "DDU", "test": false, "to": { "company_name": null, "name": "John Smith", "phone": "555-123-456", "email": "john@gmail.com", "street1": "101 Victory Blvd", "street2": "Ste 210", "city": "Woodland Hills", "province": "CA", "postal_code": "94101", "country": "US" }, "total_cost": 3.12, "verified": false, "volumetric_weight": 0.088, "weight": 0.234, "width": 5 } }
PUT /shipments/1000017
{ "shipment": { "comments": [ "", "", "" ], "consignee": { "name": "Justin Pope", "phone": null, "email": "justin@boxc.com", "id": null, "street1": "490 SUSSEX DR", "street2": null, "city": "OTTAWA", "province": "ON", "postal_code": "K1N 1G8", "country": "CA" }, "consignor": { "name": "My Company", "phone": "214-862-6911", "id": null, "street1": "1 World Way", "street2": "", "city": "Los Angeles", "province": "CA", "postal_code": "94041", "country": "US" }, "created": "2020-08-26 16:39:47", "entry_point": "LAXI01", "from": { "name": "My Company 1", "street1": "211-6500 SILVER DART DR, CORE B", "street2": "P.O. BOX 6033 amf", "city": "MISSISSAUGA", "province": "ON", "postal_code": "L5P 1B2", "country": "CA" }, "height": 10, "id": "1000017", "irregular": false, "labels": [ { "cancelled": false, "carrier": "SkyPostal", "chargeable_weight": "0.250", "cost": 7.1, "created": "2020-08-26 16:59:13", "delivery_date": null, "events": [], "exit_point": "YYZ", "id": "875", "override_fee": "0.00", "oversize_fee": "0.00", "processed": false, "processed_date": null, "processed_weight": null, "service": "BoxC Parcel", "status": "Pending", "tax": "0.00", "tracking_number": "2KNG118400631803007035400000" } ], "length": 5, "line_items": [ { "coo": "US", "value": "10", "weight": ".25", "dg_code": null, "currency": "USD", "hts_code": null, "quantity": "1", "description": "Books", "origin_description": "Books" } ], "overpack_id": null, "override": false, "service": "BoxC Parcel", "signature_confirmation": false, "terms": "DDP", "test": false, "to": { "company_name": null, "name": "Justin Pope", "phone": null, "email": "justin@boxc.com", "street1": "490 SUSSEX DR", "street2": null, "city": "OTTAWA", "province": "ON", "postal_code": "K1N 1G8", "country": "CA" }, "total_cost": 7.1, "updated": "2020-08-26 17:09:35", "verified": true, "volumetric_weight": "0.083", "weight": 0.25, "width": 10 } }
HTTP/1.1 200 OK
{ "shipment": { "comments": [ "", "", "" ], "consignee": { "name": "Justin Pope", "phone": null, "email": "justin@boxc.com", "id": null, "street1": "490 SUSSEX DR", "street2": null, "city": "OTTAWA", "province": "ON", "postal_code": "K1N 1G8", "country": "CA" }, "consignor": { "name": "My Company", "phone": "214-862-6911", "id": null, "street1": "1 World Way", "street2": "", "city": "Los Angeles", "province": "CA", "postal_code": "94041", "country": "US" }, "created": "2020-08-26 16:39:47", "entry_point": "LAXI01", "from": { "name": "My Company 1", "street1": "211-6500 SILVER DART DR, CORE B", "street2": "P.O. BOX 6033 amf", "city": "MISSISSAUGA", "province": "ON", "postal_code": "L5P 1B2", "country": "CA" }, "height": 10, "id": "1000017", "irregular": false, "labels": [ { "cancelled": false, "carrier": "SkyPostal", "chargeable_weight": "0.250", "cost": 7.1, "created": "2020-08-26 16:59:13", "delivery_date": null, "events": [], "exit_point": "YYZ", "id": "875", 'is_ready' => true, "override_fee": "0.00", "oversize_fee": "0.00", "processed": false, "processed_date": null, "processed_weight": null, "service": "BoxC Parcel", "status": "Pending", "tax": "0.00", "tracking_number": "2KNG118400631803007035400000" } ], "length": 5, "line_items": [ { "coo": "US", "value": "10", "weight": ".25", "dg_code": null, "currency": "USD", "hts_code": null, "quantity": "1", "description": "Books", "origin_description": "Books" } ], "overpack_id": null, "override": false, "service": "BoxC Parcel", "signature_confirmation": false, "terms": "DDP", "test": false, "to": { "company_name": null, "name": "Justin Pope", "phone": null, "email": "justin@boxc.com", "street1": "490 SUSSEX DR", "street2": null, "city": "OTTAWA", "province": "ON", "postal_code": "K1N 1G8", "country": "CA" }, "total_cost": 7.1, "updated": "2020-08-26 17:09:35", "verified": true, "volumetric_weight": "0.083", "weight": 0.25, "width": 10, "carton_id": null } }
DELETE /shipments/12492
HTTP/1.1 200 OK