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 token (live or test). In order to authenticate properly, please put Authorization: ShippoToken <API_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. All requests to the Shippo API must use TLS version 1.2 or higher.

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 have 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/Province values are required for shipments from/to the US, AU, and CA. UPS requires province for some countries (i.e Ireland). To receive more accurate quotes, passing this field is recommended. Most carriers only accept two or three character state abbreviations.
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/

Response 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	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 do not have to be sent. 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/

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
}

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
      },
      {...},
      {...}
   ]
}

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

Response 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", "INDIRECT", "CARRIER_CONFIRMATION"	Request standard or adult signature confirmation. You can alternatively request Certified Mail (USPS only) or Indirect signature (FedEx only) or Carrier Confirmation (Deutsche Post only)
authority_to_leave	boolean	Request “true” to give carrier permission to leave the parcel in a safe place if no one answers the door (where supported). When set to “false”, if no one is available to receive the item, the parcel will not be left (*surcharges may be applicable).
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 insurance.
bypass_address_validation	boolean	Bypasses address validation (USPS, UPS, & LaserShip only).
request_retail_rates	boolean	Returns retail rates instead of account-based rates (UPS and FedEx only).
customer_branch	string	Specify customer branch (Lasership only).
premium	boolean	Add premium service to a shipment (DHL Germany international shipments only).
preferred_delivery_timeframe	'10001200','12001400','14001600','16001800','18002000','19002100'	Required for DHL Germany Paket Sameday. Designates a desired timeframe for delivery. Format is HHMMHHMM
lasership_attrs	"TwoPersonDelivery", "Explosive", "Alcohol", "Hazmat", "ControlledSubstance", "Refrigerated", "DryIce", "Perishable", "NoRTS"	Specify Lasership Attributes (Lasership only). Multiple options accepted.
lasership_declared_value	string	Declared value (Lasership only). Defaults to "50.00".
container_type	string	Specify container type.
billing	object	Specify billing details (UPS, FedEx, and DHL Germany only).
type	"SENDER", "RECIPIENT", "THIRD_PARTY", "COLLECT"	Party to be billed. Leave blank for DHL Germany. COLLECT is only valid for Fedex.
account	string	Account number to be billed. (For DHL Germany, leave this field blank.)
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).
participation_code	string	2 digit code used to override your default participation code associated with your DHL Germany account.
COD	object	Specify collection on delivery (DHL Germany, FedEx, GLS, OnTrac, and UPS only).
amount	string	Insured Amount.
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".)
alcohol	object	Indicates that a shipment contains Alcohol (Fedex and UPS only).
contains_alcohol	boolean	Mandatory for Fedex and UPS. Specifies that the package contains Alcohol.
recipient_type	"licensee", "consumer"	Mandatory for Fedex only. License type of the recipient of the Alcohol Package.
dry_ice	object	Specify that the package contains Dry Ice (FedEx and UPS only).
contains_dry_ice	boolean	Mandatory. Specifies that the package contains Dry Ice.
weight	decimal	Mandatory. Units must be in Kilograms. Cannot be greater than package weight.
dangerous_goods_code	"01", "02", "03", "04", "05", "06", "07", "08", "09"	Dangerous Goods Code (DHL eCommerce only). See Category Codes
carbon_neutral boolean	Request carbon offsets by passing true (UPS only).

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.

In order to filter results, you must use the below path parameters. A maximum date range of 90 days is permitted. Provided dates should be ISO 8601 UTC dates (timezone offsets are currently not supported).

Optional path parameters:

object_created_gt - object(s) created greater than a provided date time
object_created_gte - object(s) created greater than or equal to a provided date time
object_created_lt - object(s) created less than a provided date time
object_created_lte - object(s) created less than or equal to a provided date time

Date format examples:

"2017-01-01"
"2017-01-01T03:30:30" or "2017-01-01T03:30:30.5"
"2017-01-01T03:30:30Z"

Example URL:
https://api.goshippo.com/shipments/?object_created_gte=2017-01-01T00:00:30&object_created_lt=2017-04-01T00:00:30

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	An array containing specific attributes of this Rate in context of the entire shipment. Attributes can be assigned 'CHEAPEST', 'FASTEST', or 'BESTVALUE'.
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_ground". 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>/]

Response 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" "PNG_2.3x7.5" "PDF" "PDF_2.3x7.5" "PDF_4x6" "PDF_4x8" "PDF_A4" "PDF_A6" "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.
eta	datetime	The estimated time of arrival according to the carrier.
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/

