Shippo: we make shipping simple

Shippo API References

First-time users and those looking for specific integration tutorials,
see our full API documentation and guides.
API Resources

All API URLs listed in this documentation are relative to https://api.goshippo.com/. For example, the /addresses/ resource is reachable at https://api.goshippo.com/addresses/.

Authentication

The API requires Shippo's token HTTP Authentication with your Shippo private token. In order to authenticate properly, please put Authorization: ShippoToken <token> in your header. You can find your token on the Shippo API settings page.

For more information about authentication and test mode, please visit our Authentication guide.

The API is available via Secure Socket Layer (SSL) only. Insecure attempts to access the API will return HTTP status 403/Forbidden.

Request & Response Data

Request data is passed to the API by POSTing JSON objects with the appropriate key/value-pairs to the respective resource. The documentation for each API resource contains more details on the values accepted by a given resource.

Response data also formatted as JSON object. You can specify how many results per page are to be returned. For instance, /rates/?results=25 will return up to 25 results.

REST & Disposable Objects

The Shippo API is built around REST principles. Use POST requests to create objects, GET requests to retrieve objects, and PUT requests to update objects.

Only the Carrier Accounts object can be updated via PUT requests. All other objects such as Addresses, Parcels, Shipments, Rates, Transactions, Refunds, Customs Items, and Customs Declarations are disposable. This means that once you created an object, you cannot change it. Instead, create a new one with the desired values.

API Endpoint

https://api.goshippo.com/

Documentation and Tutorials

First-time users and those looking for step-by-step tutorials, head to our full API documentation.

Client Framework and Libraries
The following libraries are available on our Shippo Github Account: Our community contributed libraries:
Questions?

Hit us up on Stack Overflow using the shippo tag. Or for account specific questions, we're happy to help at support@goshippo.com.

Addresses

Address objects are used for creating Shipments, obtaining Rates and printing Labels, and thus are one of the fundamental building blocks of the Shippo API.

Attributes
object_state "VALID"
"INVALID"
"INCOMPLETE"
Valid addresses contain all required values.

Invalid addresses have failed one or multiple validations.

Incomplete Addresses are eligible for requesting rates but lack at least one required value for purchasing labels.
object_purpose "QUOTE"
"PURCHASE"
Indicates whether an address can be used to purchase labels or only to obtain rates.
object_source "FULLY_ENTERED"
"PARTIALLY_ENTERED"
"VALIDATOR
Fully entered Addresses only contain user-given values and are eligible for purchasing a label.

Partially entered Addresses lack some required information and only qualify for requesting rates.

Validator addresses have been created by the address validation service.
object_created datetime Date and time of Address creation.
object_updated datetime Date and time of last Address update. Since you cannot update Addresses after they were created, this time stamp reflects the time when the Address was changed by Shippo's systems for the last time, e.g., during the approximation of one or more values.
object_id string Unique identifier of the given Address object. This ID is required to create a Shipment object.
object_owner string Username of the user who created the Address object.
object_purpose "QUOTE"
"PURCHASE"
Quote Addresses can be generated by only passing selected address information. Quote Addresses can only be used for obtaining shipping Rate quotes and cannot be used to purchase Labels. Addresses that should be used for purchases must be fully entered, i.e., a complete street address with all required fields must be passed.
name string First and Last Name of the addressee
company string Company Name
street1 string First street line, 35 character limit. Usually street number and street name (except for DHL Germany, see street_no).
street_no string Street number of the addressed building. This field can be included in street1 for all carriers except for DHL Germany.
street2 string Second street line, 35 character limit.
street3 string Third street line, 35 character limit. Only accepted for USPS international shipments, UPS domestic and UPS international shipments.
city
required for purchase
string Name of a city. When creating a Quote Address, sending a city is optional but will yield more accurate Rates. Please bear in mind that city names may be ambiguous (there are 34 Springfields in the US). Pass in a state or a ZIP code (see below), if known, it will yield more accurate results.
zip string Postal code of an Address. When creating a Quote Addresses, sending a ZIP is optional but will yield more accurate Rates.
state string State values are only required for shipments from the United States and Canada (most carriers only accept two-character state abbreviations). However, to receive more accurate quotes, passing it is generally recommended.
country ISO 3166-1-alpha-2 code (ISO 2 country code) Example: 'US' or 'DE'. All accepted values can be found on the Official ISO Website. Sending a country is always required.
phone string Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This increases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped.
email email E-mail address of the contact person, RFC3696/5321-compliant.
is_residential nullable boolean Indicates whether the address provided is a residential address or not.
validate nullable boolean Set to true to validate Address object.
metadata string A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
test bool Indicates whether the object has been created in test mode.
messages array An array containing elements of the following schema:
"code" (string): an identifier for the corresponding message (not always available")
"message" (string): a publishable message containing further information.
API Resource URL

https://api.goshippo.com/addresses/

Example
{
    "object_state": "VALID",
    "object_purpose": "PURCHASE",
    "object_source": "FULLY_ENTERED",
    "object_created": "2013-12-11T19:38:09.729Z",
    "object_updated": "2013-12-11T19:38:09.729Z",
    "object_id": "fcd9c72b564d4bfa8c03299ed6545132",
    "object_owner": "shippotle@goshippo.com",
    "name": "Shawn Ippotle",
    "company": "Shippo",
    "street1": "215 Clayton St.",
    "street2": "",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "shippotle@goshippo.com",
    "is_residential":true,
    "metadata": "Customer ID 123456",
    "test": true,
    "messages": []
}

Create a new address

Creates a new address object.

Attributes
object_purpose
required
"QUOTE"
"PURCHASE"
name
required for purchase
string
company
optional
string
street1
required for purchase
string
street_no
optional
string
street2
optional
string
street3
optional
string
city
required for purchase
string
zip
required for purchase
string
state
required for purchase for some countries
string
country
required
ISO 3166-1-alpha-2 code (ISO 2 country code)
phone
optional
string
email
required for purchase
email
is_residential
optional
boolean
validate
optional
boolean
metadata
optional
string
API Resource URL

https://api.goshippo.com/addresses/

Example
curl https://api.goshippo.com/addresses/ \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -d name="Shawn Ippotle" \
    -d object_purpose="PURCHASE" \
    -d company="Shippo" \
    -d street1="215 Clayton St." \
    -d street2="" \
    -d city="San Francisco" \
    -d state="CA" \
    -d zip=94117 \
    -d country="US" \
    -d phone="+1 555 341 9393" \
    -d email="shippotle@goshippo.com"\
    -d is_residential=True\
    -d metadata="Customer ID 123456"
Response Example
{
   "object_state":"VALID",
   "object_purpose":"PURCHASE",
   "object_source":"FULLY_ENTERED",
   "object_created":"2014-07-09T02:19:13.174Z",
   "object_updated":"2014-07-09T02:19:13.174Z",
   "object_id":"d799c2679e644279b59fe661ac8fa488",
   "object_owner":"shippotle@goshippo.com",
   "name":"Shawn Ippotle",
   "company":"Shippo",
   "street1":"215 Clayton St.",
   "street2":"",
   "city":"San Francisco",
   "state":"CA",
   "zip":"94117",
   "country":"US",
   "phone":"15553419393",
   "email":"shippotle@goshippo.com",
   "is_residential":true,
   "messages":[],
   "metadata":"Customer ID 123456"
}

Retrieve an address

Retrieve an existing address by object id.

API Resource URL

https://api.goshippo.com/addresses/<ADDRESS OBJECT ID>

Example
curl https://api.goshippo.com/addresses/d799c2679e644279b59fe661ac8fa488/ \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "object_state":"VALID",
   "object_purpose":"PURCHASE",
   "object_source":"FULLY_ENTERED",
   "object_created":"2014-07-09T02:19:13.174Z",
   "object_updated":"2014-07-09T02:19:13.174Z",
   "object_id":"d799c2679e644279b59fe661ac8fa488",
   "object_owner":"shippotle@goshippo.com",
   "name":"Shawn Ippotle",
   "street1":"215 Clayton St.",
   "street2":"",
   "city":"San Francisco",
   "state":"CA",
   "zip":"94117",
   "country":"US",
   "phone":"15553419393",
   "email":"shippotle@goshippo.com",
   "is_residential":true,
   "messages":[],
   "metadata":"Customer ID 123456",
   "test": true
}

Validate an address

Validate an existing address by object id.

API Resource URL

https://api.goshippo.com/addresses/<ADDRESS OBJECT ID>/validate/

Example
curl https://api.goshippo.com/addresses/d799c2679e644279b59fe661ac8fa488/validate/ \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
    "object_state": "INVALID", 
    "object_purpose": "PURCHASE", 
    "object_source": "VALIDATOR", 
    "object_created": "2015-03-30T23:47:11.574Z", 
    "object_updated": "2015-03-30T23:47:11.596Z", 
    "object_id": "67183b2e81e9421f894bfbcdc4236b16", 
    "object_owner": "shippotle@goshippo.com", 
    "name": "Shawn Ippotle", 
    "company": "Shippo", 
    "street_no": "", 
    "street1": "215 CLAYTOON ST.", 
    "street2": "", 
    "city": "SAN FRANCISCO", 
    "state": "CA", 
    "zip": "94107", 
    "country": "US", 
    "phone": "", 
    "email": "shippotle@goshippo.com", 
    "is_residential": null, 
    "messages": [
        {
            "source": "USPS",
            "code": "Unknown Street", 
            "text": "City, State and ZIP Code are valid, but street address is not a match."
        }
    ], 
    "metadata": "",
    "test": true
}

List all addresses

List all addresses.

API Resource URL

https://api.goshippo.com/addresses/

Example
curl https://api.goshippo.com/addresses/ \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "count":3,
   "next":null,
   "previous":null,
   "results":[
      {
         "object_state":"VALID",
         "object_purpose":"PURCHASE",
         "object_source":"FULLY_ENTERED",
         "object_created":"2014-07-16T23:20:31.089Z",
         "object_updated":"2014-07-16T23:20:31.089Z",
         "object_id":"747207de2ba64443b645d08388d0309c",
         "object_owner":"shippotle@goshippo.com",
         "name":"Shawn Ippotle",
         "street1":"215 Clayton St.",
         "street2":"",
         "city":"San Francisco",
         "state":"CA",
         "zip":"94117",
         "country":"US",
         "phone":"15553419393",
         "email":"shippotle@goshippo.com",
         "is_residential":true,
         "messages":[],
         "metadata":"Customer ID 123456",
         "test": true
      },
      {...},
      {...}
   ]
}

Parcels

Parcel objects are used for creating Shipments, obtaining Rates and printing Labels, and thus are one of the fundamental building blocks of the Shippo API. Parcels are created with their basic dimensions and their weight.

Attributes
object_state "VALID" A Parcel will only be valid when all required values have been sent and validated successfully.
object_created datetime Date and time of Parcel creation.
object_updated datetime Date and time of last Parcel update. Since you cannot update Parcels after they were created, this time stamp reflects the time when the Parcel was changed by Shippo's systems for the last time, e.g., during sorting the dimensions given.
object_id string Unique identifier of the given Parcel object. This ID is required to create a Shipment object.
object_owner string Username of the user who created the Parcel object.
length decimal (10,4) Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.
width decimal (10,4) Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.
height decimal (10,4) Height of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.
distance_unit "cm"
"in"
"ft"
"mm"
"m"
"yd"
The unit used for length, width and height.
weight decimal (10,4) Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.
mass_unit "g"
"oz"
"lb"
"kg"
The unit used for weight.
template string A parcel template is a predefined package used by one or multiple carriers. See the parcel template table for all available values and the corresponding tokens. When a template is given, the parcel dimensions have to be sent, but will not be used for the Rate generation. The dimensions below will instead be used. The parcel weight is not affected by the use of a template.
metadata string A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
extra object An object holding optional extra services to be requested for each parcel in a multi-piece shipment. See the Parcel Extra table below for all available services.
test bool Indicates whether the object has been created in test mode.
API Resource URL

https://api.goshippo.com/parcels/

Example
{
   "object_state": "VALID",
   "object_created": "2013-12-11T19:38:09.729Z",
   "object_updated": "2013-12-11T19:38:09.729Z",
   "object_id": "fcd9c72b564d4bfa8c03299ed6545132",
   "object_owner": "shippotle@goshippo.com",
   "template": null,
   "length": "20",
   "width": "15",
   "height": "12",
   "distance_unit": "in",
   "weight": "5",
   "mass_unit": "lb",
   "metadata": "Customer ID 123456",
   "extra": {},
   "test": true
}

Parcel Extras

The following values are supported for the extra field of the parcel object.

COD object Specify collection on delivery details (UPS, and FedEx only).
        amount string Amount to be collected.
        currency ISO 4217 Currency Code (string) Currency for the amount to be collected. Currently only USD is supported for FedEx and UPS.
        payment_method "SECURED_FUNDS", "CASH", "ANY" Secured funds include money orders, certified cheques and others (see UPS and FedEx for details). If no payment_method inputted the value defaults to "ANY".)
insurance object Specify collection on delivery details (UPS, and FedEx only).
        amount string Amount to be collected.
        currency ISO 4217 Currency Code (string) Currency for the amount to be collected. Currently only USD is supported for FedEx and UPS.
        provider "FEDEX", "UPS" Specify the carrier insurance to have Insurance provided by the carrier directly.
        content string Specify package content for insurance.

Create a new parcel

Creates a new parcel object.

Attributes
length
required
decimal (10,4)
width
required
decimal (10,4)
height
required
decimal (10,4)
distance_unit
required
"cm"
"in"
"ft"
"mm"
"m"
"yd"
weight
required
decimal (10,4)
mass_unit
required
"g"
"oz"
"lb"
"kg"
template
optional
string
extra
optional
object
metadata
optional
string
API Resource URL

https://api.goshippo.com/parcels/

Example
curl https://api.goshippo.com/parcels/ \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -d length=5 \
    -d width=5 \
    -d height=5 \
    -d distance_unit="cm" \
    -d weight=2 \
    -d mass_unit="lb" \
    -d template="" \
    -d metadata="Customer ID 123456"
Response Example
{
   "object_state":"VALID",
   "object_created":"2014-07-08T23:19:19.565Z",
   "object_updated":"2014-07-08T23:19:19.565Z",
   "object_id":"7df2ecf8b4224763ab7c71fae7ec8274",
   "object_owner":"shippotle@goshippo.com",
   "template":null,
   "length":"5",
   "width":"5",
   "height":"5",
   "distance_unit":"cm",
   "weight":"2",
   "mass_unit":"lb",
   "metadata":"Customer ID 123456",
   "test": true,
   "extra": {}
}

Retrieve an existing parcel

Retrieve an existing parcel by object id.

API Resource URL

https://api.goshippo.com/parcels/<PARCEL OBJECT ID>

