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.
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 |
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. |
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, 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. 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. |
contents Deprecated |
|
coo Deprecated |
|
create_label |
|
created |
|
dg_code Deprecated |
|
entry_point |
String - The drop off location for this shipment. By default your application's entry point settings are inherited by the shipment. Not 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 |
|
hs_code Deprecated |
|
id |
|
label |
{ "label": { "cancelled": false, "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, "override_fee": 0, "oversize_fee": 0, "processed": true, "processed_date": "2015-05-02", "processed_weight": 0.284, "service": "BoxC Parcel", "status": "Delivered", "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, "tax": 0, "weight": 0.235, "value": 9.95 } ] }Array (Optional) - Contents of the shipment. This will be required in a future update.
|
overpack_id |
|
override |
|
quantity Deprecated |
|
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 / consignee's shipping address. 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 |
|
value Deprecated |
|
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" ], "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" }, "contents": "1 phone case", "coo": "CN", "created": "2015-04-30 18:21:22", "dg_code": null, "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, "hs_code": null, "id": 1019, "label": { "cancelled": false, "chargeable_weight": 0.284, "cost": 3.56, "created": "2015-04-30 18:22:00", "delivery_date": null, "id": 898212, "override_fee": 0, "oversize_fee": 0, "processed": true, "processed_date": "2015-05-02", "processed_weight": 0.284, "service": "BoxC Parcel", "status": "En Route", "tracking_number": "9261299991753900000290" }, "length": 10, "overpack_id": 201921, "override": false, "quantity": 1, "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", "value": 6.95, "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" ], "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" }, "contents": "1 phone case", "coo": "CN", "created": "2015-04-30 18:21:59", "dg_code": null, "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, "hs_code": null, "id": 1014, "labels": [ { "cancelled": false, "chargeable_weight": 0.284, "cost": 3.56, "created": "2015-04-30 18:22:00", "delivery_date": null, "events": [], "id": 898212, "override_fee": 0, "oversize_fee": 0, "processed": true, "processed_date": "2015-04-05", "processed_weight": 0.284, "service": "BoxC Parcel", "status": "En Route", "tracking_number": "9261299991753900000290" } ], "length": 10, "overpack_id": null, "override": false, "quantity": 1, "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", "value": 6.95, "verified": true, "volumetric_weight": 0.088, "weight": 0.325, "width": 5 } }
POST /shipments
{ "shipment": { "comments": [ "This is a comment" ], "contents": "1 phone case", "coo": "CN", "create_label": false, "dg_code": "0966", "from": { "name": "My Company Name", "street1": "113 INTL BROADWAY", "street2": "", "city": "LOS ANGELES", "province": "CA", "postal_code": "91013", "country": "US" }, "height": 3.9, "length": 10, "override": false, "quantity": 1, "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" }, "value": 5.95, "weight": 0.4, "width": 5 } }
HTTP/1.1 201 Created
{ "shipment": { "comments": [ "This is a comment" ], "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" }, "contents": "1 phone case", "coo": "CN", "created": "2015-05-04 08:10:24", "dg_code": "0966", "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, "hs_code": null, "id": 1015, "labels": [], "length": 10, "overpack_id": null, "override": false, "quantity": 1, "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", "value": 5.95, "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" ], "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, "dg_code": null, "height": 3.5, "length": 10, "overpack_id": 123456, "override": true, "quantity": 2, "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" ], "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" }, "contents": "Phone case", "coo": "CN", "created": "2015-05-04 10:10:10", "dg_code": null, "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, "hs_code": "5515029332", "id": 1014, "labels": [], "length": 10, "overpack_id": 123456, "override": true, "quantity": 2, "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, "value": 5.95, "verified": false, "volumetric_weight": 0.088, "weight": 0.234, "width": 5 } }
DELETE /shipments/12492
HTTP/1.1 200 OK