Response 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",
    "eta": "2013-12-30T12:00:00.000Z",
    "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":"",
   "eta":"",
   "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":"",
   "eta":"",
   "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",
   "eta":"2014-07-21T12:00:00.000Z",
   "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.

In order to filter results, you must use the below path parameters. A maximum date range of 90 days is permitted. Provided dates should be ISO 8601 UTC dates (timezone offsets are currently not supported).

Optional path parameters:

object_created_gt - object(s) created greater than a provided date time
object_created_gte - object(s) created greater than or equal to a provided date time
object_created_lt - object(s) created less than a provided date time
object_created_lte - object(s) created less than or equal to a provided date time

Date format examples:

"2017-01-01"
"2017-01-01T03:30:30" or "2017-01-01T03:30:30.5"
"2017-01-01T03:30:30Z"

Example URL:
https://api.goshippo.com/transactions/?object_created_gte=2017-01-01T00:00:30&object_created_lt=2017-04-01T00:00:30

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",
         "eta":"2014-07-21T12:00:00.000Z",
         "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.
sku_code	string	SKU code of the item, which is required by some carriers.
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/

Response 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
sku_code 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	Exporter 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', 'FCA'	The incoterm reference of the shipment. FCA available for DHL Express and FedEx only.
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/

Response 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'
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/

Response 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.
errors	array	An array of codes and messages describing the error that occurred if any.
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/

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",
    "errors": [],
    "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 required	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"
         ]
      },
      {...}
   ]
}

Manifest Errors

The following codes and messages are the possible errors that may occur when creating Manifests.

generic_carrier_error	There is an error from the carrier that requires investigation. Please contact support with the object ID of this response.
carrier_account_invalid_credentials	The carrier account contains invalid credentials. Please update your carrier account with valid credentials.
carrier_account_access_denied	There is an issue with your carrier account. Please contact support with the information of your account manager at the carrier and the object ID of this response.
manifest_invalid_transactions	For this carrier, all shipments must be manifested on the same day that they are created regardless of shipment date.
manifest_no_transactions	There are no shipments in the manifest. Please check that the shipment date of the shipments matches the shipment date of the manifest.
address_from_missing_zip	The sender address is missing the zip. Please update the sender address and try again.
address_from_invalid_zip1	The sender address contains an invalid zip. Please update the sender address and try again.
address_from_invalid_zip2	The sender address contains an invalid zip. Please update the sender address and try again. You can also try removing the last 4 digits of the zip.
address_from_missing_city	The sender address is missing the city. Please update the sender address and try again.
address_from_invalid_city	The sender address contains an invalid city. Please update the sender address and try again.
address_from_missing_state	The sender address is missing the state. Please update the sender address and try again.
address_from_invalid_state	The sender address contains an invalid state. Please update the sender address and try again.
address_from_missing_name	The sender address is missing the name. Please update the sender address and try again.
shipment_date_missing	The shipment date is missing. Please update the shipment date and try again.
shipment_date_invalid	The shipment date is invalid. Please update the shipment date and try again.

API Resource URL

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

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": "ERROR",
    "errors": [
        {
            "code": "shipment_date_invalid",
            "message": "The shipment date is invalid. Please update the shipment date and try again."
        }
    ],
    "carrier_account": "b741b99f95e841639b54272834bc478c",
    "submission_date": "2014-05-16T23:59:59Z",
    "address_from": "28828839a2b04e208ac2aa4945fbca9a",
    "transactions": [],
    "documents": []
}

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/

Response 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	boolean	Determines whether the account 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.