Example
curl https://api.goshippo.com/parcels/7df2ecf8b4224763ab7c71fae7ec8274/ \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "object_state": "VALID",
   "object_created": "2013-12-11T19:38:09.729Z",
   "object_updated": "2013-12-11T19:38:09.729Z",
   "object_id": "fcd9c72b564d4bfa8c03299ed6545132",
   "object_owner": "shippotle@goshippo.com",
   "template": null,
   "length": "20",
   "width": "15",
   "height": "12",
   "distance_unit": "in",
   "weight": "5",
   "mass_unit": "lb",
   "metadata": "Customer ID 123456",
   "extra": {},
   "test": true
}

List all parcels

List all parcel objects.

API Resource URL

https://api.goshippo.com/parcels/

Example
curl https://api.goshippo.com/parcels/ \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "count":3,
   "next":null,
   "previous":null,
   "results":[
      {
         "object_state": "VALID",
         "object_created": "2013-12-11T19:38:09.729Z",
         "object_updated": "2013-12-11T19:38:09.729Z",
         "object_id": "fcd9c72b564d4bfa8c03299ed6545132",
         "object_owner": "shippotle@goshippo.com",
         "template": null,
         "length": "20",
         "width": "15",
         "height": "12",
         "distance_unit": "in",
         "weight": "5",
         "mass_unit": "lb",
         "metadata": "Customer ID 123456",
         "extra": {},
         "test": true
      },
      {...},
      {...}
   ]
}
f

Shipments

The heart of the Shippo API, a shipment is made up of "to" and "from" addresses and the parcel to be shipped. Once created, a shipment object can be used to retrieve shipping rates and purchase a shipping label.

Attributes
object_
status
"WAITING"
"QUEUED"
"SUCCESS"
"ERROR"
"Waiting" shipments have been successfully submitted but not yet been processed. "Queued" shipments are currently being processed. "Success" shipments have been processed successfully, meaning that rate generation has concluded. "Error" does not occur currently and is reserved for future use.
object_
purpose
"QUOTE"
"PURCHASE"
Indicated whether a shipment can be used to purchase Labels or only to obtain quote Rates. Note that if at least one quote Address is passed in the original request, the Shipment will be eligible for quotes only.
object_
state
"VALID"
"INCOMPLETE"
"INVALID"
"VALID" shipments contain all required values and can be used to get rates and purchase labels. "INCOMPLETE" shipments lack required values but can be used for getting rates. "INVALID" shipments can't be used for getting rates or labels.
object_
created
datetime Date and time of Shipment creation.
object_
updated
datetime Date and time of last Shipment update.
object_id string Unique identifier of the given Shipment object.
object_owner string Username of the user who created the Shipment object.
object_purpose "QUOTE"
"PURCHASE"
Quote Shipments can only be used to obtain quote Rates; at the same time, they accept any valid or completed Address object. Purchase Shipments can be used to obtain Rates and purchase Labels, but only accept purchase Addresses that have been fully entered.
address_from string ID of the Address object that should be used as sender Address.
address_to string ID of the Address object that should be used as recipient Address.
parcel string ID of the Parcel object to be shipped.
return_of string ID of the Transaction object of the outbound shipment.This field triggers the creation of a scan-based return shipments. See the Create a return shipment section for more details.
submission_date datetime (ISO 8601 date) Date the shipment will be tendered to the carrier. Must be in the format "2014-01-18T00:35:03.463Z". Defaults to current date and time if no value is provided. Please note that some carriers require this value to be in the future, on a working day, or similar.
address_return string ID of the Address object where the shipment will be sent back to if it is not delivered (Only available for UPS, USPS, and Fedex shipments).
If this field is not set, your shipments will be returned to the address_form.
customs_
declaration
string ID of the Customs Declarations object for an international shipment.
insurance_amount decimal Total Parcel value to be insured. Please note that you need to specify the "insurance_currency" as well as the "insurance_content" (via the extra field below, if your package content is not general cargo) as well.
insurance_currency
required if insurance_amount is set
ISO 4217 Currency Code (string) Currency used for insurance_amount. The official ISO 4217 currency codes are used, e.g. "USD" or "EUR".
reference_1 string Optional text to be printed on the shipping label. Up to 50 characters.
reference_2 string Optional text to be printed on the shipping label. Up to 50 characters.
carrier_
accounts
array An array of object_ids of the carrier account objects to be used for getting shipping rates for this shipment. If no carrier account object_ids are set in this field, Shippo will attempt to generate rates using all the carrier accounts that have the 'active' field set.
metadata string A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
extra object An object holding optional extra services to be requested. See the Shipment Extra table below for all available services.
rates_url url The URL pointing to the Rates List of the given shipment. It is sent for your convenience, but can also be manually built with the following schema: "https://api.goshippo.com/shipments/<SHIPMENT OBJECT ID>/rates/[<CURRENCY CODE>]"
rates_list array An array with all available rates. If async has been set to false in the request, this will be populated with all available rates in the response. Otherwise rates will be created asynchronously and this array will initially be empty.
messages array An array containing elements of the following schema:
"code" (string): an identifier for the corresponding message (not always available")
"message" (string): a publishable message containing further information.
test bool Indicates whether the object has been created in test mode.
API Resource URL

Example
{
    "object_state": "VALID",
    "object_status": "SUCCESS",
    "object_purpose": "PURCHASE",
    "object_created": "2013-12-01T06:24:20.121Z",
    "object_updated": "2013-12-01T06:24:20.121Z",
    "object_id": "5e40ead7cffe4cc1ad45108696162e42",
    "object_owner": "shippotle@goshippo.com",
    "address_from": "4f406a13253945a8bc8deb0f8266b245",
    "address_to": "4c7185d353764d0985a6a7825aed8ffb",
    "address_return": "4f406a13253945a8bc8deb0f8266b245",
    "parcel": "ec952343dd4843c39b42aca620471fd5",
    "submission_date": "2013-12-03T12:00:00.000Z",
    "insurance_amount": "",
    "insurance_currency": "",
    "extra": {},
    "customs_declaration": "",
    "reference_1": "",
    "reference_2": "",
    "rates_url": "https://api.goshippo.com/shipments/5e40ead7cffe4cc1ad45108696162e42/rates/",
    "rates_list": [
        {
            "object_state": "VALID",
            "object_purpose": "PURCHASE",
            "object_created": "2013-12-01T06:24:21.121Z",
            "object_updated": "2013-12-01T06:24:21.121Z",
            "object_id": "545ab0a1a6ea4c9f9adb2512a57d6d8b",
            "object_owner": "shippotle@goshippo.com",
            "shipment": "5e40ead7cffe4cc1ad45108696162e42",
            "attributes": [],
            "amount": "5.50",
            "currency": "USD",
            "amount_local": "5.50",
            "currency_local": "USD",
            "provider": "USPS",
            "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
            "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
            "servicelevel_name": "Priority Mail",
            "servicelevel_token":"usps_priority",
            "servicelevel_terms": "",
            "days": 2,
            "arrives_by": null,
            "duration_terms": "Delivery in 1 to 3 business days.",
            "trackable": true,
            "insurance": false,
            "insurance_amount_local": "0.00",
            "insurance_currency_local": null,
            "insurance_amount": "0.00",
            "insurance_currency": null,
            "messages": [],
            "carrier_account": "078870331023437cb917f5187429b093",
            "test": true
        },
        ...
    ],
    "carrier_accounts": [],
    "metadata": "Customer ID 123456",
    "messages": [],
    "test": true
}

Shipment Extras

The following values are supported for the extra field of the shipment object.

signature_confirmation "STANDARD", "ADULT", "CERTIFIED" Request standard or adult signature confirmation. You can alternatively request Certified Mail (USPS only).
saturday_delivery boolean Marks shipment as to be delivered on a Saturday.
insurance_content string Specify package content for insurance.
insurance_provider "FEDEX", "UPS", "ONTRAC" Specify the carrier insurance to have Insurance provided by the carrier directly, not by Shippo's 3rd-party Shipsurance insurance.
bypass_address_validation boolean Bypasses address validation (USPS and UPS only).
use_manifests boolean Indicates that shipment will be linked with a manifest (Canada Post contract customers only).
request_retail_rates boolean Returns retail rates instead of account-based rates (UPS and FedEx only).
billing object Specify billing details (UPS and FedEx only).
        type "SENDER", "RECIPIENT", "THIRD_PARTY" Party to be billed.
        account string Account number to be billed.
        zip string ZIP code of account number to be billed (required for UPS if there is a zip on the billing account).
        country string Country iso2 code of account number to be billed (required for UPS third party billing only).
COD object Specify collection on delivery details (UPS, FedEx and GLS only).
        amount string Amount to be collected.
        currency ISO 4217 Currency Code (string) Currency for the amount to be collected. Currently only USD is supported for FedEx and UPS.
        payment_method "SECURED_FUNDS", "CASH", "ANY" Secured funds include money orders, certified cheques and others (see UPS and FedEx for details). If no payment_method inputted the value defaults to "ANY".)
usps_sort_type "NDC", "FiveDigit", "MixedNDC", "Nonpresorted", "Presorted", "SCF", "SinglePiece", "ThreeDigit" Indicates sort level (USPS Parcel Select only).
usps_entry_facility "DNDC", "DDU", "DSCF", "ONDC", "Other" Indicates postal facility where mail is entered (USPS Parcel Select only).
dangerous_goods_code "01", "02", "03", "04", "05", "06", "07", "08", "09" Dangerous Goods Code (DHL eCommerce only). See Category Codes

Create a new shipment

Creates a new shipment object.

Attributes
object_purpose
required
"QUOTE"
"PURCHASE"
address_from
required
string or object
address_to
required
string or object
parcel
required
string or object
submission_date
optional
datetime
address_return
optional
string or object
customs_declaration
optional
string or object
insurance_amount
optional
decimal
insurance_currency
required if insurance_amount is set
ISO 4217 Currency Code (string)
extra
optional
object
reference_1
optional
string
reference_2
optional
string
Up to 50 characters.
metadata
optional
string
Up to 50 characters.
async
optional
boolean
API Resource URL

https://api.goshippo.com/shipments/

Example
curl https://api.goshippo.com/shipments/ \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -H "Content-Type: application/json" \
    -d $'{
        "object_purpose": "PURCHASE",
        "address_to": {
            "object_purpose": "PURCHASE",
            "name": "Mr Hippo",
            "street1": "965 Mission St #572",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94103",
            "country": "US",
            "phone": "4151234567",
            "email": "mrhippo@goshippo.com"
        },
        "address_from": {
            "object_purpose": "PURCHASE",
            "name": "Mrs Hippo",
            "street1": "1092 Indian Summer Ct",
            "city": "San Jose",
            "state": "CA",
            "zip": "95122",
            "country": "US",
            "phone": "4159876543",
            "email": "mrshippo@goshippo.com"
        },
        "parcel": {
            "length": "10",
            "width": "15",
            "height": "10",
            "distance_unit": "in",
            "weight": "1",
            "mass_unit": "lb"
        },
        "async": false
    }'
Response Example
{
   "object_created":"2014-07-17T00:04:06.163Z",
   "object_updated":"2014-07-17T00:04:06.163Z",
   "object_id":"89436997a794439ab47999701e60392e",
   "object_owner":"shippotle@goshippo.com",
   "object_state":"VALID",
   "object_status":"SUCCESS",
   "object_purpose":"PURCHASE",
   "address_from":"fdabf0abb93c4460b60aa596116872a7",
   "address_to":"0476d70c612a423f9509ba5f807569db",
   "address_return":"fdabf0abb93c4460b60aa596116872a7",
   "parcel":"7df2ecf8b4224763ab7c71fae7ec8274",
   "submission_date":"2013-12-03T12:00:00Z",
   "insurance_amount":"",
   "insurance_currency":"",
   "extra":{},
   "customs_declaration":null,
   "reference_1":"",
   "reference_2":"",
   "rates_url":"https://api.goshippo.com/shipments/89436997a794439ab47999701e60392e/rates/",
   "rates_list": [
        {
            "object_state": "VALID",
            "object_purpose": "PURCHASE",
            "object_created": "2014-07-17T00:04:06.263Z",
            "object_updated": "2014-07-17T00:04:06.263Z",
            "object_id": "545ab0a1a6ea4c9f9adb2512a57d6d8b",
            "object_owner": "shippotle@goshippo.com",
            "shipment": "89436997a794439ab47999701e60392e",
            "attributes": [],
            "amount": "5.50",
            "currency": "USD",
            "amount_local": "5.50",
            "currency_local": "USD",
            "provider": "USPS",
            "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
            "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
            "servicelevel_name": "Priority Mail",
            "servicelevel_token":"usps_priority",
            "servicelevel_terms": "",
            "days": 2,
            "arrives_by": null,
            "duration_terms": "Delivery in 1 to 3 business days.",
            "trackable": true,
            "insurance": false,
            "insurance_amount_local": "0.00",
            "insurance_currency_local": null,
            "insurance_amount": "0.00",
            "insurance_currency": null,
            "messages": [],
            "carrier_account": "078870331023437cb917f5187429b093",
            "test": true
        },
        ...
    ],
   "carrier_accounts": [],
   "messages":[],
   "metadata":"Customer ID 123456",
   "test": true
}

Retrieve an existing shipment

Retrieve an existing shipment by object id.

API Resource URL

https://api.goshippo.com/shipments/<SHIPMENT OBJECT ID>

Example
curl https://api.goshippo.com/shipments/7c47d12aa95a4cbb9d90c167cca7bea7 \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "object_created":"2014-07-17T00:04:06.163Z",
   "object_updated":"2014-07-17T00:06:05.416Z",
   "object_id":"89436997a794439ab47999701e60392e",
   "object_owner":"shippotle@goshippo.com",
   "object_state":"VALID",
   "object_status":"SUCCESS",
   "object_purpose":"PURCHASE",
   "address_from":"fdabf0abb93c4460b60aa596116872a7",
   "address_to":"0476d70c612a423f9509ba5f807569db",
   "address_return":"fdabf0abb93c4460b60aa596116872a7",
   "parcel":"7df2ecf8b4224763ab7c71fae7ec8274",
   "submission_date":"2013-12-03T12:00:00Z",
   "insurance_amount":"",
   "insurance_currency":"",
   "extra":{},
   "customs_declaration":null,
   "reference_1":"",
   "reference_2":"",
   "rates_url":"https://api.goshippo.com/shipments/89436997a794439ab47999701e60392e/rates/",
   "rates_list": [
        {
            "object_state": "VALID",
            "object_purpose": "PURCHASE",
            "object_created": "2014-07-17T00:04:06.263Z",
            "object_updated": "2014-07-17T00:04:06.263Z",
            "object_id": "545ab0a1a6ea4c9f9adb2512a57d6d8b",
            "object_owner": "shippotle@goshippo.com",
            "shipment": "89436997a794439ab47999701e60392e",
            "attributes": [],
            "amount": "5.50",
            "currency": "USD",
            "amount_local": "5.50",
            "currency_local": "USD",
            "provider": "USPS",
            "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
            "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
            "servicelevel_name": "Priority Mail",
            "servicelevel_token":"usps_priority",
            "servicelevel_terms": "",
            "days": 2,
            "arrives_by": null,
            "duration_terms": "Delivery in 1 to 3 business days.",
            "trackable": true,
            "insurance": false,
            "insurance_amount_local": "0.00",
            "insurance_currency_local": null,
            "insurance_amount": "0.00",
            "insurance_currency": null,
            "messages": [],
            "carrier_account": "078870331023437cb917f5187429b093",
            "test": true
        },
        ...
    ],
   "carrier_accounts": [],
   "messages":[
      {
         "source":"UPS",
         "code":"",
         "text":"RatedShipmentWarning: User Id and Shipper Number combination is not qualified to receive negotiated rates."
      }
   ],
   "metadata":"Customer ID 123456",
   "test": true
}

