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.

Important: A user cannot create shipments until their consignor address is set using the Users resource.

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",
        "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. Required. This property will inherit the user's phone number and company address if it's not provided. Not required.

name: String(40) - The consignor's name. Required.
phone: String(20) - The consignor's phone number. Required.
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. Not required.
city: String(40) - The consignor's city. Required.
province: String(40) - The consignor's province. Required.
postal_code: String(10) - The consignor's postal code. Required.
country: String(2) - The consignor's country in ISO 3166-1 alpha-2 format. Required.
contents Deprecated

{"contents": "An electronic speaker"}

String - The contents of the shipment. Required. Max length is 255.
coo Deprecated

{"coo": "CN"}

String - The country of origin or where the product was manufactured in ISO 3166-1 alpha-2 format for Customs. Defaults to CN.
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.
dg_code Deprecated

{"dg_code": "0966"}

String - 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.
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"
    }
}

Information about the sender. Required. This will appear as the return address. If any conditional property is missing then it will inherit your default return address. The default return address can be set using the Users resource. If the user's default return address is not set then it will use a system generated return address.

name: String(40) - Can be a sender's name or company name. Required if a return address is not set for the user's account.
street1: String(40) - The sender's street address. Conditional.
street2: String(40) - Additional space for the sender's street address. Not required.
city: String(40) - The sender's city. Conditional.
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. Only "US" is accepted. Conditional.

height

{"height": 5.5}

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

{"hs_code": "3109165102"}

String - The Harmonized System classification number for Customs (read more). Required for shipments to the US for values greater than $800 (USD).
id

{"id": 1014}

Integer - The ID of the shipment. Set by the system.
label 
{
    "label": {
        "cancelled": false,
        "cost": 3.56,
        "created": "2015-04-30 18:22:00",
        "id": 4248261,
        "override_fee": 0,
        "oversize_fee": 0,
        "processed": true,
        "processed_date": "2015-05-02",
        "processed_weight": 0.284,
        "service": "BoxC",
        "tracking_number": "9261299991753900000290"
    }
}
Object - The Label created for this shipment. If multiple labels were created, it will return the uncancelled one. Only present when retrieving multiple shipments. 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,
            "tax": 0,
            "weight": 0.235,
            "value": 9.95
        }
    ]
}
Array (Optional) - Contents of the shipment. This will be required in a future update.
  • 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.
  • tax Decimal (Optional) - The tax for this line item. Default: 0.
  • 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. Not required.
override

{"override": false}

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

{"quantity": 1}

Integer - The total number of items inside this shipment. Not required. Default is 1. Max: 999
service

{"service": "BoxC Priority"}

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

{"shipping_method": ""}

String - The shipping method to use for the given service. Not required. Applications should provide the code for the shipping method they wish to use. The default shipping method is Standard and has an empty string for the code. Methods and their codes can be retrieved by using the Estimate resource. Not all routes support multiple shipping methods.
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.
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 / 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

{"total_cost": 3.58}

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

{"value": 10.95}

Decimal - The value of the contents in the shipment in USD. Values greater than $800 must provide an hs_code. Required.
verified

{"verified": true}

Boolean - Whether or not the address is verified. 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"
        ],
        "consignor": {
            "name": "Generic Company, LLC",
            "phone": "555-123-4567",
            "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,
                "cost": 3.56,
                "created": "2015-04-30 18:22:00",
                "id": 898212,
                "override_fee": 0,
                "oversize_fee": 0,
                "processed": true,
                "processed_date": "2015-04-05",
                "processed_weight": 0.284,
                "service": "BoxC",
                "tracking_number": "9261299991753900000290"
            }
        ],
        "length": 10,
        "overpack_id": null,
        "override": false,
        "quantity": 1,
        "service": "BoxC Parcel",
        "shipping_method": "",
        "signature_confirmation": false,
        "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,
        "value": 6.95,
        "verified": true,
        "weight": 0.325,
        "width": 5
    }
}
POST
/shipments
Creates a shipment
request
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",
        "shipping_method": "",
        "signature_confirmation": false,
        "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
    }
}
response

HTTP/1.1 201 Created

{
    "shipment": {
        "comments": [
            "This is a comment"
        ],
        "consignor": {
            "name": "Generic Company, LLC",
            "phone": "555-123-4567",
            "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",
        "shipping_method": "",
        "signature_confirmation": false,
        "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,
        "value": 5.95,
        "verified": true,
        "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"
        ],
        "consignor": {
            "name": "Generic Company, LLC",
            "phone": "555-123-4567",
            "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",
        "shipping_method": "",
        "signature_confirmation": 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"
        },
        "weight": 0.234,
        "width": 5
    }
}
response

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",
            "street1": "1 WORLD WAY",
            "street2": "",
            "city": "SHENZHEN",
            "province": "GUANGDONG",
            "postal_code": "518000",
            "country": "CN"
        },
        "contents": "Phone case",
        "coo": "CN",
        "created": "2015-05-04 08:10:24",
        "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",
        "shipping_method": "",
        "signature_confirmation": false,
        "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,
        "weight": 0.234,
        "width": 5
    }
}
DELETE
/shipments/{id}
Deletes a shipment
request
DELETE /shipments/12492
response

HTTP/1.1 200 OK