When using your Test token for tracking, you'll want to use Shippo's predefined tokens for testing different tracking statuses. You can find more information in our Tracking tutorial on how to do this, and what the payloads look like.

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.
transaction	string	The `object_id` of the transaction associated with this tracking object. This field is visible only to the object owner of the transaction.
eta	datetime	The estimated time of arrival according to the carrier, this might be updated by carriers during the life of the shipment.
original_eta	datetime	The estimated time of arrival according to the carrier at the time the shipment first entered the system.
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/

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"
  },
  "transaction": "1275c67d754f45bf9d6e4d7a3e205314",
  "eta": "2016-07-23T00:00:00Z",
  "original_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"
  },
  "transaction": "1275c67d754f45bf9d6e4d7a3e205314",
  "eta": "2016-07-23T00:00:00Z",
  "original_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"
  },
  "transaction": "1275c67d754f45bf9d6e4d7a3e205314",
  "eta": "2016-07-23T00:00:00Z",
  "original_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_filetype	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/

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": "BATCH #170",
  "default_carrier_account": "078870331023437cb917f5187429b093",
  "default_servicelevel_token": "usps_priority",
  "label_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 '[
            {
              "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",
                },
                "address_to": {
                  "object_purpose": "PURCHASE",
                  "name": "Hippo Jr",
                  "street1": "915 Broadway",
                  "street2": "19th Floor",
                  "city": "New York",
                  "state": "NY",
                  "zip": "10010",
                  "country": "US",
                  "phone": "2129947880",
                },
                "parcel": {
                  "length": "12",
                  "width": "12",
                  "height": "12",
                  "distance_unit": "in",
                  "weight": "12",
                  "mass_unit": "oz"
                }
              }
            },
            {
              "shipment": {
                "object_purpose": "PURCHASE",
                "address_from": {
                  "object_purpose": "PURCHASE",
                  "name": "Ms Hippo",
                  "street1": "1092 Indian Summer Ct",
                  "city": "San Jose",
                  "state": "CA",
                  "zip": "95122",
                  "country": "US",
                  "phone": "4151234567",
                },
                "address_to": {
                  "object_purpose": "PURCHASE",
                  "name": "Mr Hippo",
                  "street1": "965 Mission St",
                  "street2": "Ste 201",
                  "city": "San Francisco",
                  "state": "CA",
                  "zip": "94103",
                  "country": "US",
                  "phone": "4151234567",
                },
                "parcel": {
                  "length": "5",
                  "width": "5",
                  "height": "5",
                  "distance_unit": "in",
                  "weight": "2",
                  "mass_unit": "lb"
                }
              },
              "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
              "servicelevel_token": "fedex_2_day"
            }
          ]'

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
airterra	Airterra
apc_postal	APC Postal
apg	APG
aramex	Aramex
asendia_us	Asendia US
australia_post	Australia Post (also used for Startrack)
axlehire	Axlehire
borderguru	BorderGuru
boxberry	Boxberry
bring	Bring (also used for Posten Norge)
canada_post	Canada Post
cdl	CDL
chronopost	Chronopost
colissimo	Colissimo
collect_plus	CollectPlus
correios_br	CorreiosBR
correos_espana	Correos Espana
couriersplease	Couriers Please
deutsche_post	Deutsche Post
dhl_benelux	DHL Benelux
dhl_ecommerce	DHL eCommerce
dhl_express	DHL Express
dhl_germany_c2c	DHL Germany C2C
dhl_germany	DHL Germany
dpd_germany	DPD GERMANY
dpd	DPD
dpd_uk	DPD UK
estafeta	Estafeta
fastway_australia	Fastway Australia
fedex	FedEx
globegistics	Globegistics
gls_us	GLS US
gophr	Gophr
gso	GSO
hermes_germany_b2c	Hermes Germany B2C
hermes_uk	Evri UK
hongkong_post	Hongkong Post
lasership	LaserShip
lso	LSO
mondial_relay	Mondial Relay
newgistics	Newgistics
new_zealand_post	New Zealand Post (also used for Pace and CourierPost)
nippon_express	Nippon Express
ontrac	OnTrac
orangeds	OrangeDS
parcelforce	Parcelforce
parcel	Parcel
passport	Passport
pcf	PCF
posti	Posti
purolator	Purolator
royal_mail	Royal Mail
rr_donnelley	RR Donnelley
russian_post	Russian Post
sendle	Sendle
skypostal	SkyPostal
stuart	Stuart
swyft	Swyft
uds	UDS (United Delivery Service)
ups	UPS
usps	USPS
yodel	Yodel

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_priority	Priority Mail
usps_priority_express	Priority Mail Express
usps_first	First Class Mail/Package
usps_parcel_select	Parcel Select
usps_media_mail	Media Mail, only for existing Shippo customers with grandfathered Media Mail option.
usps_priority_mail_international	Priority Mail International
usps_priority_mail_express_international	Priority Mail Express International
usps_first_class_package_international_service	First Class Package International

FedEx