List all shipments

List all shipment objects.

API Resource URL

https://api.goshippo.com/shipments/

Example
curl https://api.goshippo.com/shipments/ \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "count":1269,
   "next":"https://api.goshippo.com/shipments/?page=2",
   "previous":null,
   "results":[
      {
         "object_created":"2014-07-17T00:04:06.163Z",
         "object_updated":"2014-07-17T00:06:05.416Z",
         "object_id":"89436997a794439ab47999701e60392e",
         "object_owner":"shippotle@goshippo.com",
         "object_state":"VALID",
         "object_status":"SUCCESS",
         "object_purpose":"PURCHASE",
         "address_from":"fdabf0abb93c4460b60aa596116872a7",
         "address_to":"0476d70c612a423f9509ba5f807569db",
         "parcel":"7df2ecf8b4224763ab7c71fae7ec8274",
         "submission_date":"2013-12-03T12:00:00Z",
         "address_return":"fdabf0abb93c4460b60aa596116872a7",
         "customs_declaration":null,
         "insurance_amount":"",
         "insurance_currency":"",
         "extra":{},
         "reference_1":"",
         "reference_2":"",
         "rates_url":"https://api.goshippo.com/shipments/89436997a794439ab47999701e60392e/rates/",
         "rates_list": [
           {
               "object_state": "VALID",
               "object_purpose": "PURCHASE",
               "object_created": "2014-07-17T00:04:06.263Z",
               "object_updated": "2014-07-17T00:04:06.263Z",
               "object_id": "545ab0a1a6ea4c9f9adb2512a57d6d8b",
               "object_owner": "shippotle@goshippo.com",
               "shipment": "89436997a794439ab47999701e60392e",
               "attributes": [],
               "amount": "5.50",
               "currency": "USD",
               "amount_local": "5.50",
               "currency_local": "USD",
               "provider": "USPS",
               "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
               "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
               "servicelevel_name": "Priority Mail",
               "servicelevel_token":"usps_priority",
               "servicelevel_terms": "",
               "days": 2,
               "arrives_by": null,
               "duration_terms": "Delivery in 1 to 3 business days.",
               "trackable": true,
               "insurance": false,
               "insurance_amount_local": "0.00",
               "insurance_currency_local": null,
               "insurance_amount": "0.00",
               "insurance_currency": null,
               "messages": [],
               "carrier_account": "078870331023437cb917f5187429b093",
               "test": true
           },
           ...
         ],
         "carrier_accounts": [],
         "messages":[
            {
               "source":"UPS",
               "code":"",
               "text":"RatedShipmentWarning: Ship To Address Classification is changed from Commercial to Residential"
            }
         ],
         "metadata":"Customer ID 123456",
         "test": true
      },
      {...},
      {...}
   ]
}

Rates

A rate is an available service of a shipping provider for a given shipment, typically including the price and transit time.

Attributes
object_state "VALID" Each Rate of a valid Shipment object is valid.
object_purpose "QUOTE"
"PURCHASE"
Indicates whether the corresponding Shipment object can be used to purchase Labels or only to obtain quote Rates.
object_created datetime Date and time of Rate creation.
object_updated datetime Date and time of last Rate update.
object_id string Unique identifier of the given Rate object.
object_owner string Username of the user who created the rate object.
attributes array Contains specific attributes of this Rate in context of the entire shipment. Attributes are assigned to the cheapest or fastest Rate(s) or to the Rate(s) with the overall best value.
amount_local decimal Final Rate price, expressed in the currency used in the recipient's country.
currency_local ISO 4217 Currency Code Currency used in the recipient's country, refers to "amount_local". The official ISO 4217 currency codes are used, e.g. "USD" or "EUR".
amount decimal Final Rate price, expressed in the currency used in the sender's country.
currency ISO 4217 Currency Code (string) Currency used in the sender's country, refers to "amount". The official ISO 4217 currency codes are used, e.g. "USD" or "EUR".
provider string Carrier offering the rate, e.g., "FedEx" or "Deutsche Post DHL".
provider_image_75 string URL to the provider logo with max. dimensions of 75*75px. Please refer to the provider's Logo Usage Guidelines before using the logo.
provider_image_200 string URL to the provider logo with max. dimensions of 200*200px. Please refer to the provider's Logo Usage Guidelines before using the logo.
servicelevel_name string Name of the Rate's servicelevel, e.g. "International Priority" or "Standard Post". A servicelevel commonly defines the transit time of a Shipment (e.g., Express vs. Standard), along with other properties. These names vary depending on the provider.
servicelevel_token string Token of the Rate's servicelevel, e.g. "usps_priority" or "fedex_grount". See servicelevels.
servicelevel_terms string Further clarification of the service.
days integer Estimated transit time (duration) in days of the Parcel at the given servicelevel. Please note that this is not binding, but only an average value as given by the provider. Shippo is not able to guarantee any transit times.
duration_terms string Further clarification of the transit times. Often, this includes notes that the transit time as given in "days" is only an average, not a guaranteed time.
trackable bool Whether the parcel is traceable or not. Please note that this also is an approximation: some providers generally offer tracking, but exclude certain destination country from that service.
insurance bool Indicates whether the Rate contains a parcel insurance.
insurance_amount_local float The parcel insurance amount (i.e. the maximum value that is covered by the insurance in case of damage or loss) expressed in the recipient's country's currency.
insurance_currency_local ISO 4217 Currency Code (string) The parcel insurance currency of the recipient's country (ISO 3 currency code).
insurance_amount float The parcel insurance amount (i.e. the maximum value that is covered by the insurance in case of damage or loss) expressed in the sender's country's currency.
insurance_currency ISO 4217 Currency Code (string) The parcel insurance currency of the sender's country (ISO 3 currency code).
carrier_account string Object ID of the carrier account that has been used to retrieve the rate.
zone string The parcel's transit zone token. These tokens can vary depending on the provider.
messages array An array containing elements of the following schema:
"code" (string): an identifier for the corresponding message (not always available")
"message" (string): a publishable message containing further information.
test bool Indicates whether the object has been created in test mode.
API Resource URL

https://api.goshippo.com/shipments/<SHIPMENT OBJECT ID>/rates/[<CURRENCY CODE>/]

Example
{
    "object_state":"VALID",
    "object_purpose":"PURCHASE",
    "object_created":"2013-12-09T01:56:52.780Z",
    "object_updated":"2013-12-09T01:56:52.780Z",
    "object_id":"cf6fea899f1848b494d9568e8266e076",
    "object_owner":"shippotle@goshippo.com",
    "shipment":"5e40ead7cffe4cc1ad45108696162e42",
    "attributes":[],
    "amount_local":"5.35",
    "currency_local":"USD",
    "amount":"5.35",
    "currency":"USD",
    "provider":"USPS",
    "provider_image_75":"https://cdn2.goshippo.com/providers/75/USPS.png",
    "provider_image_200":"https://cdn2.goshippo.com/providers/200/USPS.png",
    "servicelevel_name":"Priority Mail",
    "servicelevel_token":"usps_priority",
    "servicelevel_terms":"",
    "days":2,
    "duration_terms":"Delivery within 1, 2, or 3 days based on where your package started and where it’s being sent.",
    "trackable":true,
    "insurance":true,
    "insurance_amount_local":"0",
    "insurance_currency_local":null,
    "insurance_amount":"0",
    "insurance_currency":null,
    "carrier_account":"b741b99f95e841639b54272834bc478c",
    "zone":"1",
    "messages":[],
    "test":true
}

Get shipping rates

Each valid shipment object will automatically trigger the calculation of all available rates. Depending on your shipment data, there may be none, one or multiple rates.

By default, the calculated Rates will return the price in two currencies under the amount and amount_local keys, respectively. The amount key will contain the price of a rate expressed in the currency that is used in the country from which parcel originates, and the amount_local key will contain the price expressed in the currency that is used in the country the parcel is shipped to. You can request rates with prices expressed in a different currency by adding the desired currency code in the end of the resource URL. The full list of supported currencies along with their codes can be viewed on open exchange rates.

Note: re-requesting the rates with a different currency code will re-queue the shipment (i.e. set the Shipment's object_status to QUEUED) and the converted currency rates will only be available when the Shipment's object_status is set to SUCCESS.

API Resource URL

https://api.goshippo.com/shipments/<SHIPMENT OBJECT ID>/rates/[<CURRENCY CODE>/]

Example
curl https://api.goshippo.com/shipments/5e40ead7cffe4cc1ad45108696162e42/rates/USD \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "count":2,
   "next":null,
   "previous":null,
   "results":[
      {
         "object_state":"VALID",
         "object_purpose":"PURCHASE",
         "object_created":"2014-07-17T00:04:10.118Z",
         "object_updated":"2014-07-17T00:04:10.627Z",
         "object_id":"ee81fab0372e419ab52245c8952ccaeb",
         "object_owner":"shippotle@goshippo.com",
         "shipment":"89436997a794439ab47999701e60392e",
         "attributes":[
            "CHEAPEST",
            "BESTVALUE"
         ],
         "amount":"5.35",
         "currency":"USD",
         "amount_local":"5.35",
         "currency_local":"USD",
         "provider":"USPS",
         "provider_image_75":"https://cdn2.goshippo.com/providers/75/USPS.png",
         "provider_image_200":"https://cdn2.goshippo.com/providers/200/USPS.png",
         "servicelevel_name":"Priority Mail",
         "servicelevel_token":"usps_priority",
         "servicelevel_terms":"",
         "days":1,
         "duration_terms":"Delivery within 1, 2, or 3 days based on where your package started and where it’s being sent.",
         "trackable":true,
         "insurance":true,
         "insurance_amount_local":"50.00",
         "insurance_currency_local":"USD",
         "insurance_amount":"50.00",
         "insurance_currency":"USD",
         "carrier_account": "b741b99f95e841639b54272834bc478c",
         "zone":"1",
         "messages":[],
         "test": true
      },
      {
         "object_state":"VALID",
         "object_purpose":"PURCHASE",
         "object_created":"2014-07-17T00:04:10.334Z",
         "object_updated":"2014-07-17T00:04:10.661Z",
         "object_id":"fd31f301b61c49048f861573d4364ff6",
         "object_owner":"shippotle@goshippo.com",
         "shipment":"89436997a794439ab47999701e60392e",
         "attributes":[],
         "amount":"16.03",
         "currency":"USD",
         "amount_local":"16.03",
         "currency_local":"USD",
         "provider":"USPS",
         "provider_image_75":"https://cdn2.goshippo.com/providers/75/USPS.png",
         "provider_image_200":"https://cdn2.goshippo.com/providers/200/USPS.png",
         "servicelevel_name":"Priority Mail Express",
         "servicelevel_token":"usps_priority_express",
         "servicelevel_terms":"",
         "days":1,
         "duration_terms":"Overnight delivery to most U.S. locations.",
         "trackable":true,
         "insurance":true,
         "insurance_amount_local":"30.00",
         "insurance_currency_local":"USD",
         "insurance_amount":"30.00",
         "insurance_currency":"USD",
         "zone":"1",
         "messages":[],
         "test": true
      }
   ]
}

Retrieve an existing rate

Retrieve an existing rate by object id.

API Resource URL

https://api.goshippo.com/rates/<RATE OBJECT ID>

Example
curl https://api.goshippo.com/rates/ee81fab0372e419ab52245c8952ccaeb \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "object_state":"VALID",
   "object_purpose":"PURCHASE",
   "object_created":"2014-07-17T00:04:10.118Z",
   "object_updated":"2014-07-17T00:04:10.627Z",
   "object_id":"ee81fab0372e419ab52245c8952ccaeb",
   "object_owner":"shippotle@goshippo.com",
   "shipment":"89436997a794439ab47999701e60392e",
   "attributes":[],
   "amount":"5.77",
   "currency":"USD",
   "amount_local":"5.77",
   "currency_local":"USD",
   "provider":"USPS",
   "provider_image_75":"https://cdn2.goshippo.com/providers/75/USPS.png",
   "provider_image_200":"https://cdn2.goshippo.com/providers/200/USPS.png",
   "servicelevel_name":"Priority Mail",
   "servicelevel_token":"usps_priority",
   "servicelevel_terms":"",
   "days":1,
   "duration_terms":"Delivery within 1, 2, or 3 days based on where your package started and where it’s being sent.",
   "trackable":true,
   "insurance":true,
   "insurance_amount_local":"30.00",
   "insurance_currency_local":"USD",
   "insurance_amount":"30.00",
   "insurance_currency":"USD",
   "carrier_account":"t7185b2e81ea421f854bfccdc4236b17",
   "zone":"1"
   "messages":[],
   "test": true
}

Transactions (shipping labels)

A transaction is the purchase of a shipping label from a shipping provider for a specific service.

