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.
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

{"create_label": true}

Boolean - Whether or not the system should attempt to create a label when creating and updating a shipment. Not required. Default is false.
created

{"created": "2015-05-05 15:43:03"}

String - The date and time the shipment was created. Set by the system.
entry_point

{"entry_point": "SZCN"}

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 create_label is true and there was an error attempting to create the label.
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.
street1: String(40) - The sender's street address. Required.
street2: String(40) - Additional space for the sender's street address. Optional.
city: String(40) - The sender's city. Required.
province: String(40) - The sender's province or state. Conditional.
postal_code: String(10) - The sender's postal code or ZIP Code. Conditional.
country: String(2) - The senders's country in ISO 3166-1 alpha-2 format. Must match to.country. Required.

height

{"height": 5.5}

Decimal - The height of the shipment in cm. Not required. Default is 1.
id

{"id": 1014}

Integer - The ID of the shipment. Set by the system.
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",
        "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

{"length": 12}

Decimal - The length of the shipment in cm. Not required. Default is 15.
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.
  • coo String (Required) - The country of origin or where the product was manufactured in ISO 3166-1 alpha-2 format.
  • currency String (Required) - The 3-letter currency code. Always "USD" for now.
  • description String (Required) - A concise description of the line item in English. Max length: 64.
  • dg_code String (Conditional) - A code that identifies dangerous goods. Required if shipping lithium batteries, ORM-D, or other dangerous goods. Refer to this page for a list of codes and further information.
  • hts_code String (Conditional) - The Harmonized Tariff System classification number for Customs clearance (read more).
  • origin_description String (Conditional) - A concise description of the line item in the entry point country's language. Max length: 64.
  • quantity Integer (Required) - The number of units in this line item. Max: 999.
  • value Decimal (Required) - The total declared value of this line item.
  • weight Decimal (Required) - The weight for a single unit of this line item.
overpack_id

{"overpack_id": 1291028}

Integer - The overpack this shipment is inside of. Set by the system. Default is null.
override

{"override": false}

Boolean - Whether or not to override the address verification for this shipment. Not required. Default is false.
service

{"service": "BoxC Priority"}

String - The type of shipping service you want to use for this shipment. Not required. Available services are:
  • BoxC Post
  • BoxC Parcel (default)
  • BoxC Plus
  • BoxC Priority
signature_confirmation

{"signature_confirmation": false}

Boolean - Request signature confirmation from the recipient upon delivery. Default is false. Not available for all services or routes. An additional fee may apply.
terms

{"terms": "DDU"}

String - The Incoterms for this shipment that affects which routes are available. Not required. 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. Options are:
  • DDU (default)
  • DDP
test

{"test": false}

Boolean - Whether or not this is a test shipment that will generate test labels. Default is false. This property is immutable.
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

{"total_cost": 3.58}

Decimal - The total shipping cost in USD. Set by the system.
updated

{"updated": "2015-05-05 15:43:03"}

String - The date and time the shipment was last updated. Set by the system.
verified

{"verified": true}

Boolean - Whether or not the address is verified. Set by the system.
volumetric_weight

{"volumetric_weight": .088}

Decimal - The volumetric / dimensional weight of the shipment based on the route's divisor. Set by the system.
weight

{"weight": 0.567}

Decimal - The weight of the shipment in KG. Required.
width

{"width": 8}

Decimal - The width of the shipment in cm. Not required. Default is 10.
GET
/shipments/{id}
Retrieves a shipment
request
GET /shipments/1014
response

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,
        "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",
                "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
Creates a shipment
request
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,
        "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
    }
}
response

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,
        "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/{id}
Updates a shipment
request
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
            }
        ],
        "overpack_id": 123456,
        "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
    }
}
response

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,
        "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
    }
}
DELETE
/shipments/{id}
Deletes a shipment
request
DELETE /shipments/12492
response

HTTP/1.1 200 OK