Token	Service name
fedex_ground	FedEx Ground
fedex_home_delivery	FedEx Home Delivery®
fedex_smart_post	FedEx SmartPost®
fedex_2_day	FedEx 2Day®
fedex_2_day_am	FedEx 2Day® A.M.
fedex_express_saver	FedEx Express Saver®
fedex_standard_overnight	FedEx Standard Overnight®
fedex_priority_overnight	FedEx Priority Overnight®
fedex_first_overnight	FedEx First Overnight®
fedex_freight_priority	FedEx Freight® Priority
fedex_next_day_freight	FedEx Next Day Freight
fedex_freight_economy	FedEx Freight® Economy
fedex_first_freight	FedEx First Freight
fedex_international_economy	FedEx International Economy
fedex_international_priority	FedEx International Priority®
fedex_international_first	FedEx International First®
fedex_europe_first_international_priority	FedEx International First®
fedex_international_connect_plus	FedEx International Connect Plus
fedex_international_economy_freight	FedEx International Economy Freight
fedex_international_priority_express	FedEx International Priority® Express
fedex_international_priority_freight	FedEx International Priority Freight
fedex_europe_first_international_priority	Europe First International Priority

UPS

Token	Service name
ups_standard	Standard℠
ups_ground	Ground
ups_saver	Saver®
ups_3_day_select	3 Day Select®
ups_second_day_air	2nd Day Air®
ups_second_day_air_am	2nd Day Air® A.M.
ups_next_day_air	Next Day Air®
ups_next_day_air_saver	Next Day Air Saver®
ups_next_day_air_early_am	Next Day Air® Early
ups_mail_innovations_domestic	Mail Innovations (domestic)
ups_surepost	Surepost
ups_surepost_bound_printed_matter	SurePost® Bound Printed Matter
ups_surepost_lightweight	Surepost Lightweight
ups_surepost_media	SurePost® Media
ups_express	Express®
ups_express_1200	Express 12:00
ups_express_plus	Express Plus®
ups_expedited	Expedited®
ups_express_early	Express® Early
ups_access_point_economy	Access Point™ Economy

Airterra

Token	Service name
airterra_ground	GroundXC
airterra_postal	FastPost

APC Postal

Token	Service name
apc_postal_parcelconnect_expedited	parcelConnect Expedited
apc_postal_parcelconnect_priority	parcelConnect Priority
apc_postal_parcelconnect_priority_delcon	parcelConnect Priority Delcon
apc_postal_parcelconnect_priority_pqw	parcelConnect Priority PQW
apc_postal_parcelconnect_book_service	parcelConnect Book Service
apc_postal_parcelconnect_standard	parcelConnect Standard
apc_postal_parcelconnect_epmi	parcelConnect ePMI
apc_postal_parcelconnect_epacket	parcelConnect ePacket
apc_postal_parcelconnect_epmei	parcelConnect ePMEI

APG

Token	Service name
epacket	ePacket
epacket_plus	ePacket Plus
eparcel_premium	eParcel premium
apg_eparcel_expedited	eParcel Expedited

Asendia

Token	Service name
asendia_us_priority_tracked	Asendia USA Priority Tracked
asendia_us_international_express	Asendia USA International Express
asendia_us_international_priority_airmail	Asendia USA International Priority Airmail
asendia_us_international_surface_airlift	Asendia USA International Surface Air Lift
asendia_us_priority_mail_international	Asendia USA Priority Mail International
asendia_us_priority_mail_express_international	Asendia USA Priority Mail Express International
asendia_us_epacket	Asendia USA International ePacket
asendia_us_other	Asendia USA Other Services (custom)

Australia Post

Token	Service name
australia_post_express_post	Express Post
australia_post_parcel_post	Parcel Post
australia_post_pack_and_track_international	Pack and Track International
australia_post_international_airmail	International Airmail
australia_post_express_post_international	Express Post International
australia_post_express_courier_international	Express Courier International
australia_post_international_express	International Express
australia_post_international_standard	International Standard
australia_post_international_economy	International Economy

AxleHire

Token	Service name
axlehire_next_day	Next Day

BetterTrucks

Token	Service name
better_trucks_same_day	Same Day
better_trucks_next_day	Next Day

Canada Post

Token	Service name
canada_post_regular_parcel	Regular Parcel
canada_post_expedited_parcel	Expedited Parcel
canada_post_priority	Priority
canada_post_xpresspost	Xpresspost
canada_post_xpresspost_international	Xpresspost International
canada_post_xpresspost_usa	Xpresspost USA
canada_post_expedited_parcel_usa	Expedited Parcel USA
canada_post_tracked_packet_usa	Tracked Packet USA
canada_post_small_packet_usa_air	Small Packet USA Air
canada_post_tracked_packet_international	Tracked Packet International
canada_post_small_packet_international_air	Small Package International Air