Attributes
object_state "VALID"
"INVALID"
Indicates the validity of the Transaction object based on the given data, regardless of what the corresponding carrier returns.
object_status "WAITING"
"QUEUED"
"SUCCESS"
"ERROR"
"REFUNDED"
"REFUNDPENDING"
"REFUNDREJECTED"
Indicates the status of the Transaction.
object_created datetime Date and time of Transaction creation.
object_updated datetime Date and time of last Transaction update.
object_id string Unique identifier of the given Transaction object.
object_owner string Username of the user who created the Transaction object.
rate string ID of the Rate object for which a Label has to be obtained. Please note that only rates that are not older than 7 days can be purchased in order to ensure up-to-date pricing.
metadata string A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
label_file_type "PNG"
"PDF"
"PDF_4X6"
"ZPLII"
Specify the label file format for this label. If you don't specify this value, the API will default to your default file format that you can set on the settings page.
See supported label formats per carrier here.
test bool Indicates whether the object has been created in test mode.
tracking_number string The carrier-specific tracking number that can be used to track the Shipment. A value will only be returned if the Rate is for a trackable Shipment and if the Transactions has been processed successfully.
tracking_status dict The latest tracking information of this shipment.
tracking_status.status enum Indicates the high level status of the shipment: 'UNKNOWN', 'DELIVERED', 'TRANSIT', 'FAILURE', 'RETURNED'.
tracking_status.status_details string The human-readable description of the status
tracking_status.status_date datetime Date and time when the carrier has scanned this tracking event.
tracking_status.location object An object containing zip, city, state and country information of the tracking event.
tracking_history array A list of tracking events, following the same structure as the tracking_status field. It cointains the full history of all tracking events, sorted according to the order of the tracking events.
tracking_url_provider url A link to track this item on the carrier-provided tracking website. A value will only be returned if tracking is available and the carrier provides such a service.
label_url url A URL pointing directly to the label in the format you've set in your settings. A value will only be returned if the Transactions has been processed successfully.
commercial_invoice_url url A URL pointing to the commercial invoice as a 8.5x11 inch PDF file. A value will only be returned if the Transactions has been processed successfully and if the shipment is international.
messages array An array containing elements of the following schema:
"code" (string): an identifier for the corresponding message (not always available")
"message" (string): a publishable message containing further information.
API Resource URL

https://api.goshippo.com/transactions/

Example
{
    "object_state": "VALID",
    "object_status": "SUCCESS",
    "object_created": "2013-12-27T19:14:48.273Z",
    "object_updated": "2013-12-27T19:14:48.273Z",
    "object_id": "64bba01845ef40d29374032599f22588",
    "object_owner": "shippotle@goshippo.com",
    "test": true,
    "rate": "cf6fea899f1848b494d9568e8266e076",
    "tracking_number": "ZW70QJC",
    "tracking_status": {
        "object_created": "2013-12-27T23:17:41.411Z",
        "object_id": "a21b3d6831c14ceaba6730179ce6e784",
        "status": "UNKNOWN",
        "status_details": "",
        "status_date": "2013-12-28T12:04:04.214Z"
    },
    "tracking_history": [],
    "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=ZW70QJC",
    "label_url": "https://shippo-delivery.s3.amazonaws.com/96.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
    "commercial_invoice_url": "",
    "metadata": "Customer ID 123456",
    "messages": []
}

Create a transaction (shipping label) based on a rate object

Creates a new transaction object and purchases the shipping label for the provided rate.

Attributes
rate
required
string
metadata
optional
string
label_file_type
optional
"PNG"
"PDF"
"PDF_4X6"
"ZPLII"
async
optional
boolean
API Resource URL

https://api.goshippo.com/transactions/

Example
curl https://api.goshippo.com/transactions \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -d rate="cf6fea899f1848b494d9568e8266e076"
    -d label_file_type="PDF"
    -d async=false
Response Example
{
   "object_state":"VALID",
   "object_status":"SUCCESS",
   "object_created":"2014-07-25T02:09:34.422Z",
   "object_updated":"2014-07-25T02:09:34.513Z",
   "object_id":"ef8808606f4241ee848aa5990a09933c",
   "object_owner":"shippotle@goshippo.com",
   "test":true,
   "rate":"ee81fab0372e419ab52245c8952ccaeb",
   "tracking_number":"",
   "tracking_status":null,
   "tracking_url_provider":"",
   "label_url":"",
   "commercial_invoice_url": "",
   "messages":[

   ],
   "customs_note":"",
   "submission_note":"",
   "metadata":""
}

Create a transaction (shipping label) with one API call

Creates a new transaction object and purchases the shipping label with one API call.

Attributes
shipment
required
object (see shipments)
carrier_account
required
string
servicelevel_token
required
string (see servicelevels)
metadata
optional
string
label_file_type
optional
"PNG"
"PDF"
"PDF_4X6"
"ZPLII"
API Resource URL

https://api.goshippo.com/transactions/

Example
curl https://api.goshippo.com/transactions \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -H "Content-Type: application/json" \
    -d $'{
        "shipment": {
            "object_purpose": "PURCHASE",
            "address_to": {
                "object_purpose": "PURCHASE",
                "name": "Mr Hippo",
                "street1": "965 Mission St #572",
                "city": "San Francisco",
                "state": "CA",
                "zip": "94103",
                "country": "US",
                "phone": "4151234567",
                "email": "mrhippo@goshippo.com"
            },
            "address_from": {
                "object_purpose": "PURCHASE",
                "name": "Mrs Hippo",
                "street1": "1092 Indian Summer Ct",
                "city": "San Jose",
                "state": "CA",
                "zip": "95122",
                "country": "US",
                "phone": "4159876543",
                "email": "mrshippo@goshippo.com"
            },
            "parcel": {
                "length": "10",
                "width": "15",
                "height": "10",
                "distance_unit": "in",
                "weight": "1",
                "mass_unit": "lb"
            }
        },
        "carrier_account": "b741b99f95e841639b54272834bc478c",
        "servicelevel_token": "usps_priority"
        }'
Response Example
{
   "object_state":"VALID",
   "object_status":"SUCCESS",
   "object_created":"2014-07-25T02:09:34.422Z",
   "object_updated":"2014-07-25T02:09:34.513Z",
   "object_id":"ef8808606f4241ee848aa5990a09933c",
   "object_owner":"shippotle@goshippo.com",
   "test":true,
   "rate":"ee81fab0372e419ab52245c8952ccaeb",
   "tracking_number":"",
   "tracking_status":null,
   "tracking_url_provider":"",
   "label_url":"",
   "commercial_invoice_url": "",
   "messages":[

   ],
   "customs_note":"",
   "submission_note":"",
   "metadata":""
}

Retrieve a transaction

Retrieve an existing transaction by object id.

API Resource URL

https://api.goshippo.com/transactions/<TRANSACTION OBJECT ID>

Example
curl https://api.goshippo.com/transactions/70ae8117ee1749e393f249d5b77c45e0 \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "object_state":"VALID",
   "object_status":"SUCCESS",
   "object_created":"2014-07-17T00:43:40.842Z",
   "object_updated":"2014-07-17T00:43:50.531Z",
   "object_id":"70ae8117ee1749e393f249d5b77c45e0",
   "object_owner":"shippotle@goshippo.com",
   "test":true,
   "rate":"ee81fab0372e419ab52245c8952ccaeb",
   "tracking_number":"9499907123456123456781",
   "tracking_status":{
      "object_created":"2014-07-17T00:43:50.402Z",
      "object_id":"907d5e6120ed491ea27d4f681a7ccd4d",
      "status":"UNKNOWN",
      "status_details":"",
      "status_date":null
   },
   "tracking_history":[
      {
         "object_created":"2014-07-17T00:43:50.402Z",
         "object_id":"907d5e6120ed491ea27d4f681a7ccd4d",
         "status":"UNKNOWN",
         "status_details":"",
         "status_date":null
      },
   ],
   "tracking_url_provider":"https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781",
   "label_url":"https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
   "commercial_invoice_url": "",
   "messages":[],
   "customs_note":"",
   "submission_note":"",
   "metadata":""
}

List all transactions

List all transaction objects.

API Resource URL

https://api.goshippo.com/transactions/?results=<XX>

Example
curl https://api.goshippo.com/transactions/ \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "count":5,
   "next":null,
   "previous":null,
   "results":[
      {
         "object_state":"VALID",
         "object_status":"SUCCESS",
         "object_created":"2014-07-17T00:43:40.842Z",
         "object_updated":"2014-07-17T00:43:50.531Z",
         "object_id":"70ae8117ee1749e393f249d5b77c45e0",
         "object_owner":"shippotle@goshippo.com",
         "test":true,
         "rate":"ee81fab0372e419ab52245c8952ccaeb",
         "tracking_number":"9499907123456123456781",
         "tracking_status":{
            "object_created":"2014-07-17T00:43:50.402Z",
            "object_id":"907d5e6120ed491ea27d4f681a7ccd4d",
            "status":"UNKNOWN",
            "status_details":"",
            "status_date":null
         },
         "tracking_history":[
            {
               "object_created":"2014-07-17T00:43:50.402Z",
               "object_id":"907d5e6120ed491ea27d4f681a7ccd4d",
               "status":"UNKNOWN",
               "status_details":"",
               "status_date":null
            },
         ],
         "tracking_url_provider":"https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781",
         "label_url":"https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
         "commercial_invoice_url": "",
         "messages":[

         ],
         "customs_note":"",
         "submission_note":"",
         "metadata":""
      },
      {...},
      {...}
   ]
}

Customs Items

Customs items are distinct items in your international shipment parcel.

Attributes
object_state "VALID"
"INVALID"
Indicates the validity of the Customs Item.
object_created datetime Date and time of object creation.
object_updated datetime Date and time of last object update.
object_id string Unique identifier of the given object.
object_owner string Username of the user who created the object.
description string Text description of your item.
quantity int Quantity of this item in the shipment you send. Must be greater than 0.
net_weight decimal Total weight of this item, i.e. quantity * weight per item.
mass_unit "g"
"oz"
"lb"
"kg"
The unit used for net_weight.
value_amount decimal Total value of this item, i.e. quantity * value per item.
value_currency ISO 4217 Currency Code (string) Currency used for value_amount. The official ISO 4217 currency codes are used, e.g. "USD" or "EUR".
origin_country ISO 3166-1-alpha-2 code (ISO 2 country code) Country of origin of the item. Example: 'US' or 'DE'. All accepted values can be found on the Official ISO Website.
tariff_number string The tariff number of the item.
metadata string A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
test bool Indicates whether the object has been created in test mode.
API Resource URL

https://api.goshippo.com/customs/items/

Example
{
    "object_created": "2014-02-24T22:05:55.014",
    "object_updated": "2014-02-24T22:05:55.016",
    "object_id": "0265b7cc4d71468197b2e8584cf8fc05",
    "object_owner": "shippotle@goshippo.com",
    "object_state": "VALID",
    "description": "T-Shirt",
    "quantity": 2,
    "net_weight": "400",
    "mass_unit": "g",
    "value_amount": "20",
    "value_currency": "USD",
    "tariff_number": "",
    "origin_country": "US",
    "metadata": "Order ID #123123",
    "test": true
}

Create a new customs item

Creates a new Customs Item object.

Attributes
description
required
string
quantity
required
int
net_weight
required
decimal
mass_unit
required
"g"
"oz"
"lb"
"kg"
value_amount
required
decimal
value_currency
required
ISO 4217 Currency Code (string)
origin_country
required
ISO 3166-1-alpha-2 code (ISO 2 country code)
tariff_number
optional
string
metadata
optional
string
API Resource URL

https://api.goshippo.com/customs/items/

Example
curl  https://api.goshippo.com/customs/items/ \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -d description="T-Shirt" \
    -d quantity=2 \
    -d net_weight="400" \
    -d mass_unit="g" \
    -d value_amount="20" \
    -d value_currency="USD" \
    -d tariff_number="" \
    -d origin_country="US" \
    -d metadata="Order ID '123123'"
Response Example
{
   "object_created":"2014-07-17T00:49:20.631Z",
   "object_updated":"2014-07-17T00:49:20.631Z",
   "object_id":"55358464c7b740aca199b395536981bd",
   "object_owner":"shippotle@goshippo.com",
   "object_state":"VALID",
   "description":"T-Shirt",
   "quantity":2,
   "net_weight":"400",
   "mass_unit":"g",
   "value_amount":"20",
   "value_currency":"USD",
   "origin_country":"US",
   "tariff_number":"",
   "metadata":"Order ID '123123'",
   "test": true
}

Retrieve an existing Customs Item

Retrieve an existing Customs Item by object id.

API Resource URL

https://api.goshippo.com/customs/items/<CUSTOMS ITEM OBJECT ID>

Example
curl  https://api.goshippo.com/customs/items/55358464c7b740aca199b395536981bd \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "object_created":"2014-07-17T00:49:20.631Z",
   "object_updated":"2014-07-17T00:49:20.631Z",
   "object_id":"55358464c7b740aca199b395536981bd",
   "object_owner":"shippotle@goshippo.com",
   "object_state":"VALID",
   "description":"T-Shirt",
   "quantity":2,
   "net_weight":"400.0000",
   "mass_unit":"g",
   "value_amount":"20.00",
   "value_currency":"USD",
   "origin_country":"US",
   "tariff_number":"",
   "metadata":"Order ID '123123'",
   "test": true
}

List all Customs Items

List all custom-items objects.

API Resource URL

https://api.goshippo.com/customs/items/

Example
curl  https://api.goshippo.com/customs/items/ \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "count":10,
   "next":null,
   "previous":null,
   "results":[
      {
         "object_created":"2014-07-17T00:49:20.631Z",
         "object_updated":"2014-07-17T00:49:20.631Z",
         "object_id":"55358464c7b740aca199b395536981bd",
         "object_owner":"shippotle@goshippo.com",
         "object_state":"VALID",
         "description":"T-Shirt",
         "quantity":2,
         "net_weight":"400.0000",
         "mass_unit":"g",
         "value_amount":"20.00",
         "value_currency":"USD",
         "origin_country":"US",
         "tariff_number":"",
         "metadata":"Order ID '123123'",
         "test": true
      },
      {...},
      {...}
   ]
}

Customs Declarations

Customs declarations are relevant information, including one or multiple customs items, you need to provide for customs clearance for your international shipments.

Attributes
object_state "VALID"
"INVALID"
Indicates the validity of the Customs Item.
object_created datetime Date and time of object creation.
object_updated datetime Date and time of last object update.
object_id string Unique identifier of the given object.
object_owner string Username of the user who created the object.
certify_signer string Name of the person who created the customs declaration and is responsible for the validity of all information provided.
certify boolean Expresses that the certify_signer has provided all information of this customs declaration truthfully.
items Array of Customs Items object_ids Distinct Parcel content items as Customs Items object_ids.
non_delivery_option 'ABANDON',
'RETURN'
Indicates how the carrier should proceed in case the shipment can't be delivered.
contents_type 'DOCUMENTS',
'GIFT',
'SAMPLE',
'MERCHANDISE',
'HUMANITARIAN_
DONATION',
'RETURN_
MERCHANDISE',
'OTHER'
Type of goods of the shipment.
contents_explanation string Explanation of the type of goods of the shipment.
exporter_reference string Experter reference of an export shipment.
importer_reference string Importer reference of an import shipment.
invoice string Invoice reference of the shipment.
license string License reference of the shipment.
certificate string Certificate reference of the shipment.
notes string Additional notes to be included in the customs declaration.
eel_pfc 'NOEEI_30_37_a',
'NOEEI_30_37_h',
'NOEEI_30_37_f',
'NOEEI_30_36',
'AES_ITN'
EEL / PFC type of the shipment. For most shipments from the US to CA, 'NOEEI_30_36' is applicable; for most other shipments from the US, 'NOEEI_30_37_a' is applicable.
aes_itn string AES / ITN reference of the shipment.
incoterm 'DDP',
'DDU',
'CPT',
'CIP'
The incoterm reference of the shipment.
metadata string A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
disclaimer string Disclaimer for the shipment and customs information that have been provided.
test bool Indicates whether the object has been created in test mode.
API Resource URL

https://api.goshippo.com/customs/declarations/

Example
{
    "object_created": "2014-02-24T22:35:44.358",
    "object_updated": "2014-02-24T22:35:44.358",
    "object_id": "b741b99f95e841639b54272834bc478c",
    "object_owner": "shippotle@goshippo.com",
    "object_state": "VALID",
    "exporter_reference": "",
    "importer_reference": "",
    "contents_type": "MERCHANDISE",
    "contents_explanation": "T-Shirt purchase",
    "invoice": "#123123",
    "license": "",
    "certificate": "",
    "notes": "",
    "eel_pfc": "NOEEI_30_37_a",
    "aes_itn": "",
    "non_delivery_option": "ABANDON",
    "certify": true,
    "certify_signer": "Shawn Ippotle",
    "disclaimer": "",
    "incoterm": "",
    "items": [
        "0c1a723687164307bb2175972fbcd9ef"
    ],
    "metadata": "Order ID #123123",
    "test": true
}

Create a new Customs Declaration

Creates a new Customs Declaration object.

Attributes
certify_signer
required
string
certify
required
boolean
items
required
Array of Customs Items object_ids
non_delivery_option
required
'ABANDON',
'RETURN'
contents_type
required
'DOCUMENTS',
'GIFT',
'SAMPLE',
'MERCHANDISE',
'HUMANITARIAN_
DONATION',
'RETURN_
MERCHANDISE',
'OTHER'
contents_explanation
required if contents_type is 'OTHER'
string
exporter_reference
optional
string
importer_reference
optional
string
invoice
optional
string
license
optional
string
certificate
optional
string
notes
optional
string
eel_pfc
optional
'NOEEI_30_37_a',
'NOEEI_30_37_h',
'NOEEI_30_36',
'AES_ITN'
aes_itn
required if eel_pfc is 'AES_ITN'
string
incoterm
optional
'DDP',
'DDU',
'CPT',
'CIP'
metadata
optional
string
API Resource URL

https://api.goshippo.com/customs/declarations/

Example
curl https://api.goshippo.com/customs/declarations/ \
    -H "Authorization: ShippoToken " \
    -H "Content-Type: application/json"  \
    -d '{          
          "contents_type": "MERCHANDISE",
          "non_delivery_option": "RETURN",
          "certify": true,
          "certify_signer": "Simon Kreuz",
          "incoterm": "DDU",
          "items": [{
                    "description": "T-shirt",
                    "quantity": 20,
                    "net_weight": "5",
                    "mass_unit": "lb",
                    "value_amount": "200",
                    "value_currency": "USD",
                    "tariff_number": "",
                    "origin_country": "US"
            }]
    }'
Response Example
{
   "object_created":"2014-07-17T01:01:08.306Z",
   "object_updated":"2014-07-17T01:01:08.306Z",
   "object_id":"e2197a54da9d470480f4f8796cc419cb",
   "object_owner":"shippotle@goshippo.com",
   "object_state":"VALID",
   "certify_signer":"Shawn Ippotle",
   "certify":true,
   "items":[
      "5087f181d1dc4b14b73fdbf636498886"
   ],
   "non_delivery_option":"ABANDON",
   "contents_type":"MERCHANDISE",
   "contents_explanation":"T-Shirt purchase",
   "exporter_reference":"",
   "importer_reference":"",
   "invoice":"#123123",
   "commercial_invoice":false,
   "license":"",
   "certificate":"",
   "notes":"",
   "eel_pfc":"NOEEI_30_37_a",
   "aes_itn":"",
   "disclaimer":"",
   "incoterm":"",
   "metadata":"Order ID #123123",
   "test": true
}

Retrieve an existing Customs Declaration

Retrieve an existing customs-declaration by object id.

API Resource URL

https://api.goshippo.com/customs/declarations/<CUSTOMS DEC. OBJECT ID>

Example
curl https://api.goshippo.com/customs/declarations/e2197a54da9d470480f4f8796cc419cb \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "object_created":"2014-07-17T01:01:08.306Z",
   "object_updated":"2014-07-17T01:01:08.306Z",
   "object_id":"e2197a54da9d470480f4f8796cc419cb",
   "object_owner":"shippotle@goshippo.com",
   "object_state":"VALID",
   "certify_signer":"Shawn Ippotle",
   "certify":true,
   "items":[
      "5087f181d1dc4b14b73fdbf636498886"
   ],
   "non_delivery_option":"ABANDON",
   "contents_type":"MERCHANDISE",
   "contents_explanation":"T-Shirt purchase",
   "exporter_reference":"",
   "importer_reference":"",
   "invoice":"#123123",
   "commercial_invoice":false,
   "license":"",
   "certificate":"",
   "notes":"",
   "eel_pfc":"NOEEI_30_37_a",
   "aes_itn":"",
   "disclaimer":"",
   "incoterm":"",
   "metadata":"Order ID #123123",
   "test": true
}

List all customs declarations

List all customs-declaration objects.

API Resource URL

https://api.goshippo.com/customs/declarations/

Example
curl https://api.goshippo.com/customs/declarations/ \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "count":11,
   "next":null,
   "previous":null,
   "results":[
      {
         "object_created":"2014-07-17T01:01:08.306Z",
         "object_updated":"2014-07-17T01:01:08.306Z",
         "object_id":"e2197a54da9d470480f4f8796cc419cb",
         "object_owner":"shippotle@goshippo.com",
         "object_state":"VALID",
         "certify_signer":"Shawn Ippotle",
         "certify":true,
         "items":[
            "5087f181d1dc4b14b73fdbf636498886"
         ],
         "non_delivery_option":"ABANDON",
         "contents_type":"MERCHANDISE",
         "contents_explanation":"T-Shirt purchase",
         "exporter_reference":"",
         "importer_reference":"",
         "invoice":"#123123",
         "commercial_invoice":false,
         "license":"",
         "certificate":"",
         "notes":"",
         "eel_pfc":"NOEEI_30_37_a",
         "aes_itn":"",
         "disclaimer":"",
         "incoterm":"",
         "metadata":"Order ID #123123",
         "test": true
      },
      {...},
      {...}
   ]
}

Refunds

Refunds are reimbursements for successfully created but unused Transaction.

Please keep the following in mind:

  • Once a Refund has been claimed, you must not use the shipping label for actual postage.
  • Refunds take 14 days to be processed.
  • Some carriers, e.g. FedEx and UPS, don't require refunds since the corresponding labels will only be charged after they have been scanned, i.e. used. The Shippo refund may be used for refunding of the $0.05 Shippo label fee.
Attributes
object_created datetime Date and time of object creation.
object_updated datetime Date and time of last object update.
object_id string Unique identifier of the given object.
object_owner string Username of the user who created the object.
object_status "QUEUED"
"PENDING"
"SUCCESS"
"ERROR"
Indicates the status of the Refund.
transaction string Object ID of the Transaction to be refunded.
test bool Indicates whether the object has been created in test mode.
Additional response attributes
API Resource URL

https://api.goshippo.com/refunds/

Example
{
    "object_created": "2014-04-21T07:12:41.044Z",
    "object_updated": "2014-04-21T07:12:41.045Z",
    "object_id": "bd7b8379a2e847bcb0818125943dde5d",
    "object_owner": "shippotle@goshippo.com",
    "object_status": "SUCCESS",
    "transaction": "35ed59f23a514ecfa2faeaed93a00086",
    "test": true
}

Create a new refund

Creates a new refund object.

Attributes
transaction
required
string
async
optional
boolean
API Resource URL

https://api.goshippo.com/refunds/

Example
curl  https://api.goshippo.com/refunds/ \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -d transaction="4503427478ea45a899e9b54abc4c5803"	
Response Example
{
   "object_created":"2014-07-17T15:38:37.372Z",
   "object_updated":"2014-07-17T15:38:37.381Z",
   "object_id":"d7c811cff9e24e4387418876f1ffd371",
   "object_owner":"shippotle@goshippo.com",
   "object_status":"SUCCESS",
   "transaction":"8b7f25f33d2a4bb58060df94cb152434",
   "test": true
}

Retrieve an existing refund

Retrieve an existing refund by object id.

API Resource URL

https://api.goshippo.com/refunds/<REFUND OBJECT ID>

Example
curl https://api.goshippo.com/refunds/d7c811cff9e24e4387418876f1ffd371 \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "object_created":"2014-07-17T15:38:37.372Z",
   "object_updated":"2014-07-17T15:38:43.070Z",
   "object_id":"d7c811cff9e24e4387418876f1ffd371",
   "object_owner":"shippotle@goshippo.com",
   "object_status":"SUCCESS",
   "transaction":"8b7f25f33d2a4bb58060df94cb152434",
   "test": true
}

List all refund objects.

Retrieve an existing refund by object id.

API Resource URL

https://api.goshippo.com/refunds/

Example
curl https://api.goshippo.com/refunds/ \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "count":2,
   "next":null,
   "previous":null,
   "results":[
      {
         "object_created":"2014-07-17T15:38:37.372Z",
         "object_updated":"2014-07-17T15:38:43.070Z",
         "object_id":"d7c811cff9e24e4387418876f1ffd371",
         "object_owner":"shippotle@goshippo.com",
         "object_status":"SUCCESS",
         "transaction":"8b7f25f33d2a4bb58060df94cb152434",
         "test": true
      },
      {...}
   ]
}

Manifests

Manifests are close-outs of shipping labels of a certain day. Some carriers require Manifests to properly process the shipments.

The following carriers require Manifests:

  • USPS: the USPS allows you to create "scan forms", which also is a Manifest. By creating scan forms, the USPS doesn't need to scan each of your packages individually and all tracking codes are updated immediately.
  • Canada Post: contract customers that ship more than 50 shipments a day will need to create manifests to transmit the shipments for billing for a given day. Contract customers that ship less than 50 daily can usually skip the manifest requirement, but are encouraged to verify with Canada Post. If a contract customer doesn't close out a shipment day by creating a manifest, Canada Post may bill for & transmit the shipments on customer's behalf.
  • Australia Post: all Australia Post customers need to manifest their daily shipments.
  • Newgistics: create daily manifests.

You can't refund shipments after you have created a Manifest for them.

Attributes
object_created datetime Date and time of object creation.
object_updated datetime Date and time of last object update.
object_id string Unique identifier of the given object.
object_owner string Username of the user who created the object.
object_status "QUEUED"
"SUCCESS"
"ERROR"
Indicates the status of the Manifest.
carrier_account string ID of carrier account
submission_date datetime All shipments to be submitted on this day will be closed out. Must be in the format "2014-01-18T00:35:03.463Z" (ISO 8601 date).
address_from string ID of the Address object that should be used as pickup address for the scan form. The USPS will validate this address before creating the scan form.
transactions array IDs transactions to use. If you set this to null or not send this parameter, Shippo will automatically assign all applicable transactions.
documents array An array containing the URLs to all returned Manifest documents.
API Resource URL

https://api.goshippo.com/manifests/

Example
{
    "object_created": "2014-05-16T03:43:52.765Z",
    "object_updated": "2014-05-16T03:43:55.445Z",
    "object_id": "0fadebf6f60c4aca95fa01bcc59c79ae",
    "object_owner": "mrhippo@goshippo.com",
    "object_status": "SUCCESS",
    "carrier_account": "b741b99f95e841639b54272834bc478c",
    "submission_date": "2014-05-16T23:59:59Z",
    "address_from": "28828839a2b04e208ac2aa4945fbca9a",
    "transactions": ["64bba01845ef40d29374032599f22588", "c169aa586a844cc49da00d0272b590e1"],
    "documents": [
        "https://shippo-delivery.s3.amazonaws.com/0fadebf6f60c4aca95fa01bcc59c79ae.pdf?Signature=tlQU3RECwdHUQJQadwqg5bAzGFQ%3D&Expires=1402803835&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
    ]
}

Create a new manifest

Creates a new manifest object.

Attributes
carrier_account
required
string
submission_date
required
datetime
address_from
optional
string
transactions
optional
array of Transaction object_ids
async
optional
boolean
API Resource URL

https://api.goshippo.com/manifests/

Example
curl https://api.goshippo.com/manifests/ \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -d carrier_account="b741b99f95e841639b54272834bc478c", \
    -d submission_date="2014-05-16T23:59:59Z" \
    -d address_from="d799c2679e644279b59fe661ac8fa488" \
    -d transactions=["64bba01845ef40d29374032599f22588", "c169aa586a844cc49da00d0272b590e1"] \
    -d async=false
Response Example
{
    "object_created": "2014-05-16T03:43:52.765Z",
    "object_updated": "2014-05-16T03:43:55.445Z",
    "object_id": "0fadebf6f60c4aca95fa01bcc59c79ae",
    "object_owner": "mrhippo@goshippo.com",
    "object_status": "SUCCESS",
    "carrier_account": "b741b99f95e841639b54272834bc478c",
    "submission_date": "2014-05-16T23:59:59Z",
    "address_from": "d799c2679e644279b59fe661ac8fa488",
    "transactions": ["64bba01845ef40d29374032599f22588", "c169aa586a844cc49da00d0272b590e1"],
    "documents": [
        "https://shippo-delivery.s3.amazonaws.com/0fadebf6f60c4aca95fa01bcc59c79ae.pdf?Signature=tlQU3RECwdHUQJQadwqg5bAzGFQ%3D&Expires=1402803835&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
    ]
}

Retrieve an existing manifest

Retrieve an existing manifest by object id.

API Resource URL

https://api.goshippo.com/manifests/<MANIFEST OBJECT ID>

Example
curl https://api.goshippo.com/manifests/0fadebf6f60c4aca95fa01bcc59c79ae \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "object_created":"2014-05-16T03:43:52.765Z",
   "object_updated":"2014-05-16T03:43:55.445Z",
   "object_id":"0fadebf6f60c4aca95fa01bcc59c79ae",
   "object_owner":"mrhippo@goshippo.com",
   "object_status":"SUCCESS",
   "carrier_account": "b741b99f95e841639b54272834bc478c",
   "submission_date":"2014-05-16T23:59:59Z",
   "address_from":"008ee72b723c4f129371b7346fe2f55f",
   "transactions": ["64bba01845ef40d29374032599f22588", "c169aa586a844cc49da00d0272b590e1"],
   "documents":[
      "https://shippo-delivery.s3.amazonaws.com/0fadebf6f60c4aca95fa01bcc59c79ae.pdf?Signature=tlQU3RECwdHUQJQadwqg5bAzGFQ%3D&Expires=1402803835&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
   ]
}

List all manifests

List all Manifest objects.

API Resource URL

https://api.goshippo.com/manifests/