CDL

Token	Service name
cdl_next_day	Next Day

Chronopost

Token	Service name
chronopost_13	Chrono 13
chronopost_10	Chrono 10
chronopost_18	Chrono 18
chronopost_relais_fr	Chrono Point Relais
chronopost_classic	Chrono Classic International
chronopost_express	Chrono Express International

Colissimo

Token	Service name
colissimo_home	Domicile
colissimo_pick_up_point	Point Retrait
colissimo_return_mainland_france	Retour France

Correos España

Token	Service name
correos_estandard_home	Paquete Estándar
correos_premium_home	Paquete Premium

CouriersPlease

Token	Service name
couriersplease_domestic_priority_auth_to_leave	Domestic Priority - Authority To Leave/POPPoints
couriersplease_domestic_priority_sign_required	Domestic Priority - Signature Required
couriersplease_gold_domestic_auth_to_leave	Gold Domestic - Authority To Leave/POPPoints
couriersplease_gold_domestic_sign_required	Gold Domestic - Signature Required
couriersplease_off_peak_auth_to_leave	Off Peak - Authority To Leave/POPPoints
couriersplease_off_peak_sign_required	Off Peak - Signature Required
couriersplease_parcel_auth_to_leave	Parcel - Authority To Leave
couriersplease_parcel_sign_required	Parcel - Signature Required
couriersplease_road_express	Road Express
couriersplease_satchel_auth_to_leave	Satchel - Authority To Leave
couriersplease_satchel_sign_required	Satchel - Signature Required

Purolator

Token	Service name
purolator_ground	Ground
purolator_ground9_am	Ground 9am
purolator_ground1030_am	Ground 10:30am
purolator_ground_distribution	Ground Distribution
purolator_ground_evening	Ground Evening
purolator_ground_us	Ground US
purolator_express	Express
purolator_express9_am	Express 9am
purolator_express1030_am	Express 10am
purolator_express_evening	Express Evening
purolator_express_us	Express US
purolator_express_us9_am	Express US 9am
purolator_express_us1030_am	Express US 10:30am
purolator_express_us1200	Express US 12pm
purolator_express_international	Express International
purolator_express_international9_am	Express International 9am
purolator_express_international1030_am	Express International 10:30am
purolator_express_international1200	Express International 12pm

DHL Express

Token	Service name
dhl_express_domestic_express_doc	Domestic Express Doc
dhl_express_economy_select_doc	Economy Select Doc
dhl_express_worldwide_nondoc	Express Worldwide Nondoc
dhl_express_worldwide_doc	Express Worldwide Doc
dhl_express_worldwide	Worldwide
dhl_express_worldwide_eu_doc	Express Worldwide EU Doc
dhl_express_break_bulk_express_doc	Break Bulk Express Doc
dhl_express_express_9_00_nondoc	Express 9:00 NonDoc
dhl_express_economy_select_nondoc	Economy Select NonDoc
dhl_express_break_bulk_economy_doc	Break Bulk Economy Doc
dhl_express_express_9_00_doc	Express 9:00 Doc
dhl_express_express_10_30_doc	Express 10:30 Doc
dhl_express_express_10_30_nondoc	Express 10:30 NonDoc
dhl_express_express_12_00_doc	Express 12:00 Doc
dhl_express_europack_nondoc	Europack NonDoc
dhl_express_express_envelope_doc	Express Envelope Doc
dhl_express_express_12_00_nondoc	Express 12:00 NonDoc
dhl_express_express_12_doc	Domestic Express 12:00
dhl_express_worldwide_b2c_doc	Express Worldwide (B2C) Doc
dhl_express_worldwide_b2c_nondoc	Express Worldwide (B2C) NonDoc
dhl_express_medical_express	Medical Express
dhl_express_express_easy_nondoc	Express Easy NonDoc

DHL eCommerce