Example
curl https://api.goshippo.com/manifests/ \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "count":2,
   "next":null,
   "previous":null,
   "results":[
      {
         "object_created":"2014-07-17T16:09:46.079Z",
         "object_updated":"2014-07-17T16:09:46.079Z",
         "object_id":"aa41ad380c53413ab2cee8ba98d2cc34",
         "object_owner":"mrhippo@goshippo.com",
         "object_status":"SUCCESS",
         "carrier_account": "b741b99f95e841639b54272834bc478c",
         "submission_date":"2014-05-16T23:59:59Z",
         "address_from":"d799c2679e644279b59fe661ac8fa488",
         "transactions": ["64bba01845ef40d29374032599f22588", "c169aa586a844cc49da00d0272b590e1"],
         "documents": [
            "https://shippo-delivery.s3.amazonaws.com/0fadebf6f60c4aca95fa01bcc59c79ae.pdf?Signature=tlQU3RECwdHUQJQadwqg5bAzGFQ%3D&Expires=1402803835&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
         ]
      },
      {...}
   ]
}

Carrier Accounts

Carrier accounts are used as credentials to retrieve shipping rates and purchase labels from a shipping provider. They can be updated via PUT requests, however carrier account objects cannot be deleted.

Attributes
object_id string Unique identifier of the carrier account object.
object_owner string Username of the user who created the carrier account object.
carrier string Name of the carrier. Please check the carrier accounts tutorial page for all supported carrier names.
account_id string Unique identifier of the account. Please check the carrier accounts tutorial page for the account_id per carrier.
parameters array An array of additional parameters for the account, such as e.g. password or token. Please check the carrier accounts tutorial page for the parameters per carrier.
test boolean Indicates whether the object has been created in test mode.
active boolean Determines whether the account is active. When creating a shipment, if no carrier_accounts are explicitly passed Shippo will query all carrier accounts that have this field set. By default, this is set to True.
API Resource URL

https://api.goshippo.com/carrier_accounts/

Example
{
    "object_id":"b741b99f95e841639b54272834bc478c",
    "object_owner": "shippotle@goshippo.com",
    "carrier": "fedex",
    "account_id": "321123",
    "parameters": {
        "meter": "789987"
    },
    "test": false,
    "active": true
}

Create a new carrier account

Creates a new carrier account object.

Attributes
carrier
required
string Name of the carrier. Please check the Carrier Capabilities page for all supported carrier names.
account_id
required
string Unique identifier of the account. Please check the Carrier Capabilities page for the account_id per carrier.
parameters
required
array An array of additional parameters for the account, such as e.g. password or token. Please check the Carrier Capabilities page for the parameters per carrier.
active
optional
boolean Determines whether the account is enabled. Default is enabled.
API Resource URL

https://api.goshippo.com/carrier_accounts/

Example
curl https://api.goshippo.com/carrier_accounts/ \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -d carrier="fedex" \
    -d account_id="321123" \
    -d parameters='{ "meter": "789987"}'
Response Example
{
    "object_id":"b741b99f95e841639b54272834bc478c",
    "object_owner": "shippotle@goshippo.com",
    "carrier": "fedex",
    "account_id": "321123",
    "parameters": {
        "meter": "789987"
    },
    "test": false,
    "active": true
}

Retrieve an existing carrier account

Retrieve an existing carrier account by object id.

API Resource URL

https://api.goshippo.com/carrier_accounts/<CARRIER ACCOUNT OBJECT ID>

Example
curl https://api.goshippo.com/carrier_accounts/b741b99f95e841639b54272834bc478c \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
    "object_id":"b741b99f95e841639b54272834bc478c",
    "object_owner": "shippotle@goshippo.com",
    "carrier": "fedex",
    "account_id": "321123",
    "parameters": {
        "meter": "789987"
    },
    "test": false,
    "active": true
}

List all carrier accounts

List all carrier accounts.

API Resource URL

https://api.goshippo.com/carrier_accounts/

Example
curl https://api.goshippo.com/carrier_accounts/ \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
   "count":3,
   "next":null,
   "previous":null,
   "results":[
         {
            "object_id":"b741b99f95e841639b54272834bc478c",
             "object_owner": "shippotle@goshippo.com",
             "carrier": "fedex",
             "account_id": "321123",
             "parameters": {
                 "meter": "789987"
             },
             "test": false,
             "active": true
         },
         {...},
         {...}
   ]
}

Update an existing carrier account

PUT request to update an existing carrier account object. The account_id and carrier can't be updated, because they form the unique identifier together.

Attributes
carrier
required
string Name of the carrier. Please check the Carrier Capabilities page for all supported carrier names.
account_id
required
string Unique identifier of the account. Please check the Carrier Capabilities page for the account_id per carrier.
parameters
optional
array An array of additional parameters for the account, such as e.g. password or token. Please check the Carrier Capabilities page for the parameters per carrier.
active
optional
boolean Determines whether the account is active. When creating a shipment, if no carrier_accounts are explicitly passed Shippo will query all carrier accounts that have this field set. By default, this is set to True.
API Resource URL

https://api.goshippo.com/carrier_accounts/<CARRIER ACCOUNT OBJECT ID>

Example
curl https://api.goshippo.com/carrier_accounts/b741b99f95e841639b54272834bc478c/ \
    -X PUT  \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -d parameters='{
        "meter": "123987"
    }'
Response Example
{
    "object_id":"b741b99f95e841639b54272834bc478c",
    "object_owner": "shippotle@goshippo.com",
    "carrier": "fedex",
    "account_id": "321123",
    "parameters": {
        "meter": "123987"
    },
    "test": false,
    "active": true
}

Tracking Status

If you purchased your shipping label through Shippo, you can also get all the tracking details of your Shipment from the Transaction object.

Tracking Status objects are used to track any shipment as long as you have it's tracking number, and know what carrier it was sent with. You can send GET requests to the Tracking endpoint to get the tracking status of a Shipment. Alternatively you can POST to the endpoint to automatically get webhook updates whenever the tracking status of the shipment changes.

Attributes
carrier string Name of the carrier of the shipment to track. See Carriers.
tracking_number string Tracking number to track.
address_from hash The sender address with city, state, zip and country information.
address_to hash The recipient address with city, state, zip and country information.
eta datetime The estimated time of arrival according to the carrier.
servicelevel hash The service level of the shipment as token and full name.
tracking_status hash The latest tracking information of this shipment.
tracking_status.status enum Indicates the high level status of the shipment: 'UNKNOWN', 'DELIVERED', 'TRANSIT', 'FAILURE', 'RETURNED'.
tracking_status.status_details string The human-readable description of the status.
tracking_status.status_date datetime Date and time when the carrier scanned this tracking event. This is displayed in UTC.
tracking_status.location object An object containing zip, city, state and country information of the tracking event.
tracking_history array A list of tracking events, following the same structure as tracking_status. It contains a full history of all tracking statuses, starting with the earlier tracking event first.
metadata string A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
Additional response attributes
API Resource URL

https://api.goshippo.com/tracks/

Example
{
  "carrier": "usps",
  "tracking_number": "9205590164917312751089",
  "address_from": {
    "city": "Las Vegas",
    "state": "NV",
    "zip": "89101",
    "country": "US"
  },
  "address_to": {
    "city": "Spotsylvania",
    "state": "VA",
    "zip": "22551",
    "country": "US"
  },
  "eta": "2016-07-23T00:00:00Z",
  "servicelevel": {
    "token": "usps_priority",
    "name": "Priority Mail"
  },
  "metadata": null,
  "tracking_status": {
    "object_created": "2016-07-23T20:35:26.129Z",
    "object_updated": "2016-07-23T20:35:26.129Z",
    "object_id": "ce48ff3d52a34e91b77aa98370182624",
    "status": "DELIVERED",
    "status_details": "Your shipment has been delivered at the destination mailbox.",
    "status_date": "2016-07-23T13:03:00Z",
    "location": {
      "city": "Spotsylvania",
      "state": "VA",
      "zip": "22551",
      "country": "US"
    }
  },
  "tracking_history": [
    {
      "object_created": "2016-07-22T14:36:50.943Z",
      "object_id": "265c7a7c23354da5b87b2bf52656c625",
      "status": "TRANSIT",
      "status_details": "Your shipment has been accepted.",
      "status_date": "2016-07-21T15:33:00Z",
      "location": {
        "city": "Las Vegas",
        "state": "NV",
        "zip": "89101",
        "country": "US"
      }
    },
    ...

    {
      "object_created": "2016-07-23T20:35:26.129Z",
      "object_id": "aab1d7c0559d43ccbba4ff8603089e56",
      "status": "DELIVERED",
      "status_details": "Your shipment has been delivered at the destination mailbox.",
      "status_date": "2016-07-23T13:03:00Z",
      "location": {
        "city": "Spotsylvania",
        "state": "VA",
        "zip": "22551",
        "country": "US"
      }
    }
  ]
}

Get a tracking update

Request the tracking status of a shipment by sending a GET request.

API Resource URL

https://api.goshippo.com/tracks/<CARRIER>/<TRACKING NUMBER>/

Example
curl https://api.goshippo.com/tracks/usps/9205590164917312751089 \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
  "carrier": "usps",
  "tracking_number": "9205590164917312751089",
  "address_from": {
    "city": "Las Vegas",
    "state": "NV",
    "zip": "89101",
    "country": "US"
  },
  "address_to": {
    "city": "Spotsylvania",
    "state": "VA",
    "zip": "22551",
    "country": "US"
  },
  "eta": "2016-07-23T00:00:00Z",
  "servicelevel": {
    "token": "usps_priority",
    "name": "Priority Mail"
  },
  "metadata": null,
  "tracking_status": {
    "object_created": "2016-07-23T20:35:26.129Z",
    "object_updated": "2016-07-23T20:35:26.129Z",
    "object_id": "ce48ff3d52a34e91b77aa98370182624",
    "status": "DELIVERED",
    "status_details": "Your shipment has been delivered at the destination mailbox.",
    "status_date": "2016-07-23T13:03:00Z",
    "location": {
      "city": "Spotsylvania",
      "state": "VA",
      "zip": "22551",
      "country": "US"
    }
  },
  "tracking_history": [
    {
      "object_created": "2016-07-22T14:36:50.943Z",
      "object_id": "265c7a7c23354da5b87b2bf52656c625",
      "status": "TRANSIT",
      "status_details": "Your shipment has been accepted.",
      "status_date": "2016-07-21T15:33:00Z",
      "location": {
        "city": "Las Vegas",
        "state": "NV",
        "zip": "89101",
        "country": "US"
      }
    },
    ...

    {
      "object_created": "2016-07-23T20:35:26.129Z",
      "object_id": "aab1d7c0559d43ccbba4ff8603089e56",
      "status": "DELIVERED",
      "status_details": "Your shipment has been delivered at the destination mailbox.",
      "status_date": "2016-07-23T13:03:00Z",
      "location": {
        "city": "Spotsylvania",
        "state": "VA",
        "zip": "22551",
        "country": "US"
      }
    }
  ]
}

Register a tracking webhook

You can register your webhook(s) for a Shipment (and request the current status at the same time) by POSTing to the tracking endpoint. This way Shippo will send HTTP notifications to your track_updated webhook(s) whenever the status changes.

Attributes
carrier
required
string Name of the carrier of the shipment to track. See Carriers.
tracking_number
required
string Tracking number to track.
metadata
optional
string A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
API Resource URL

https://api.goshippo.com/tracks/

Example
curl https://api.goshippo.com/tracks/ \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -d carrier="usps" \
    -d tracking_number="9205590164917312751089" \
    -d metadata="Order 000123"
Response Example
{
  "carrier": "usps",
  "tracking_number": "9205590164917312751089",
  "address_from": {
    "city": "Las Vegas",
    "state": "NV",
    "zip": "89101",
    "country": "US"
  },
  "address_to": {
    "city": "Spotsylvania",
    "state": "VA",
    "zip": "22551",
    "country": "US"
  },
  "eta": "2016-07-23T00:00:00Z",
  "servicelevel": {
    "token": "usps_priority",
    "name": "Priority Mail"
  },
  "metadata": null,
  "tracking_status": {
    "object_created": "2016-07-23T20:35:26.129Z",
    "object_updated": "2016-07-23T20:35:26.129Z",
    "object_id": "ce48ff3d52a34e91b77aa98370182624",
    "status": "DELIVERED",
    "status_details": "Your shipment has been delivered at the destination mailbox.",
    "status_date": "2016-07-23T13:03:00Z",
    "location": {
      "city": "Spotsylvania",
      "state": "VA",
      "zip": "22551",
      "country": "US"
    }
  },
  "tracking_history": [
    {
      "object_created": "2016-07-22T14:36:50.943Z",
      "object_id": "265c7a7c23354da5b87b2bf52656c625",
      "status": "TRANSIT",
      "status_details": "Your shipment has been accepted.",
      "status_date": "2016-07-21T15:33:00Z",
      "location": {
        "city": "Las Vegas",
        "state": "NV",
        "zip": "89101",
        "country": "US"
      }
    },
    ...

    {
      "object_created": "2016-07-23T20:35:26.129Z",
      "object_id": "aab1d7c0559d43ccbba4ff8603089e56",
      "status": "DELIVERED",
      "status_details": "Your shipment has been delivered at the destination mailbox.",
      "status_date": "2016-07-23T13:03:00Z",
      "location": {
        "city": "Spotsylvania",
        "state": "VA",
        "zip": "22551",
        "country": "US"
      }
    }
  ]
}

Batches

The batch endpoint allows you to create and purchase up to 10,000 shipments in one API call. After creating the batch, retrieve the batch to verify that all shipments are valid. You can add and remove shipments after the batch has been created. When all shipments are valid you can purchase the batch and retrieve the shipping labels.

Attributes
object_status "VALIDATING"
"VALID"
"INVALID"
"PURCHASING"
"PURCHASED"
Batches that are VALIDATING are being created and validated

VALID batches can be purchased

INVALID batches cannot be purchased, INVALID BatchShipments must be removed

Batches that are in the PURCHASING state are being purchased

PURCHASED batches are finished purchasing.
object_created datetime Date and time of Batch creation
object_updated datetime Date and time of last update to the Batch
object_id string Unique identifier of the given Batch object
object_owner string Username of the user who created the Address object.
default_carrier_account string ID of the Carrier Account object to use as the default for all shipments in this Batch. The carrier account can be changed on a per-shipment basis by changing the carrier_account in the corresponding BatchShipment object.
default_servicelevel_token string Token of the service level to use as the default for all shipments in this Batch. The servicelevel can be changed on a per-shipment basis by changing the servicelevel_token in the corresponding BatchShipment object. Servicelevel tokens can be found here.
label_file_type string
"PDF"
"PDF_4X6"
"ZPLII"
"PNG"
Print format of the label. If empty, will use the default format set from the Shippo dashboard.
metadata string A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
batch_shipments array Array of BatchShipment objects. The response keeps the same order as in the request array.
label_url array An array of URLs each pointing to a merged file of 100 labels each
object_results An object containing the following counts:
creation_succeeded
creation_failed
purchase_succeeded
purchase_failed
API Resource URL

https://api.goshippo.com/batches/