Token	Service name
dhl_ecommerce_marketing_parcel_expedited	Marketing Parcel Expedited
dhl_ecommerce_globalmail_business_ipa	GlobalMail Business IPA
dhl_ecommerce_parcel_international_direct	Parcel International Direct
dhl_ecommerce_parcels_expedited_max	Parcels Expedited Max
dhl_ecommerce_bpm_ground	Bounded Printed Matter Ground
dhl_ecommerce_priority_expedited	Priority Expedited
dhl_ecommerce_globalmail_packet_ipa	GlobalMail Packet IPA
dhl_ecommerce_globalmail_packet_isal	GlobalMail Packet ISAL
dhl_ecommerce_easy_return_plus	Easy Return Plus
dhl_ecommerce_marketing_parcel_ground	Marketing Parcel Ground
dhl_ecommerce_first_class_parcel_expedited	First Class Parcel Expedited
dhl_ecommerce_globalmail_business_priority	GlobalMail Business Priority
dhl_ecommerce_parcels_expedited	Parcels Expedited
dhl_ecommerce_globalmail_business_isal	GlobalMail Business ISAL
dhl_ecommerce_parcel_plus_expedited_max	Parcel Plus Expedited Max
dhl_ecommerce_globalmail_packet_plus	GlobalMail Packet Plus
dhl_ecommerce_parcels_ground	Parcels Ground
dhl_ecommerce_expedited	Expedited
dhl_ecommerce_parcel_plus_ground	Parcel Plus Ground
dhl_ecommerce_parcel_international_standard	Parcel International Standard
dhl_ecommerce_bpm_expedited	Bounded Printed Matter Expedited
dhl_ecommerce_parcel_international_expedited	Parcel International Expedited
dhl_ecommerce_globalmail_packet_priority	GlobalMail Packet Priority
dhl_ecommerce_easy_return_light	Easy Return Light
dhl_ecommerce_parcel_plus_expedited	Parcel Plus Expedited
dhl_ecommerce_globalmail_business_standard	GlobalMail Packet Standard
dhl_ecommerce_ground	Ground
dhl_ecommerce_globalmail_packet_standard	GlobalMail Business Standard

DHL Germany

Token	Service name
dhl_germany_europaket	DHL Germany Europaket
dhl_germany_paket	DHL Germany Paket
dhl_germany_paket_connect	DHL Germany Paket Connect
dhl_germany_paket_international	DHL Germany Paket International
dhl_germany_paket_priority	DHL Germany Paket Priority
dhl_germany_paket_sameday	DHL Germany Paket Sameday

DPD DE

Token	Service name
dpd_de_classic	DPD Classic

DPD UK

Token	Service name
dpd_uk_ship_to_shop	Ship to shop
dpd_uk_1030	Door to door 10.30 next day
dpd_uk_1200	Door to door 12.00 next day
dpd_uk_saturday	Saturday Delivery
dpd_uk_saturday_1030	Saturday Delivery 10.30
dpd_uk_saturday_1200	Saturday Delivery 12.00
dpd_uk_sunday	Sunday Delivery
dpd_uk_sunday_1030	Sunday Delivery 10.30
dpd_uk_sunday_1200	Sunday Delivery 12.00
dpd_uk_next_day	Next day
dpd_uk_two_day	Two day
dpd_uk_classic	DPD Classic
dpd_uk_air_classic	DPD Air Classic
dpd_uk_air_express	DPD Air Express
dpd_uk_direct	DPD Direct
dpd_uk_direct_tracked_mail	DPD Tracked Mail
dpd_uk_pickup_returns	Pickup Returns

Deutsche Post

Token	Service name
deutsche_post_postkarte	Postkarte
deutsche_post_standardbrief	Standardbrief
deutsche_post_kompaktbrief	Kompaktbrief
deutsche_post_grossbrief	Grossbrief
deutsche_post_maxibrief	Maxibrief
deutsche_post_maxibrief_plus	Maxibrief Plus
deutsche_post_warenpost_international_xs	Warenpost International XS
deutsche_post_warenpost_international_s	Warenpost International S
deutsche_post_warenpost_international_m	Warenpost International M
deutsche_post_warenpost_international_l	Warenpost International L

Fastway Australia

Token	Service name
fastway_australia_parcel	Parcel
fastway_australia_satchel	Satchel
fastway_australia_box_small	Box Small
fastway_australia_box_medium	Box Medium
fastway_australia_box_large	Box Large

Globegistics

Token	Service name
globegistics_priority_mail_express_international	Globegistics Priority Mail Express International
globegistics_priority_mail_international	Globegistics Priority Mail International
globegistics_priority_mail_express_international_pds	Globegistics Priority Mail Express International PreSort Drop Ship
globegistics_priority_mail_international_pds	Globegistics Priority Mail International PreSort Drop Ship
globegistics_epacket	Globegistics ePacket
globegistics_ecom_tracked_ddp	Globegistics eCom Tracked DDP
globegistics_ecom_packet_ddp	Globegistics eCom Packet DDP
globegistics_ecom_priority_mail_international_ddp	Globegistics eCom Priority Mail International DDP
globegistics_ecom_priority_mail_express_international_ddp	Globegistics eCom Priority Mail Express International DDP
globegistics_ecom_extra	Globegistics eCom Extra
globegistics_ecom_international_priority_airmail	Globegistics eCom International Priority Airmail
globegistics_ecom_international_surface_airlift	Globegistics eCom International Surface Air Lift

GLS US

Token	Service name
gls_us_cps	GSO Ground
gls_us_eps	Early Priority Overnight
gls_us_ess	Early Saturday Delivery
gls_us_nps	Noon Priority Overnight
gls_us_pds	Priority Overnight
gls_us_sds	Saturday Delivery

LSO

Token	Service name
lso_ground	Ground
lso_economy_next_day	Economy Next Day
lso_saturday_delivery	Saturday Delivery
lso_2nd_day	2nd Day
lso_priority_next_day	Priority Next Day
lso_early_overnight	Early Overnight

Mondial Relay

Token	Service name
mondial_relay_pointrelais	Point Relais

Parcelforce

Token	Service name
parcelforce_express48	Express 48
parcelforce_express24	Express 24
parcelforce_expressam	Express AM

Poste Italiane

Token	Service name
poste_italiane_delivery_business_express	Poste Delivery Business Express

RR Donnelley

Token	Service name
rr_donnelley_domestic_economy_parcel	Domestic Economy Parcel
rr_donnelley_domestic_priority_parcel	Domestic Priority Parcel
rr_donnelley_domestic_parcel_bpm	Domestic Parcel BPM
rr_donnelley_priority_domestic_priority_parcel_bpm	Domestic Priority Parcel BPM
rr_donnelley_priority_parcel_delcon	International Priority Parcel DelCon
rr_donnelley_priority_parcel_nondelcon	International Priority Parcel NonDelcon
rr_donnelley_economy_parcel	Economy Parcel Service
rr_donnelley_ipa	International Priority Airmail (IPA)
rr_donnelley_courier	International Courier
rr_donnelley_isal	International Surface Air Lift (ISAL)
rr_donnelley_epacket	e-Packet
rr_donnelley_pmi	Priority Mail International
rr_donnelley_emi	Express Mail International

Royal Mail

Token	Service name
royal_mail_tracked_letter_boxable_24_no_signature	Royal Mail Tracked Letter-Boxable 24 No Signature
royal_mail_tracked_letter_boxable_48_no_signature	Royal Mail Tracked Letter-Boxable 48 No Signature
royal_mail_tracked_24_returns	Royal Mail Tracked Returns 24
royal_mail_tracked_48_returns	Royal Mail Tracked Returns 48

Sendle

Token	Service name
sendle_parcel	Sendle Parcel

Swyft

Token	Service name
same_day	Same day
next_day	Next day

UDS

Token	Service name
uds_next_day	Next day

Newgistics

Token	Service name
newgistics_parcel_select_lightweight	Parcel Select Lightweight
newgistics_parcel_select	Parcel Select
newgistics_priority_mail	Priority Mail
newgistics_first_class_mail	First Class Mail

OnTrac

Token	Service name
ontrac_ground	Ground
ontrac_sunrise_gold	Sunrise Gold
ontrac_sunrise	Sunrise

Lasership

Token	Service name
lasership_routed_delivery	Routed Delivery

Evri UK

Token	Service name
hermes_uk_courier_service	Courier Collection
hermes_uk_parcelshop_dropoff	ParcelShop Drop-Off
hermes_uk_parcelshop_dropoff_nextday	ParcelShop Drop-Off Next Day
hermes_uk_postable	Postable
hermes_uk_postable_nextday	Postable Next Day

Parcel Templates

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

FedEx

Token	Name	Dimensions
FedEx_Box_10kg	FedEx® 10kg Box
FedEx_Box_25kg	FedEx® 25kg Box
FedEx_Box_Extra_Large_1	FedEx® Extra Large Box (X1)
FedEx_Box_Extra_Large_2	FedEx® Extra Large Box (X2)
FedEx_Box_Large_1	FedEx® Large Box (L1)
FedEx_Box_Large_2	FedEx® Large Box (L2)
FedEx_Box_Medium_1	FedEx® Medium Box (M1)
FedEx_Box_Medium_2	FedEx® Medium Box (M2)
FedEx_Box_Small_1	FedEx® Small Box (S1)
FedEx_Box_Small_2	FedEx® Small Box (S2)
FedEx_Envelope	FedEx® Envelope
FedEx_Padded_Pak	FedEx® Padded Pak
FedEx_Pak_1	FedEx® Large Pak
FedEx_Pak_2	FedEx® Small Pak
FedEx_Tube	FedEx® Tube
FedEx_XL_Pak	FedEx® Extra Large Pak