Example
{
  "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  "object_owner": "shippo@goshippo.com",
  "object_status": "VALID",
  "object_created": "2016-01-04T00:15:44.394Z",
  "object_updated": "2016-01-04T00:48:13.841Z",
  "metadata": "BATCH #170",
  "default_carrier_account": "078870331023437cb917f5187429b093",
  "default_servicelevel_token": "usps_priority",
  "filetype": "PDF_4x6",
  "batch_shipments": {
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
      {
        "metadata": "",
        "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
        "servicelevel_token": "fedex_2_day",
        "shipment": "99c326a150f54e638b08623833ef152f",
        "transaction": null,
        "object_id": "aa7dea463a5a48b0b8fb21f90e72d779",
        "object_status": "VALID",
        "messages": []
      },
      {
        "metadata": "",
        "carrier_account": null,
        "servicelevel_token": null,
        "shipment": "77fd9aeaf9b347da9aa95eb250997dc3",
        "transaction": null,
        "object_id": "e11c95a6788d4ddcaa22f03175838740",
        "object_status": "VALID",
        "messages": []
      }
    ]
  },
  "object_results": {
    "purchase_succeeded": 0,
    "purchase_failed": 0,
    "creation_failed": 0,
    "creation_succeeded": 2
  },
  "label_url": []
}

The Batch Shipment Object

The batch shipment object is a wrapper around a Shipment object, which include shipment-specific information for batch processing.
Note: batch shipments can only be created on the Batch endpoint, either when creating a Batch object or by through the /batches/{BATCH_OBJECT_ID}/add_shipments endpoint

Attributes
object_id string Object ID of this batch shipment. Can be used in the remove_shipments endpoint.
object_status "INVALID"
"VALID"
"INCOMPLETE"
"TRANSACTION_
FAILED"
INVALID batch shipments cannot be purchased and will have to be removed, fixed, and added to the batch again.

VALID batch shipments can be purchased.

batch shipments with the status TRANSACTION_FAILED were not able to be purchased and the error will be displayed on the message field

INCOMPLETE batch shipments have an issue with the Address and will need to be removed, fixed, and added to the batch again.
carrier_account string Object ID of the carrier account to be used for this shipment (will override batch default)
servicelevel_token string A token that sets the shipping method for the batch, overriding the batch default. Servicelevel tokens can be found here.
shipment string or object Object ID of a previously created shipment, to be added to the batch

OR required fields of a new Shipment Object, to be created.
transaction string Object ID of the transaction object created for this batch shipment.
message array List of Shipment and Transaction error messages.
metadata string A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
API Resource URL

https://api.goshippo.com/batches/

Example
{
  "metadata": "",
  "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
  "servicelevel_token": "usps_priority",
  "shipment": "77fd9aeaf9b347da9aa95eb250997dc3",
  "transaction": null,
  "object_id": "adf7a342264b4df1ac5f3c3955fb7603",
  "object_status": "VALID",
  "messages": []
}

Create a batch

Creates a new batch object which allows you to purchase shipping labels for many shipments with one API call. Batches are created asynchronously. This means that the API response won't include your batch shipments yet. You need to retrieve the batch later to verify that all batch shipments are valid.

Attributes
default_carrier_account
required
string ID of the Carrier Account object to use as the default for all shipments in this Batch. The carrier account can be changed on a per-shipment basis by changing the carrier_account in the corresponding BatchShipment object.
default_servicelevel_token
required
string Token of the service level to use as the default for all shipments in this Batch. The servicelevel can be changed on a per-shipment basis by changing the servicelevel_token in the corresponding BatchShipment object.
label_filetype
optional
"PNG"
"PDF"
"PDF_4X6"
"ZPLII"
Print format of the label. If empty, will use the default format set from the Shippo dashboard.
metadata
optional
string A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
batch_shipments
required
array Array of BatchShipment objects. The response keeps the same order as in the request array.
API Resource URL

https://api.goshippo.com/batches/

Example
curl https://api.goshippo.com/batches/  \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -H "Content-Type: application/json"  \
    -d '{
          "default_carrier_account": "078870331023437cb917f5187429b093",
          "default_servicelevel_token": "usps_priority",
          "label_filetype": "PDF_4x6",
          "metadata": "BATCH #170",
          "batch_shipments": [
            {
              "shipment": {    
                "object_purpose": "PURCHASE",
                "address_from": {
                  "object_purpose": "PURCHASE",
                  "name": "Mr Hippo",
                  "street1": "965 Mission St",
                  "street2": "Ste 201",
                  "city": "San Francisco",
                  "state": "CA",
                  "zip": "94103",
                  "country": "US",
                  "phone": "4151234567",
                  "email": "mrhippo@goshippo.com"
                },
                "address_to": {
                  "object_purpose": "PURCHASE",
                  "name": "Mrs Hippo",
                  "company": "",
                  "street1": "Broadway 1",
                  "street2": "",
                  "city": "New York",
                  "state": "NY",
                  "zip": "10007",
                  "country": "US",
                  "phone": "4151234567",
                  "email": "mrshippo@goshippo.com"
                },
                "parcel": {
                  "length": "5",
                  "width": "5",
                  "height": "5",
                  "distance_unit": "in",
                  "weight": "2",
                  "mass_unit": "oz"
                }
              }
            },
            {
              "shipment": {    
                "object_purpose": "PURCHASE",
                "address_from": {
                  "object_purpose": "PURCHASE",
                  "name": "Mr Hippo",
                  "street1": "1092 Indian Summer Ct",
                  "city": "San Jose",
                  "state": "CA",
                  "zip": "95122",
                  "country": "US",
                  "phone": "4151234567",
                  "email": "mrhippo@goshippo.com"
                },
                "address_to": {
                  "object_purpose": "PURCHASE",
                  "name": "Mrs Hippo",
                  "company": "",
                  "street1": "Broadway 1",
                  "street2": "",
                  "city": "New York",
                  "state": "NY",
                  "zip": "10007",
                  "country": "US",
                  "phone": "4151234567",
                  "email": "mrshippo@goshippo.com"
                },
                "parcel": {
                  "length": "5",
                  "width": "5",
                  "height": "5",
                  "distance_unit": "in",
                  "weight": "20",
                  "mass_unit": "lb"
                }
              },
              "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
              "servicelevel_token": "fedex_2_day"
            }
          ]
        }'
Response Example
{
  "object_id": "a015eb693cca465dbb6523ce6d2e3c65",
  "object_owner": "admin",
  "object_status": "VALIDATING",
  "object_created": "2016-09-12T15:25:43.465Z",
  "object_updated": "2016-09-12T15:25:43.465Z",
  "metadata": "BATCH #170",
  "default_carrier_account": "078870331023437cb917f5187429b093",
  "default_servicelevel_token": "usps_priority",
  "label_filetype": "PDF_4x6",
  "batch_shipments": {
      "count": 0,
      "next": null,
      "previous": null,
      "results": []
  },
  "object_results": {
      "purchase_succeeded": 0,
      "purchase_failed": 0,
      "creation_failed": 0,
      "creation_succeeded": 0
  },
  "label_url": []
}

Retrieve a batch

Batch shipments are displayed 100 at a time. You can iterate through each "page" using the ?page= query parameter. You can also filter based on batch shipment status; for instance by passing a query param like ?object_results=creation_failed.

Attributes
object_results
optional GET parameter
"creation_failed"
"creation_succeeded"
"purchase_succeeded"
"purchase_failed"
Filter based on the status of the batch shipment.
API Resource URL

https://api.goshippo.com/batches/<BATCH OBJECT ID>

Example
curl https://api.goshippo.com/batches/<BATCH OBJECT ID>?page=2&object_results=creation_failed \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
  "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  "object_owner": "shippo@goshippo.com",
  "object_status": "INVALID",
  "object_created": "2016-01-04T00:15:44.394Z",
  "object_updated": "2016-01-04T00:48:13.841Z",
  "metadata": "",
  "default_carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
  "default_servicelevel_token": "usps_priority",
  "label_filetype": "PDF_4x6",
  "batch_shipments": {
    "count": 1,
    "next": "https://api.goshippo.com/batches/5ef63c54f5bf45d3b1f8fb37dcb1c5f4?object_results=creation_failed&page=3",
    "previous": "https://api.goshippo.com/batches/5ef63c54f5bf45d3b1f8fb37dcb1c5f4?object_results=creation_failed&page=1",
    "results": [
      {
        "metadata": "",
        "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
        "servicelevel_token": "fedex_ground",
        "shipment": null,
        "transaction": null,
        "object_id": "e11c95a6788d4ddcaa22f03175838740",
        "object_status": "INVALID",
        "messages": [
          [
            {
              "address_to": [
                "This field is required."
              ]
            }
          ]
        ]
      }
    ]
  },
  "object_results": {
    "purchase_succeeded": 0,
    "purchase_failed": 0,
    "creation_failed": 3,
    "creation_succeeded": 5
  },
  "label_url": []
}

Add batch shipments to a batch

Add batch shipments to an existing batch.

Attributes
Array
required
An array consisting of batch shipment objects
API Resource URL

https://api.goshippo.com/batches/<BATCH OBJECT ID>/add_shipments

Example
curl -X POST https://api.goshippo.com/batches/<BATCH OBJECT ID>/add_shipments \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -H "Content-Type: application/json"  \
    -d '[
          "aa7dea463a5a48b0b8fb21f90e72d779",
          "f11b46440c144ce3b97fb5ddf02b8c71",
          "5400f9078f764b1bbb121bcd08de127f",
          "2ab2b452392545908d2cef8861a39c35"
        ]'
Response Example
{
  "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  "object_owner": "shippo@goshippo.com",
  "object_status": "VALID",
  "object_created": "2016-01-04T00:15:44.394Z",
  "object_updated": "2016-01-04T00:48:13.841Z",
  "metadata": "",
  "default_carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
  "default_servicelevel_token": "usps_priority",
  "label_filetype": "PDF_4x6",
  "batch_shipments": {
    "count": 4,
    "next": null,
    "previous": null,
    "results": [
      {
        "metadata": "add batchshipment1",
        "carrier_account": "e11c95a6788d4ddcaa22f03175838740",
        "servicelevel_token": "fedex_2_day",
        "shipment": "99c326a150f54e638b08623833ef152f",
        "transaction": null,
        "object_id": "aa7dea463a5a48b0b8fb21f90e72d779",
        "object_status": "VALID",
        "messages": []
      },
      {
        "metadata": "add batchshipment2",
        "carrier_account": "d2ce085dd3734a22b20c6df36a63aa07",
        "servicelevel_token": "ups_ground",
        "shipment": "2ba26e9733954b3fb8fef38fbb742676",
        "transaction": null,
        "object_id": "f11b46440c144ce3b97fb5ddf02b8c71",
        "object_status": "VALID",
        "messages": []
      },
      {
        "metadata": "add batchshipment3",
        "carrier_account":"a4391cd4ab974f478f55dc08b5c8e3b3",
        "servicelevel_token": "usps_priority_express",
        "shipment": "77fd9aeaf9b347da9aa95eb250997dc3",
        "transaction": null,
        "object_id": "5400f9078f764b1bbb121bcd08de127f",
        "object_status": "VALID",
        "messages": []
      },
      {
        "metadata": "add batchshipment4",
        "carrier_account": null,
        "servicelevel_token": null,
        "shipment": "77fd9aeaf9b347da9aa95eb250997dc3",
        "transaction": null,
        "object_id": "2ab2b452392545908d2cef8861a39c35",
        "object_status": "VALID",
        "messages": []
      }
    ]
  },
  "object_results": {
    "purchase_succeeded": 0,
    "purchase_failed": 0,
    "creation_failed": 0,
    "creation_succeeded": 4
  },
  "label_url": []
}

Remove batch shipments from a batch

Remove batch shipments from an existing batch.

Attributes
Array
required
An array consisting of batch shipment object IDs
API Resource URL

https://api.goshippo.com/batches/<BATCH OBJECT ID>/remove_shipments

Example
curl -X POST https://api.goshippo.com/batches/<BATCH OBJECT ID>/remove_shipments \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -H "Content-Type: application/json"  \
    -d '[
          "aa7dea463a5a48b0b8fb21f90e72d779",
          "f11b46440c144ce3b97fb5ddf02b8c71",
          "5400f9078f764b1bbb121bcd08de127f",
          "2ab2b452392545908d2cef8861a39c35"
        ]'
Response Example
{
  "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  "object_owner": "shippo@goshippo.com",
  "object_status": "VALID",
  "object_created": "2016-01-04T00:15:44.394Z",
  "object_updated": "2016-01-04T00:48:13.841Z",
  "metadata": "",
  "default_carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
  "default_servicelevel_token": "usps_priority",
  "label_filetype": "PDF_4x6",
  "batch_shipments": {
    "count": 0,
    "next": null,
    "previous": null,
    "results": []
  },
  "object_results": {
    "purchase_succeeded": 0,
    "purchase_failed": 0,
    "creation_failed": 0,
    "creation_succeeded": 0
  },
  "label_url": []
}

Purchase a batch

Purchase an existing batch with an object_status of VALID. Once you send a POST request to the purchase endpoint the batch object_status will change to PURCHASING. When all the shipments are purchased, the object_status will change to PURCHASED and you will receive a batch_purchased webhook indicating that the batch has been purchased.

API Resource URL

https://api.goshippo.com/batches/<BATCH OBJECT ID>/purchase

Example
curl -X POST https://api.goshippo.com/batches/<BATCH OBJECT ID>/purchase \
    -H "Authorization: ShippoToken <API_TOKEN>"
Response Example
{
  "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  "object_owner": "shippo@goshippo.com",
  "object_status": "PURCHASING",
  "object_created": "2016-01-04T00:15:44.394Z",
  "object_updated": "2016-01-04T00:48:13.841Z",
  "metadata": "",
  "default_carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
  "default_servicelevel_token": "usps_priority",
  "label_filetype": "PDF_4x6",
  "batch_shipments": {
    "count": 4,
    "next": null,
    "previous": null,
    "results": [
      {
        "metadata": "",
        "carrier_account": null,
        "servicelevel_token": null,
        "shipment": "99c326a150f54e638b08623833ef152f",
        "transaction": null,
        "object_id": "aa7dea463a5a48b0b8fb21f90e72d779",
        "object_status": "VALID",
        "messages": []
      },
      {
        "metadata": "",
        "carrier_account": null,
        "servicelevel_token": null,
        "shipment": "2ba26e9733954b3fb8fef38fbb742676",
        "transaction": null,
        "object_id": "f11b46440c144ce3b97fb5ddf02b8c71",
        "object_status": "VALID",
        "messages": []
      },
      {
        "metadata": "",
        "carrier_account": null,
        "servicelevel_token": null,
        "shipment": "77fd9aeaf9b347da9aa95eb250997dc3",
        "transaction": null,
        "object_id": "5400f9078f764b1bbb121bcd08de127f",
        "object_status": "VALID",
        "messages": []
      },
      {
        "metadata": "",
        "carrier_account": null,
        "servicelevel_token": null,
        "shipment": "77fd9aeaf9b347da9aa95eb250997dc3",
        "transaction": null,
        "object_id": "2ab2b452392545908d2cef8861a39c35",
        "object_status": "VALID",
        "messages": []
      }
    ]
  },
  "object_results": {
    "purchase_succeeded": 1,
    "purchase_failed": 0,
    "creation_failed": 0,
    "creation_succeeded": 4
  },
  "label_url": []
}