UPS

Token	Name	Dimensions
UPS_Box_10kg	Box 10kg
UPS_Box_25kg	Box 25kg
UPS_Express_Box	Express Box
UPS_Express_Box_Large	Express Box Large
UPS_Express_Box_Medium	Express Box Medium
UPS_Express_Box_Small	Express Box Small
UPS_Express_Envelope	Express Envelope
UPS_Express_Hard_Pak	Express Hard Pak
UPS_Express_Legal_Envelope	Express Legal Envelope
UPS_Express_Pak	Express Pak
UPS_Express_Tube	Express Tube
UPS_Laboratory_Pak	Laboratory Pak
UPS_MI_BPM	BPM (Mail Innovations - Domestic & International)
UPS_MI_BPM_Flat	BPM Flat (Mail Innovations - Domestic & International)
UPS_MI_BPM_Parcel	BPM Parcel (Mail Innovations - Domestic & International)
UPS_MI_First_Class	First Class (Mail Innovations - Domestic only)
UPS_MI_Flat	Flat (Mail Innovations - Domestic only)
UPS_MI_Irregular	Irregular (Mail Innovations - Domestic only)
UPS_MI_Machinable	Machinable (Mail Innovations - Domestic only)
UPS_MI_MEDIA_MAIL	Media Mail (Mail Innovations - Domestic only)
UPS_MI_Parcel_Post	Parcel Post (Mail Innovations - Domestic only)
UPS_MI_Priority	Priority (Mail Innovations - Domestic only)
UPS_MI_Standard_Flat	Standard Flat (Mail Innovations - Domestic only)
UPS_Pad_Pak	Pad Pak
UPS_Pallet	Pallet

USPS

Token	Name	Dimensions
USPS_FlatRateCardboardEnvelope	Flat Rate Cardboard Envelope
USPS_FlatRateEnvelope	Flat Rate Envelope
USPS_FlatRateGiftCardEnvelope	Flat Rate Gift Card Envelope
USPS_FlatRateLegalEnvelope	Flat Rate Legal Envelope
USPS_FlatRatePaddedEnvelope	Flat Rate Padded Envelope
USPS_FlatRateWindowEnvelope	Flat Rate Window Envelope
USPS_IrregularParcel	Irregular Parcel
USPS_LargeFlatRateBoardGameBox	Large Flat Rate Board Game Box
USPS_LargeFlatRateBox	Large Flat Rate Box
USPS_APOFlatRateBox	APO/FPO/DPO Large Flat Rate Box
USPS_LargeVideoFlatRateBox	Flat Rate Large Video Box (Int'l only)
USPS_MediumFlatRateBox1	Medium Flat Rate Box 1
USPS_MediumFlatRateBox2	Medium Flat Rate Box 2
USPS_RegionalRateBoxA1	Regional Rate Box A1
USPS_RegionalRateBoxA2	Regional Rate Box A2
USPS_RegionalRateBoxB1	Regional Rate Box B1
USPS_RegionalRateBoxB2	Regional Rate Box B2
USPS_SmallFlatRateBox	Small Flat Rate Box
USPS_SmallFlatRateEnvelope	Small Flat Rate Envelope
USPS_SoftPack	Soft Pack Padded Envelope	Length and width defined in the Parcel

DHL eCommerce

Token	Name	Dimensions
DHLeC_Irregular	Irregular Shipment
DHLeC_SM_Flats	Flats

DPD UK

Token	Name	Dimensions
DPD_UK_Express_Pak	DPD UK Express Pak

CouriersPlease

Token	Name	Dimensions
couriersplease_500g_satchel	500g Satchel
couriersplease_1kg_satchel	1kg Satchel
couriersplease_3kg_satchel	3kg Satchel
couriersplease_5kg_satchel	5kg Satchel

Fastway Australia

Token	Name	Dimensions
Fastway_Australia_Satchel_A2	Satchel A2
Fastway_Australia_Satchel_A3	Satchel A3
Fastway_Australia_Satchel_A4	Satchel A4
Fastway_Australia_Satchel_A5	Satchel A5