Carriers

The following carrier tokens can be used to reference carriers, e.g. when tracking shipments.

Token Carrier name
australia_postAustralia Post
canada_postCanada Post
deutsche_postDeutsche Post
dhl_germanyDHL Germany
dhl_ecommerceDHL eCommerce
dhl_expressDHL Express
fedexFedEx
gls_deGLS Germany
gls_frGLS France
lasershipLasership
mondial_relayMondial Relay
newgisticsNewgistics
ontracOnTrac
purolatorPurolator
upsUPS
uspsUSPS

Service Levels

The following service level tokens can be used to reference specific rates when purchasing shipping labels using single call label creation (instalabel) and batch label creation endpoints.

USPS

Token Service name
usps_priorityPriority Mail
usps_priority_expressPriority Mail Express
usps_firstFirst Class Mail/Package
usps_parcel_selectParcel Select
usps_media_mailMedia Mail, only for existing Shippo customers with grandfathered Media Mail option.
usps_priority_mail_internationalPriority Mail International
usps_priority_mail_express_internationalPriority Mail Express International
usps_first_class_package_international_serviceFirst Class Package International

FedEx

Token Service name
fedex_groundGround
fedex_home_deliveryHome Delivery
fedex_smart_postSmartpost
fedex_2_day2 Day
fedex_2_day_am2 Day A.M.
fedex_express_saverExpress Saver
fedex_standard_overnightStandard Overnight
fedex_priority_overnightPriority Overnight
fedex_first_overnightFirst Overnight
fedex_international_economyInternational Economy
fedex_international_priorityInternational Priority
fedex_international_firstInternational First
fedex_europe_first_international_priorityEurope First International Priority

UPS

Token Service name
ups_standardStandard℠
ups_groundGround
ups_saverSaver®
ups_3_day_selectThree-Day Select®
ups_second_day_airSecond Day Air®
ups_second_day_air_amSecond Day Air A.M.®
ups_next_day_airNext Day Air®
ups_next_day_air_saverNext Day Air Saver®
ups_next_day_air_early_amNext Day Air Early A.M.®
ups_mail_innovations_domesticMail Innovations (domestic)
ups_surepostSurepost
ups_surepost_lightweightSurepost Lightweight
ups_expressExpress®
ups_express_plusExpress Plus®
ups_expeditedExpedited®

Australia Post

Token Service name
australia_post_express_postExpress Post
australia_post_parcel_postParcel Post

Canada Post

Token Service name
canada_post_regular_parcelRegular Parcel
canada_post_expedited_parcelExpedited Parcel
canada_post_priorityPriority
canada_post_xpresspostXpresspost
canada_post_xpresspost_internationalXpresspost International
canada_post_xpresspost_usaXpresspost USA
canada_post_expedited_parcel_usaExpedited Parcel USA
canada_post_tracked_packet_usaTracked Packet USA
canada_post_small_packet_usa_airSmall Packet USA Air
canada_post_tracked_packet_internationalTracked Packet International
canada_post_small_packet_international_airSmall Package International Air

Purolator

Token Service name
purolator_groundGround
purolator_ground9_amGround 9am
purolator_ground1030_amGround 10:30am
purolator_ground_distributionGround Distribution
purolator_ground_eveningGround Evening
purolator_ground_usGround US
purolator_expressExpress
purolator_express9_amExpress 9am
purolator_express1030_amExpress 10am
purolator_express_eveningExpress Evening
purolator_express_usExpress US
purolator_express_us9_amExpress US 9am
purolator_express_us1030_amExpress US 10:30am
purolator_express_us1200Express US 12pm
purolator_express_internationalExpress International
purolator_express_international9_amExpress International 9am
purolator_express_international1030_amExpress International 10:30am
purolator_express_international1200Express International 12pm

DHL Express

Token Service name
dhl_express_domestic_express_docDomestic Express Doc
dhl_express_economy_select_docEconomy Select Doc
dhl_express_worldwide_nondocExpress Worldwide Nondoc
dhl_express_worldwide_docExpress Worldwide Doc
dhl_express_worldwideWorldwide
dhl_express_worldwide_eu_docExpress Worldwide EU Doc
dhl_express_break_bulk_express_docBreak Bulk Express Doc
dhl_express_express_9_00_nondocExpress 9:00 NonDoc
dhl_express_economy_select_nondocEconomy Select NonDoc
dhl_express_break_bulk_economy_docBreak Bulk Economy Doc
dhl_express_express_9_00_docExpress 9:00 Doc
dhl_express_express_10_30_docExpress 10:30 Doc
dhl_express_express_10_30_nondocExpress 10:30 NonDoc
dhl_express_express_12_00_docExpress 12:00 Doc
dhl_express_europack_nondocEuropack NonDoc
dhl_express_express_envelope_docExpress Envelope Doc
dhl_express_express_12_00_nondocExpress 12:00 NonDoc
dhl_express_worldwide_b2c_docExpress Worldwide (B2C) Doc
dhl_express_worldwide_b2c_nondocExpress Worldwide (B2C) NonDoc
dhl_express_medical_expressMedical Express
dhl_express_express_easy_nondocExpress Easy NonDoc

DHL eCommerce

Token Service name
dhl_ecommerce_first_class_expeditedFirst Class Expedited
dhl_ecommerce_priority_expeditedPriority Expedited
dhl_ecommerce_bpm_groundBPM Ground
dhl_ecommerce_bpm_expeditedBPM Expedited
dhl_ecommerce_marketing_parcel_groundMarketing Parcel Ground
dhl_ecommerce_marketing_parcel_expeditedMarketing Parcel Expedited
dhl_ecommerce_parcel_plus_groundParcel Plus Ground
dhl_ecommerce_parcel_plus_expeditedParcel Plus Expedited
dhl_ecommerce_parcel_plus_expedited_maxParcel Plus Expedited Max
dhl_ecommerce_parcels_groundParcels Ground Expedited
dhl_ecommerce_parcels_expeditedParcels Expedited
dhl_ecommerce_parcels_expedited_maxParcels Expedited Max
dhl_ecommerce_groundGround
dhl_ecommerce_expeditedExpedited (for Flats)
dhl_ecommerce_lightLight (for EZ Return)
dhl_ecommerce_plusPlus (for EZ Return)

DHL Germany

Token Service name
dhl_paket_businessPaket (business customers)
dhl_weltpaket_businessWeltpaket (business customers)
dhl_europaket_businessEuropaket (business customers)

Deutsche Post

Token Service name
deutsche_post_postkartePostkarte
deutsche_post_standardbriefStandardbrief
deutsche_post_kompaktbriefKompaktbrief
deutsche_post_grossbriefGrossbrief
deutsche_post_maxibriefMaxibrief
deutsche_post_maxibrief_plusMaxibrief Plus

GLS Germany

Token Service name
gls_deutschland_business_parcelBusiness Parcel

GLS France

Token Service name
gls_france_business_parcelBusiness Parcel

Mondial Relay

Token Service name
mondial_relay_pointrelaisPoint Relais

Parcelforce

Token Service name
parcelforce_express48Express 48
parcelforce_express24Express 24
parcelforce_expressamExpress AM

Newgistics

Token Service name
newgistics_parcel_select_lightweightParcel Select Lightweight
newgistics_parcel_selectParcel Select
newgistics_priority_mailPriority Mail
newgistics_first_class_mailFirst Class Mail

OnTrac

Token Service name
ontrac_groundGround
ontrac_sunrise_goldSunrise Gold
ontrac_sunriseSunrise

Lasership

Token Service name
lasership_routed_deliveryRouted Delivery

UberRUSH

Token Service name
uber_on_demandOn Demand

Parcel Templates

Use any of the following templates when you ship with special carrier packaging.

FedEx

Token Name Dimensions
FedEx_Box_10kg Box 10kg 15.81 x 12.94 x 10.19 in
FedEx_Box_25kg Box 25kg 54.80 x 42.10 x 33.50 in
FedEx_Box_Extra_Large_1 Box Extra Large (1) 11.88 x 11.00 x 10.75 in
FedEx_Box_Extra_Large_2 Box Extra Large (2) 15.75 x 14.13 x 6.00 in
FedEx_Box_Large_1 Box Large (1) 17.50 x 12.38 x 3.00 in
FedEx_Box_Large_2 Box Large (2) 11.25 x 8.75 x 7.75 in
FedEx_Box_Medium_1 Box Medium (1) 13.25 x 11.50 x 2.38 in
FedEx_Box_Medium_2 Box Medium (2) 11.25 x 8.75 x 4.38 in
FedEx_Box_Small_1 Box Small (1) 12.38 x 10.88 x 1.50 in
FedEx_Box_Small_2 Box Small (2) 11.25 x 8.75 x 4.38 in
FedEx_Envelope Envelope 12.50 x 9.50 x 0.80 in
FedEx_Padded_Pak Padded Pak 11.75 x 14.75 x 2.00 in
FedEx_Pak_1 Pak (1) 15.50 x 12.00 x 0.80 in
FedEx_Pak_2 Pak (2) 12.75 x 10.25 x 0.80 in
FedEx_Tube Tube 38.00 x 6.00 x 6.00 in
FedEx_XL_Pak XL Pak 17.50 x 20.75 x 2.00 in

UPS

Token Name Dimensions
UPS_Box_10kg Box 10kg 410.00 x 335.00 x 265.00 mm
UPS_Box_25kg Box 25kg 484.00 x 433.00 x 350.00 mm
UPS_Express_Box Express Box 460.00 x 315.00 x 95.00 mm
UPS_Express_Box_Large Express Box Large 18.00 x 13.00 x 3.00 in
UPS_Express_Box_Medium Express Box Medium 15.00 x 11.00 x 3.00 in
UPS_Express_Box_Small Express Box Small 13.00 x 11.00 x 2.00 in
UPS_Express_Envelope Express Envelope 12.50 x 9.50 x 2.00 in
UPS_Express_Hard_Pak Express Hard Pak 14.75 x 11.50 x 2.00 in
UPS_Express_Legal_Envelope Express Legal Envelope 15.00 x 9.50 x 2.00 in
UPS_Express_Pak Express Pak 16.00 x 12.75 x 2.00 in
UPS_Express_Tube Express Tube 970.00 x 190.00 x 165.00 mm
UPS_Laboratory_Pak Laboratory Pak 17.25 x 12.75 x 2.00 in
UPS_MI_BPM BPM (Mail Innovations - Domestic & International) 0.00 x 0.00 x 0.00 in
UPS_MI_BPM_Flat BPM Flat (Mail Innovations - Domestic & International) 0.00 x 0.00 x 0.00 in
UPS_MI_BPM_Parcel BPM Parcel (Mail Innovations - Domestic & International) 0.00 x 0.00 x 0.00 in
UPS_MI_First_Class First Class (Mail Innovations - Domestic only) 0.00 x 0.00 x 0.00 in
UPS_MI_Flat Flat (Mail Innovations - Domestic only) 0.00 x 0.00 x 0.00 in
UPS_MI_Irregular Irregular (Mail Innovations - Domestic only) 0.00 x 0.00 x 0.00 in
UPS_MI_Machinable Machinable (Mail Innovations - Domestic only) 0.00 x 0.00 x 0.00 in
UPS_MI_MEDIA_MAIL Media Mail (Mail Innovations - Domestic only) 0.00 x 0.00 x 0.00 in
UPS_MI_Parcel Parcel (Mail Innovations - Domestic only) 0.00 x 0.00 x 0.00 in
UPS_MI_Parcel_Post Parcel Post (Mail Innovations - Domestic only) 0.00 x 0.00 x 0.00 in
UPS_MI_Priority Priority (Mail Innovations - Domestic only) 0.00 x 0.00 x 0.00 in
UPS_MI_Standard_Flat Standard Flat (Mail Innovations - Domestic only) 0.00 x 0.00 x 0.00 in
UPS_Pad_Pak Pad Pak 14.75 x 11.00 x 2.00 in
UPS_Pallet Pallet 120.00 x 80.00 x 200.00 cm

USPS

Token Name Dimensions
USPS_FlatRateCardboardEnvelope Flat Rate Cardboard Envelope 12.50 x 9.50 x 0.75 in
USPS_FlatRateEnvelope Flat Rate Envelope 12.50 x 9.50 x 0.75 in
USPS_FlatRateGiftCardEnvelope Flat Rate Gift Card Envelope 10.00 x 7.00 x 0.75 in
USPS_FlatRateLegalEnvelope Flat Rate Legal Envelope 15.00 x 9.50 x 0.75 in
USPS_FlatRatePaddedEnvelope Flat Rate Padded Envelope 12.50 x 9.50 x 1.00 in
USPS_FlatRateWindowEnvelope Flat Rate Window Envelope 10.00 x 5.00 x 0.75 in
USPS_IrregularParcel Irregular Parcel 0.00 x 0.00 x 0.00 in
USPS_LargeFlatRateBoardGameBox Large Flat Rate Board Game Box 24.06 x 11.88 x 3.13 in
USPS_LargeFlatRateBox Large Flat Rate Box 12.25 x 12.25 x 6.00 in
USPS_LargeVideoFlatRateBox Flat Rate Large Video Box (Int'l only) 9.60 x 6.40 x 2.20 in
USPS_MediumFlatRateBox1 Medium Flat Rate Box 1 11.25 x 8.75 x 6.00 in
USPS_MediumFlatRateBox2 Medium Flat Rate Box 2 14.00 x 12.00 x 3.50 in
USPS_RegionalRateBoxA1 Regional Rate Box A1 10.13 x 7.13 x 5.00 in
USPS_RegionalRateBoxA2 Regional Rate Box A2 13.06 x 11.06 x 2.50 in
USPS_RegionalRateBoxB1 Regional Rate Box B1 12.25 x 10.50 x 5.50 in
USPS_RegionalRateBoxB2 Regional Rate Box B2 16.25 x 14.50 x 3.00 in
USPS_SmallFlatRateBox Small Flat Rate Box 8.69 x 5.44 x 1.75 in
USPS_SmallFlatRateEnvelope Small Flat Rate Envelope 10.00 x 6.00 x 4.00 in

DHL eCommerce

Token Name Dimensions
DHLeC_Easy_Return Easy Return 10.00 x 10.00 x 10.00 in
DHLeC_Irregular Irregular Shipment 10.00 x 10.00 x 10.00 in
DHLeC_SM_Flats Flats 27.00 x 17.00 x 17.00 in