Overview


First-time users and those looking for specific integration tutorials, see our full API documentation and guides.
Download the API Specification yaml file

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

This reference guide supports the Shippo API version: 2018-02-08 .

To see reference guides for older API versions, see our legacy reference guide. For more information about Shippo API versions, see our API versions guide.

Addresses

Addresses are the locations a parcel is being shipped from and to. They represent company and residential places. Among other things, you can use address objects to create shipments, calculate shipping rates, and purchase shipping labels.

Address represents the address as retrieved from the database

name
string

required for purchase
First and Last Name of the addressee

company
string

Company Name

street1
string

required for purchase
First street line, 35 character limit. Usually street number and street name (except for DHL Germany, see street_no).

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.

street_no
string

Street number of the addressed building. This field can be included in street1 for all carriers except for DHL Germany.

city
string

required for purchase
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.

state
string

required for purchase for some countries
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.

zip
string

required for purchase
Postal code of an Address. When creating a Quote Addresses, sending a ZIP is optional but will yield more accurate Rates.

country
required
string

ISO 3166-1 alpha-2 country codes and country names can be used. For most consistent results, we reccomend using country codes like US or DE. If using country names, please ensure they are spelled correctly and in English. Country names are converted to country codes. Refer to this guide for a list of country codes. 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
string

E-mail address of the contact person, RFC3696/5321-compliant.

is_residential
boolean
metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

is_complete
boolean

Complete addresses contain all required values.

Incomplete addresses have failed one or multiple validations.
Incomplete Addresses are eligible for requesting rates but lack at least one required value for purchasing labels.

latitude
number or string

Latitude of address

longitude
number or string

Longitude of address

object_created
string <date-time>

Date and time of Address creation.

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_updated
string <date-time>

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 (AddressValidationResults)

Object that contains information regarding if an address had been validated or not. Also contains any messages generated during validation. Children keys are is_valid(boolean) and messages(array).

test
boolean

Indicates whether the object has been created in test mode.

{
  • "name": "Shwan Ippotle",
  • "company": "Shippo",
  • "street1": "215 Clayton St.",
  • "street2": "string",
  • "street3": "",
  • "street_no": "",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip": "94117",
  • "country": "US",
  • "phone": "+1 555 341 9393",
  • "email": "shippotle@shippo.com",
  • "is_residential": true,
  • "metadata": "Customer ID 123456",
  • "is_complete": true,
  • "latitude": 0,
  • "longitude": 0,
  • "object_created": "2014-07-09T02:19:13.174Z",
  • "object_id": "d799c2679e644279b59fe661ac8fa488",
  • "object_owner": "shippotle@shippo.com",
  • "object_updated": "2014-07-09T02:19:13.174Z",
  • "validation_results": {
    },
  • "test": false
}

List all addresses

Returns a list of all address objects that have been created in this account.

SecurityAPIKeyHeader
Request
query Parameters
page
integer <int64>
Default: 1

The page number you want to select

results
integer <int64> <= 100
Default: 5

The number of results to return per page (max 100, default 5)

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/addresses
Request samples 
curl https://api.goshippo.com/addresses/ \
 -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "next": "baseurl?page=3&results=10",
  • "previous": "baseurl?page=1&results=10",
  • "results": [
    ]
}

Create a new address

Creates a new address object. You can use address objects to create new shipments, calculate rates, and to create orders.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required

Address details.

name
string

required for purchase
First and Last Name of the addressee

company
string

Company Name

street1
string

required for purchase
First street line, 35 character limit. Usually street number and street name (except for DHL Germany, see street_no).

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.

street_no
string

Street number of the addressed building. This field can be included in street1 for all carriers except for DHL Germany.

city
string

required for purchase
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.

state
string

required for purchase for some countries
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.

zip
string

required for purchase
Postal code of an Address. When creating a Quote Addresses, sending a ZIP is optional but will yield more accurate Rates.

country
required
string

ISO 3166-1 alpha-2 country codes and country names can be used. For most consistent results, we reccomend using country codes like US or DE. If using country names, please ensure they are spelled correctly and in English. Country names are converted to country codes. Refer to this guide for a list of country codes. 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
string

E-mail address of the contact person, RFC3696/5321-compliant.

is_residential
boolean
metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

validate
boolean

Set to true to validate Address object.

Responses
201
400
post/addresses
Request samples
application/json
{
  • "name": "Shwan Ippotle",
  • "company": "Shippo",
  • "street1": "215 Clayton St.",
  • "street2": "string",
  • "street3": "",
  • "street_no": "",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip": "94117",
  • "country": "US",
  • "phone": "+1 555 341 9393",
  • "email": "shippotle@shippo.com",
  • "is_residential": true,
  • "metadata": "Customer ID 123456",
  • "validate": true
}
Response samples
application/json
{
  • "name": "Shwan Ippotle",
  • "company": "Shippo",
  • "street1": "215 Clayton St.",
  • "street2": "string",
  • "street3": "",
  • "street_no": "",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip": "94117",
  • "country": "US",
  • "phone": "+1 555 341 9393",
  • "email": "shippotle@shippo.com",
  • "is_residential": true,
  • "metadata": "Customer ID 123456",
  • "is_complete": true,
  • "latitude": 0,
  • "longitude": 0,
  • "object_created": "2014-07-09T02:19:13.174Z",
  • "object_id": "d799c2679e644279b59fe661ac8fa488",
  • "object_owner": "shippotle@shippo.com",
  • "object_updated": "2014-07-09T02:19:13.174Z",
  • "validation_results": {
    },
  • "test": false
}

Retrieve an address

Returns an existing address using an object ID.

SecurityAPIKeyHeader
Request
path Parameters
AddressId
required
string

Object ID of the address

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/addresses/{AddressId}
Request samples 
curl https://api.goshippo.com/addresses/d799c2679e644279b59fe661ac8fa488/ \
  -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "name": "Shwan Ippotle",
  • "company": "Shippo",
  • "street1": "215 Clayton St.",
  • "street2": "string",
  • "street3": "",
  • "street_no": "",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip": "94117",
  • "country": "US",
  • "phone": "+1 555 341 9393",
  • "email": "shippotle@shippo.com",
  • "is_residential": true,
  • "metadata": "Customer ID 123456",
  • "is_complete": true,
  • "latitude": 0,
  • "longitude": 0,
  • "object_created": "2014-07-09T02:19:13.174Z",
  • "object_id": "d799c2679e644279b59fe661ac8fa488",
  • "object_owner": "shippotle@shippo.com",
  • "object_updated": "2014-07-09T02:19:13.174Z",
  • "validation_results": {
    },
  • "test": false
}

Validate an address

Validates an existing address using an object ID

SecurityAPIKeyHeader
Request
path Parameters
AddressId
required
string

Object ID of the address

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/addresses/{AddressId}/validate
Request samples 
curl https://api.goshippo.com/addresses/d799c2679e644279b59fe661ac8fa488/validate/ \
  -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "name": "Shwan Ippotle",
  • "company": "Shippo",
  • "street1": "215 Clayton St.",
  • "street2": "string",
  • "street3": "",
  • "street_no": "",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip": "94117",
  • "country": "US",
  • "phone": "+1 555 341 9393",
  • "email": "shippotle@shippo.com",
  • "is_residential": true,
  • "metadata": "Customer ID 123456",
  • "is_complete": true,
  • "latitude": 0,
  • "longitude": 0,
  • "object_created": "2014-07-09T02:19:13.174Z",
  • "object_id": "d799c2679e644279b59fe661ac8fa488",
  • "object_owner": "shippotle@shippo.com",
  • "object_updated": "2014-07-09T02:19:13.174Z",
  • "validation_results": {
    },
  • "test": false
}

Parcels

A parcel is an item you are shipping. The parcel object includes details about its physical make-up of the parcel. It includes dimensions and weight that Shippo uses to calculate rates.

object (ParcelExtra)

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.

metadata
string
mass_unit
required
string (WeightUnitEnum)

The unit used for weight.

Enum: "g" "kg" "lb" "oz"
weight
required
string

Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.

distance_unit
required
string (DistanceUnitEnum)

The measure unit used for length, width and height.

Enum: "cm" "in" "ft" "m" "mm" "yd"
height
required
string

Height of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.

length
required
string

Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.

width
required
string

Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.

object_created
string <date-time>

Date and time of Parcel creation.

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.

object_state
string

A Parcel will only be valid when all required values have been sent and validated successfully.

Value: "VALID"
object_updated
string <date-time>

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.

FedEx Parcel Template (string) or UPS Parcel Template (string) or USPS Parcel Template (string) or DHL eCommerce Parcel Template (string) or DPD UK Parcel Template (string) or Aramex Australia Parcel Template (string) (ParcelTemplateEnumSet)
test
boolean

Indicates whether the object has been created in test mode.

{
  • "extra": {
    },
  • "metadata": "Customer ID 123456",
  • "mass_unit": "lb",
  • "weight": "1",
  • "distance_unit": "in",
  • "height": "1",
  • "length": "1",
  • "width": "1",
  • "object_created": "2014-07-09T02:19:13.174Z",
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_owner": "shippotle@shippo.com",
  • "object_state": "VALID",
  • "object_updated": "2014-07-09T02:19:13.174Z",
  • "template": "FedEx_Box_10kg",
  • "test": true
}

Parcel Extras

The following values are supported for the extra field of the parcel 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.

object (COD)

Specify collection on delivery details (UPS only).

object (ParcelInsurance)

To add insurace to your parcel, specify amount, content and currency.

If you do not want to add insurance to you parcel, do not set these parameters.

reference_1
string

Optional text to be printed on the shipping label if supported by carrier. Up to 50 characters.

reference_2
string

Optional text to be printed on the shipping label if supported by carrier. Up to 50 characters.

{
  • "COD": {
    },
  • "insurance": {
    },
  • "reference_1": "string",
  • "reference_2": "string"
}

List all parcels

Returns a list of all parcel objects.

SecurityAPIKeyHeader
Request
query Parameters
page
integer <int64>
Default: 1

The page number you want to select

results
integer <int64> <= 100
Default: 25

The number of results to return per page (max 100)

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/parcels
Request samples 
curl https://api.goshippo.com/parcels/ \
  -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "next": "baseurl?page=3&results=10",
  • "previous": "baseurl?page=1&results=10",
  • "results": [
    ]
}

Create a new parcel

Creates a new parcel object.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required

Parcel details.

One of:
object (ParcelExtra)

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.

metadata
string
mass_unit
required
string (WeightUnitEnum)

The unit used for weight.

Enum: "g" "kg" "lb" "oz"
weight
required
string

Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.

distance_unit
required
string (DistanceUnitEnum)

The measure unit used for length, width and height.

Enum: "cm" "in" "ft" "m" "mm" "yd"
height
required
string

Height of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.

length
required
string

Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.

width
required
string

Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.

Responses
201
400
post/parcels
Request samples
application/json
{
  • "extra": {
    },
  • "metadata": "Customer ID 123456",
  • "mass_unit": "lb",
  • "weight": "1",
  • "distance_unit": "in",
  • "height": "1",
  • "length": "1",
  • "width": "1"
}
Response samples
application/json
{
  • "extra": {
    },
  • "metadata": "Customer ID 123456",
  • "mass_unit": "lb",
  • "weight": "1",
  • "distance_unit": "in",
  • "height": "1",
  • "length": "1",
  • "width": "1",
  • "object_created": "2014-07-09T02:19:13.174Z",
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_owner": "shippotle@shippo.com",
  • "object_state": "VALID",
  • "object_updated": "2014-07-09T02:19:13.174Z",
  • "template": "FedEx_Box_10kg",
  • "test": true
}

Retrieve an existing parcel

Returns parcel details using an existing parcel object ID (this will not return parcel details associated with un-purchased shipment/rate parcel object IDs).

SecurityAPIKeyHeader
Request
path Parameters
ParcelId
required
string

Object ID of the parcel

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/parcels/{ParcelId}
Request samples 
curl https://api.goshippo.com/parcels/7df2ecf8b4224763ab7c71fae7ec8274/ \
  -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "extra": {
    },
  • "metadata": "Customer ID 123456",
  • "mass_unit": "lb",
  • "weight": "1",
  • "distance_unit": "in",
  • "height": "1",
  • "length": "1",
  • "width": "1",
  • "object_created": "2014-07-09T02:19:13.174Z",
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_owner": "shippotle@shippo.com",
  • "object_state": "VALID",
  • "object_updated": "2014-07-09T02:19:13.174Z",
  • "template": "FedEx_Box_10kg",
  • "test": true
}

Carrier Parcel Templates

A carrier parcel template represents a package used for shipping that has preset dimensions defined by a carrier. Some examples of a carrier parcel template include USPS Flat Rate Box and Fedex Small Pak. When using a carrier parcel template, the rates returned may be limited to the carrier that provides the box. You can create user parcel templates using a carrier parcel template. Shippo takes the dimensions of the carrier parcel template but you must configure the weight.

carrier
string

The name of the carrier that provides this parcel template

distance_unit
string (DistanceUnitEnum)

The measure unit used for length, width and height.

Enum: "cm" "in" "ft" "m" "mm" "yd"
height
string

The height of the package, in units specified by the distance_unit attribute

is_variable_dimensions
boolean

True if the carrier parcel template allows custom dimensions, such as USPS Softpack.

length
string

The length of the package, in units specified by the distance_unit attribute

name
string

The name of the carrier parcel template

token
string

The unique string representation of the carrier parcel template

width
string

The width of the package, in units specified by the distance_unit attribute

{
  • "carrier": "FedEx",
  • "distance_unit": "in",
  • "height": "1.5",
  • "is_variable_dimensions": false,
  • "length": "12.375",
  • "name": "FedEx® Small Box (S1)",
  • "token": "FedEx_Box_Small_1",
  • "width": "10.875"
}

List all carrier parcel templates

List all carrier parcel template objects.
Use the following query string params to filter the results as needed.

  • `include=all` (the default). Includes templates from all carriers
  • `include=user`. Includes templates only from carriers which the user has added (whether or not they're currently enabled)
  • `include=enabled`. includes templates only for carriers which the user has added and enabled
  • `carrier=*token*`. filter by specific carrier, e.g. fedex, usps
SecurityAPIKeyHeader
Request
query Parameters
include
string

filter by user or enabled

Enum: "all" "user" "enabled"
carrier
string

filter by specific carrier

Example: carrier=fedex
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/parcel-templates
Request samples 
curl https://api.goshippo.com/parcel-templates  \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396" \
-H "Content-Type: application/json"
Response samples
application/json
{
  • "results": [
    ]
}

Retrieve a carrier parcel templates

Fetches the parcel template information for a specific carrier parcel template, identified by the token.

SecurityAPIKeyHeader
Request
path Parameters
CarrierParcelTemplateToken
required
string

The unique string representation of the carrier parcel template

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/parcel-templates/{CarrierParcelTemplateToken}
Request samples 
curl https://api.goshippo.com/parcel-templates/Fedex_Box_Small_1  \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396" \
-H "Content-Type: application/json"
Response samples
application/json
{
  • "carrier": "FedEx",
  • "distance_unit": "in",
  • "height": "1.5",
  • "is_variable_dimensions": false,
  • "length": "12.375",
  • "name": "FedEx® Small Box (S1)",
  • "token": "FedEx_Box_Small_1",
  • "width": "10.875"
}

User Parcel Templates

A user parcel template represents a package used for shipping that has preset dimensions and attributes defined by you. They are useful for capturing attributes of parcel-types you frequently use for shipping, allowing them to be defined once and then used for many shipments. These parcel templates can also be used for live rates.

User parcel templates can also be created using a carrier parcel template, where the dimensions will be copied from the carrier presets, but the weight can be configured by you.

distance_unit
string (DistanceUnitEnum)

The measure unit used for length, width and height. Required, but if using a preset carrier template then this field must be empty.

Enum: "cm" "in" "ft" "m" "mm" "yd"
height
string

The height of the package, in units specified by the distance_unit attribute. Required, but if using a preset carrier template then this field must be empty.

length
string

The length of the package, in units specified by the distance_unit attribute. Required, but if using a preset carrier template then this field must be empty.

name
string

The name of the User Parcel Template

weight
string

The weight of the package, in units specified by the weight_unit attribute.

weight_unit
string (WeightUnitEnum)

The unit used for weight.

Enum: "g" "kg" "lb" "oz"
width
string

The width of the package, in units specified by the distance_unit attribute. Required, but if using a preset carrier template then this field must be empty.

object_created
string <date-time>

Date and time of User Parcel Template creation

object_id
string

Unique identifier of the given User Parcel Template object

object_owner
string

Username of the user who created the User Parcel Template object

object_updated
string <date-time>

Date and time of last update on User Parcel Template

object (CarrierParcelTemplate)
{
  • "distance_unit": "in",
  • "height": "6",
  • "length": "10",
  • "name": "My Custom Template",
  • "weight": "12",
  • "weight_unit": "lb",
  • "width": "8",
  • "object_created": "2013-12-11T19:38:09.729Z",
  • "object_id": "b958d3690bb04bb8b2986724872750f5",
  • "object_owner": "shippotle@shippo.com",
  • "object_updated": "2013-12-12T19:38:09.729Z",
  • "template": {
    }
}

List all user parcel templates

Returns a list all of all user parcel template objects.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/user-parcel-templates
Request samples 
curl https://api.goshippo.com/user-parcel-templates  \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396" \
-H "Content-Type: application/json"
Response samples
application/json
{
  • "results": [
    ]
}

Create a new user parcel template

Creates a new user parcel template.
You can choose to create a parcel template using a preset carrier template as a starting point, or you can create an entirely custom one. To use a preset carrier template, pass in a unique template token from this list plus the weight fields (weight and weight_unit). Otherwise, omit the template field and pass the other fields, for the weight, length, height, and depth, as well as their units."

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required
One of:
template
string

The object representing the carrier parcel template

weight
string

The weight of the package, in units specified by the weight_unit attribute.

weight_unit
string (WeightUnitEnum)

The unit used for weight.

Enum: "g" "kg" "lb" "oz"
Responses
200
400
post/user-parcel-templates
Request samples
application/json
{
  • "distance_unit": "in",
  • "height": "6",
  • "length": "10",
  • "name": "My Custom Template",
  • "weight": "12",
  • "weight_unit": "lb",
  • "width": "8"
}
Response samples
application/json
{
  • "distance_unit": "in",
  • "height": "6",
  • "length": "10",
  • "name": "My Custom Template",
  • "weight": "12",
  • "weight_unit": "lb",
  • "width": "8",
  • "object_created": "2013-12-11T19:38:09.729Z",
  • "object_id": "b958d3690bb04bb8b2986724872750f5",
  • "object_owner": "shippotle@shippo.com",
  • "object_updated": "2013-12-12T19:38:09.729Z",
  • "template": {
    }
}

Delete a user parcel template

Deletes a user parcel template using an object ID.

SecurityAPIKeyHeader
Request
path Parameters
UserParcelTemplateObjectId
required
string

Object ID of the user parcel template

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
204

The user parcel template was successfully deleted.

400
delete/user-parcel-templates/{UserParcelTemplateObjectId}
Request samples 
curl -X DELETE https://api.goshippo.com/user-parcel-templates/{UserParcelTemplateObjectId}  \
  -H "Authorization: ShippoToken <API_TOKEN>"
Response samples
application/json
{ }

Retrieves a user parcel template

Returns the parcel template information for a specific user parcel template, identified by the object ID.

SecurityAPIKeyHeader
Request
path Parameters
UserParcelTemplateObjectId
required
string

Object ID of the user parcel template

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/user-parcel-templates/{UserParcelTemplateObjectId}
Request samples 
curl /user-parcel-templates/{UserParcelTemplateToken}  \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -H "Content-Type: application/json"
Response samples
application/json
{
  • "distance_unit": "in",
  • "height": "6",
  • "length": "10",
  • "name": "My Custom Template",
  • "weight": "12",
  • "weight_unit": "lb",
  • "width": "8",
  • "object_created": "2013-12-11T19:38:09.729Z",
  • "object_id": "b958d3690bb04bb8b2986724872750f5",
  • "object_owner": "shippotle@shippo.com",
  • "object_updated": "2013-12-12T19:38:09.729Z",
  • "template": {
    }
}

Update an existing user parcel template

Updates an existing user parcel template.

SecurityAPIKeyHeader
Request
path Parameters
UserParcelTemplateObjectId
required
string

Object ID of the user parcel template

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
distance_unit
required
string (DistanceUnitEnum)

The measure unit used for length, width and height. Required, but if using a preset carrier template then this field must be empty.

Enum: "cm" "in" "ft" "m" "mm" "yd"
height
required
string

The height of the package, in units specified by the distance_unit attribute. Required, but if using a preset carrier template then this field must be empty.

length
required
string

The length of the package, in units specified by the distance_unit attribute. Required, but if using a preset carrier template then this field must be empty.

name
required
string

The name of the User Parcel Template

weight
string

The weight of the package, in units specified by the weight_unit attribute.

weight_unit
string (WeightUnitEnum)

The unit used for weight.

Enum: "g" "kg" "lb" "oz"
width
required
string

The width of the package, in units specified by the distance_unit attribute. Required, but if using a preset carrier template then this field must be empty.

Responses
200
400
put/user-parcel-templates/{UserParcelTemplateObjectId}
Request samples
application/json
{
  • "distance_unit": "in",
  • "height": "6",
  • "length": "10",
  • "name": "My Custom Template",
  • "weight": "12",
  • "weight_unit": "lb",
  • "width": "8"
}
Response samples
application/json
{
  • "distance_unit": "in",
  • "height": "6",
  • "length": "10",
  • "name": "My Custom Template",
  • "weight": "12",
  • "weight_unit": "lb",
  • "width": "8",
  • "object_created": "2013-12-11T19:38:09.729Z",
  • "object_id": "b958d3690bb04bb8b2986724872750f5",
  • "object_owner": "shippotle@shippo.com",
  • "object_updated": "2013-12-12T19:38:09.729Z",
  • "template": {
    }
}

Shipments

A shipment is the act of transporting goods. A shipment object contains to and from addresses, and the parcel details that you are shipping. You can use the shipment object to retrieve shipping rates and purchase a shipping label.

Shipment represents the parcel as retrieved from the database

object (ShipmentExtra)

An object holding optional extra services to be requested.

metadata
required
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

shipment_date
string

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.

required
object (AddressFrom)

Address object of the sender / seller. Will be returned expanded by default.

object (AddressReturn)

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.

required
object (AddressTo)

Address object of the recipient / buyer. Will be returned expanded by default.

carrier_accounts
required
Array of strings

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.

object (CustomsDeclaration)
required
Array of objects (ResponseMessageList)
object_created
required
string <date-time>

Date and time of Shipment creation.

object_id
required
string

Unique identifier of the given Shipment object.

object_owner
required
string

Username of the user who created the Shipment object.

object_updated
required
string <date-time>

Date and time of last Shipment update.

required
Array of objects (Parcel)

List of Parcel objects to be shipped.

required
Array of objects (Rate)

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.

status
required
string

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.

Enum: "ERROR" "QUEUED" "SUCCESS" "WAITING"
test
boolean

Indicates whether the object has been created in test mode.

{
  • "extra": {
    },
  • "metadata": "Customer ID 123456",
  • "shipment_date": "2021-03-22T12:00:00Z",
  • "address_from": {
    },
  • "address_return": {
    },
  • "address_to": {
    },
  • "carrier_accounts": [
    ],
  • "customs_declaration": {
    },
  • "messages": [
    ],
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_owner": "pp@gmail.com",
  • "object_updated": "2019-08-24T14:15:22Z",
  • "parcels": [
    ],
  • "rates": [
    ],
  • "status": "QUEUED",
  • "test": true
}

Shipment Extras

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

An object holding optional extra services to be requested.

object (UPSReferenceFields)

UPS only. Adds custom accounts receivable customer account reference to UPS labels.

object (Alcohol)

Indicates that a shipment contains Alcohol (Fedex and UPS only).

ancillary_endorsement
any

Specify an ancillary service endorsement to provide the USPS with instructions on how to handle undeliverable-as-addressed pieces (DHL eCommerce only).

Enum: "FORWARDING_SERVICE_REQUESTED" "RETURN_SERVICE_REQUESTED"
object (UPSReferenceFields)

UPS only. Adds custom appropriation number reference to UPS labels.

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

object (UPSReferenceFields)

UPS only. Adds custom bill of lading number reference to UPS labels.

object (Billing)

Specify billing details (UPS, FedEx, and DHL Germany only).

bypass_address_validation
boolean

Bypasses address validation (USPS, UPS, & LaserShip only).

carbon_neutral
boolean

Request carbon offsets by passing true (UPS only).

carrier_hub_id
string

Identifies the carrier injection site.

carrier_hub_travel_time
integer

Travel time in hours from fulfillment center to carrier injection site.

object (COD)

Specify collection on delivery details (UPS only).

object (UPSReferenceFields)

UPS only. Adds custom COD number reference to UPS labels.

container_type
string

Specify container type.

critical_pull_time
string

Carrier arrival time to pickup packages from the fulfillment center. UTC format: %Y-%m-%dT%H:%M:%SZ

customer_branch
string

Specify customer branch (Lasership only).

object (CustomerReference)

Specify the reference field on the label (FedEx and UPS only).

object (DangerousGoodsObject)

Container for specifying the presence of dangerous materials. This is specific to USPS, and if any contents are provided, only certain USPS service levels will be eligible. For more information, see our guide on hazardous or dangerous materials shipping.

dangerous_goods_code
any

Dangerous Goods Code (DHL eCommerce only). See Category Codes

Enum: "01" "02" "03" "04" "05" "06" "07" "08" "09"
object (UPSReferenceFields)

UPS only. Adds custom dealer order number reference to UPS labels.

delivery_instructions
string

Specify delivery instructions. Up to 500 characters. (FedEx and OnTrac only).

object (DepartmentNumber)

Specify the department number field on the label (FedEx and UPS only).

object (DryIce)

Specify that the package contains Dry Ice (FedEx, Veho, and UPS only).

object (UPSReferenceFields)

UPS only. Adds custom FDA product code reference to UPS labels.

fulfillment_center
string

The fulfilment center where the package originates from.

object (Insurance)

To add 3rd party insurance powered by XCover, specify
amount, content, and currency.
Alternatively, you can choose carrier provided insurance by additionally specifying provider (UPS, FedEx and OnTrac only).

If you do not want to add insurance to your shipment, do not set these parameters.

object (InvoiceNumber)

Specify the invoice number field on the label (FedEx and UPS only).

is_return
boolean

This field specifies if it is a scan-based return shipment. See the Create a return shipment section for more details.

lasership_attrs
Array of strings (ShipmentExtraLasershipAttributesEnum)

Specify Lasership Attributes (Lasership only). Multiple options accepted.

Items Enum: "TwoPersonDelivery" "Explosive" "Alcohol" "Hazmat" "ControlledSubstance" "Refrigerated" "DryIce" "Perishable" "NoRTS"
lasership_declared_value
string

Declared value (Lasership only). Defaults to 50.00.

object (UPSReferenceFields)

UPS only. Adds custom manifest number reference to UPS labels.

object (UPSReferenceFields)

UPS only. Adds custom model number reference to UPS labels.

object (UPSReferenceFields)

UPS only. Adds custom part number reference to UPS labels.

object (PoNumber)

Specify the PO number field on the label (FedEx and UPS only).

preferred_delivery_timeframe
any

Required for DHL Germany Paket Sameday. Designates a desired timeframe for delivery. Format is HHMMHHMM

Enum: "10001200" "12001400" "14001600" "16001800" "18002000" "19002100"
premium
boolean

Add premium service to a shipment (DHL Germany international shipments only).

object (UPSReferenceFields)

UPS only. Adds custom product code reference to UPS labels.

object (UPSReferenceFields)

UPS only. Adds custom purchase request number reference to UPS labels.

qr_code_requested
boolean

Request a QR code for a given transaction when creating a shipping label (USPS domestic and Evri UK only).

reference_1
string

Optional text to be printed on the shipping label if supported by carrier. Up to 50 characters.

reference_2
string

Optional text to be printed on the shipping label if supported by carrier. Up to 50 characters. For DHL eCommerce, this field can be used for billing reference.

request_retail_rates
boolean

Returns retail rates instead of account-based rates (UPS and FedEx only).

ShipmentExtraReturnServiceTypeUPSEnum (string) or ShipmentExtraReturnServiceTypeLasershipEnum (string)

Request additional return option for return shipments (UPS and Lasership only).

object (RmaNumber)

Specify the RMA number field on the label (FedEx and UPS only).

saturday_delivery
boolean

Marks shipment as to be delivered on a Saturday.

object (UPSReferenceFields)

UPS only. Adds custom salesperson number reference to UPS labels.

object (UPSReferenceFields)

UPS only. Adds custom serial number reference to UPS labels.

signature_confirmation
any

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

Enum: "STANDARD" "ADULT" "CERTIFIED" "INDIRECT" "CARRIER_CONFIRMATION"
object (UPSReferenceFields)

UPS only. Adds custom store number reference to UPS labels.

object (UPSReferenceFields)

UPS only. Adds custom transaction reference number to UPS labels.

{
  • "accounts_receivable_customer_account": {
    },
  • "alcohol": {
    },
  • "ancillary_endorsement": "FORWARDING_SERVICE_REQUESTED",
  • "appropriation_number": {
    },
  • "authority_to_leave": true,
  • "bill_of_lading_number": {
    },
  • "billing": {
    },
  • "bypass_address_validation": true,
  • "carbon_neutral": true,
  • "carrier_hub_id": "string",
  • "carrier_hub_travel_time": 0,
  • "COD": {
    },
  • "cod_number": {
    },
  • "container_type": "string",
  • "critical_pull_time": "string",
  • "customer_branch": "string",
  • "customer_reference": {
    },
  • "dangerous_goods": {
    },
  • "dangerous_goods_code": "01",
  • "dealer_order_number": {
    },
  • "delivery_instructions": "string",
  • "dept_number": {
    },
  • "dry_ice": {
    },
  • "fda_product_code": {
    },
  • "fulfillment_center": "string",
  • "insurance": {
    },
  • "invoice_number": {
    },
  • "is_return": true,
  • "lasership_attrs": [
    ],
  • "lasership_declared_value": "string",
  • "manifest_number": {
    },
  • "model_number": {
    },
  • "part_number": {
    },
  • "po_number": {
    },
  • "preferred_delivery_timeframe": "10001200",
  • "premium": true,
  • "production_code": {
    },
  • "purchase_request_number": {
    },
  • "qr_code_requested": true,
  • "reference_1": "string",
  • "reference_2": "string",
  • "request_retail_rates": true,
  • "return_service_type": "PRINT_AND_MAIL",
  • "rma_number": {
    },
  • "saturday_delivery": true,
  • "salesperson_number": {
    },
  • "serial_number": {
    },
  • "signature_confirmation": "STANDARD",
  • "store_number": {
    },
  • "transaction_reference_number": {
    }
}

List all shipments

Returns a list of 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

SecurityAPIKeyHeader
Request
query Parameters
page_token
string

The page token for paginated results

page
integer <int64>
Default: 1

The page number you want to select

results
integer <int64> <= 100
Default: 25

The number of results to return per page (max 100)

object_created_gt
string

Object(s) created greater than a provided date and time.

object_created_gte
string

Object(s) created greater than or equal to a provided date and time.

object_created_lt
string

Object(s) created lesser than a provided date and time.

object_created_lte
string

Object(s) created lesser than or equal to a provided date and time.

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/shipments
Request samples 
curl https://api.goshippo.com/shipments/ \
  -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "next": "baseurl?page=3&results=10",
  • "previous": "baseurl?page=1&results=10",
  • "results": [
    ]
}

Create a new shipment

Creates a new shipment object.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required

Shipment details and contact info.

object (ShipmentExtra)

An object holding optional extra services to be requested.

metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

shipment_date
string

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.

required
AddressCreateRequest (object) or string
AddressCreateRequest (object) or string
required
AddressCreateRequest (object) or string
CustomsDeclarationCreateRequest (object) or string
async
boolean
carrier_accounts
Array of strings

List of Carrier Accounts object_ids used to filter the returned rates. If set, only rates from these carriers will be returned.

required
Array of ParcelCreateRequest (object) or ParcelCreateFromTemplateRequest (object) or strings
Responses
201
400
post/shipments
Request samples
application/json
{
  • "extra": {
    },
  • "metadata": "Customer ID 123456",
  • "shipment_date": "2021-03-22T12:00:00Z",
  • "address_from": {
    },
  • "address_return": {
    },
  • "address_to": {
    },
  • "customs_declaration": {
    },
  • "async": true,
  • "carrier_accounts": [
    ],
  • "parcels": [
    ]
}
Response samples
application/json
{
  • "extra": {
    },
  • "metadata": "Customer ID 123456",
  • "shipment_date": "2021-03-22T12:00:00Z",
  • "address_from": {
    },
  • "address_return": {
    },
  • "address_to": {
    },
  • "carrier_accounts": [
    ],
  • "customs_declaration": {
    },
  • "messages": [
    ],
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_owner": "pp@gmail.com",
  • "object_updated": "2019-08-24T14:15:22Z",
  • "parcels": [
    ],
  • "rates": [
    ],
  • "status": "QUEUED",
  • "test": true
}

Retrieve a shipment

Returns an existing shipment using an object ID

SecurityAPIKeyHeader
Request
path Parameters
ShipmentId
required
string

Object ID of the shipment to update

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/shipments/{ShipmentId}
Request samples 
curl https://api.goshippo.com/shipments/7c47d12aa95a4cbb9d90c167cca7bea7 \
  -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "extra": {
    },
  • "metadata": "Customer ID 123456",
  • "shipment_date": "2021-03-22T12:00:00Z",
  • "address_from": {
    },
  • "address_return": {
    },
  • "address_to": {
    },
  • "carrier_accounts": [
    ],
  • "customs_declaration": {
    },
  • "messages": [
    ],
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_owner": "pp@gmail.com",
  • "object_updated": "2019-08-24T14:15:22Z",
  • "parcels": [
    ],
  • "rates": [
    ],
  • "status": "QUEUED",
  • "test": true
}

Rates

A rate is the cost to ship a parcel from a carrier. The rate object details the service level including the cost and transit time.

amount
required
string

Final Rate price, expressed in the currency used in the sender's country.

amount_local
required
string

Final Rate price, expressed in the currency used in the recipient's country.

currency
required
string

Currency used in the sender's country, refers to amount. The official ISO 4217 currency codes are used, e.g. USD or EUR.

currency_local
required
string

Currency used in the recipient's country, refers to amount_local. The official ISO 4217 currency codes are used, e.g. USD or "EUR".

arrives_by
string

Predicted time the carrier will deliver the package in the destination's local time zone. In the format HH:MM:SS.

attributes
required
Array of strings

An array containing specific attributes of this Rate in context of the entire shipment. Attributes can be assigned CHEAPEST, FASTEST, or BESTVALUE.

Items Enum: "BESTVALUE" "CHEAPEST" "FASTEST"
carrier_account
required
string

Object ID of the carrier account that has been used to retrieve the rate.

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.

estimated_days
integer <int64>

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.

included_insurance_price
string

Cost to the user to insure the Rate for the requested amount of coverage, if insurance coverage was requested. Expressed in the currency used in the sender's country. Will be null if no insurance coverage was requested, or if insurance is requested from a non-standard insurance provider. Please note this price is already included in the amount and amount_local fields on the Rate. Do not add this field to them.

Array of objects (ResponseMessageList)
object_created
required
string <date-time>

Date and time of Rate creation.

object_id
required
string

Unique identifier of the given Rate object.

object_owner
required
string

Username of the user who created the rate object.

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

required
object (ServiceLevelWithParent)

Contains details regarding the service level for the given rate.

shipment
required
string
test
boolean

Indicates whether the object has been created in test mode.

zone
string

The parcel's transit zone token. These tokens can vary depending on the provider.

{
  • "amount": "5.5",
  • "amount_local": "5.5",
  • "currency": "USD",
  • "currency_local": "USD",
  • "arrives_by": "08:30:00",
  • "attributes": [
    ],
  • "carrier_account": "078870331023437cb917f5187429b093",
  • "duration_terms": "Delivery in 1 to 3 business days",
  • "estimated_days": 2,
  • "included_insurance_price": "1.05",
  • "messages": [
    ],
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_owner": "pp@gmail.com",
  • "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": {
    },
  • "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "test": true,
  • "zone": "1"
}

Retrieve a rate

Returns an existing rate using a rate object ID.

SecurityAPIKeyHeader
Request
path Parameters
RateId
required
string

Object ID of the rate

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/rates/{RateId}
Request samples 
curl https://api.goshippo.com/rates/ee81fab0372e419ab52245c8952ccaeb \
  -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "amount": "5.5",
  • "amount_local": "5.5",
  • "currency": "USD",
  • "currency_local": "USD",
  • "arrives_by": "08:30:00",
  • "attributes": [
    ],
  • "carrier_account": "078870331023437cb917f5187429b093",
  • "duration_terms": "Delivery in 1 to 3 business days",
  • "estimated_days": 2,
  • "included_insurance_price": "1.05",
  • "messages": [
    ],
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_owner": "pp@gmail.com",
  • "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": {
    },
  • "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "test": true,
  • "zone": "1"
}

Retrieve shipment rates

Returns a paginated list of rates associated with a shipment

SecurityAPIKeyHeader
Request
path Parameters
ShipmentId
required
string

Object ID of the shipment to update

query Parameters
page
integer <int64>
Default: 1

The page number you want to select

results
integer <int64> <= 100
Default: 25

The number of results to return per page (max 100)

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/shipments/{ShipmentId}/rates
Request samples 
curl https://api.goshippo.com/shipments/5e40ead7cffe4cc1ad45108696162e42/rates/USD \
  -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "next": "baseurl?page=3&results=10",
  • "previous": "baseurl?page=1&results=10",
  • "results": [
    ]
}

Retrieve shipment rates in currency

Returns all available shipping rates for a shipment object.

When you create a new valid shipment object, Shippo automatically calculates 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 where the 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 currency code to 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 status to QUEUED) and the converted currency rates will only be available when the Shipment's status is set to SUCCESS.

SecurityAPIKeyHeader
Request
path Parameters
ShipmentId
required
string

Object ID of the shipment to update

CurrencyCode
required
string
Default: "USD"

ISO currency code for the rates

query Parameters
page
integer <int64>
Default: 1

The page number you want to select

results
integer <int64> <= 100
Default: 25

The number of results to return per page (max 100)

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/shipments/{ShipmentId}/rates/{CurrencyCode}
Request samples 
import shippo
from shippo.models import operations

s = shippo.Shippo(
    api_key_header='ShippoToken <API_TOKEN>',
    shippo_api_version='2018-02-08',
)


res = s.rates.list_shipment_rates_by_currency_code(request=operations.ListShipmentRatesByCurrencyCodeRequest(
    shipment_id='<id>',
    currency_code='USD',
))

if res is not None:
    # handle response
    pass
Response samples
application/json
{
  • "next": "baseurl?page=3&results=10",
  • "previous": "baseurl?page=1&results=10",
  • "results": [
    ]
}

Transactions (shipping labels)

A transaction is the purchase of a shipping label from a shipping provider for a specific service. You can print purchased labels and used them to ship a parcel with a carrier, such as USPS or FedEx.

commercial_invoice_url
string

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.

object or null
eta
string

The estimated time of arrival according to the carrier.

label_file_type
string (LabelFileTypeEnum)

Print format of the label. If empty, will use the default format set from the Shippo dashboard.

Enum: "PNG" "PNG_2.3x7.5" "PDF" "PDF_2.3x7.5" "PDF_4x6" "PDF_4x8" "PDF_A4" "PDF_A5" "PDF_A6" "ZPLII"
label_url
string

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.

Array of objects (ResponseMessageList)
metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

object_created
string <date-time>

Date and time of Transaction creation.

object_id
string

Unique identifier of the given Transaction object.

object_owner
string

Username of the user who created the Transaction object.

object_state
string (ObjectStateEnum)

Indicates the validity of the enclosing object

Enum: "VALID" "INVALID"
object_updated
string <date-time>

Date and time of last Transaction update.

parcel
string

Object ID of the Parcel object that is being shipped.

qr_code_url
string

A URL pointing directly to the QR code in PNG format. A value will only be returned if requested using qr_code_requested flag and the carrier provides such an option.

CoreRate (object) or string

ID of the Rate object for which a Label has to be obtained.
If you purchase a label by calling the transaction endpoint without a rate (instalabel), this field will be a simplified Rate object in the Transaction model returned from the POST request.
Note, only rates less than 7 days old can be purchased to ensure up-to-date pricing.

status
string (TransactionStatusEnum)

Indicates the status of the Transaction.

Enum: "WAITING" "QUEUED" "SUCCESS" "ERROR" "REFUNDED" "REFUNDPENDING" "REFUNDREJECTED"
test
boolean

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
string (TrackingStatusEnum)

Indicates the high level status of the shipment.

Enum: "UNKNOWN" "PRE_TRANSIT" "TRANSIT" "DELIVERED" "RETURNED" "FAILURE"
tracking_url_provider
string

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.

{}

List all shipping labels

Returns a list of all transaction objects.

SecurityAPIKeyHeader
Request
query Parameters
rate
string

Filter by rate ID

object_status
string (TransactionStatusEnum)

Filter by object status

Enum: "WAITING" "QUEUED" "SUCCESS" "ERROR" "REFUNDED" "REFUNDPENDING" "REFUNDREJECTED"
Example: object_status=SUCCESS
tracking_status
string (TrackingStatusEnum)

Filter by tracking status

Enum: "UNKNOWN" "PRE_TRANSIT" "TRANSIT" "DELIVERED" "RETURNED" "FAILURE"
Example: tracking_status=DELIVERED
page
integer <int64>
Default: 1

The page number you want to select

results
integer <int64> <= 100
Default: 25

The number of results to return per page (max 100)

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/transactions
Request samples 
curl https://api.goshippo.com/transactions/ \
  -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{}

Create a shipping label

Creates a new transaction object and purchases the shipping label using a rate object that has previously been created.
OR
Creates a new transaction object and purchases the shipping label instantly using shipment details, an existing carrier account, and an existing service level token.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required

Examples.

One of:
async
boolean
Default: true
label_file_type
string (LabelFileTypeEnum)

Print format of the label. If empty, will use the default format set from the Shippo dashboard.

Enum: "PNG" "PNG_2.3x7.5" "PDF" "PDF_2.3x7.5" "PDF_4x6" "PDF_4x8" "PDF_A4" "PDF_A5" "PDF_A6" "ZPLII"
metadata
string
rate
required
string
order
string
Responses
201
400
post/transactions
Request samples
application/json
{
  • "async": true,
  • "carrier_account": "b741b99f95e841639b54272834bc478c",
  • "label_file_type": "PDF",
  • "metadata": "Order ID",
  • "servicelevel_token": "usps_priority",
  • "shipment": {
    }
}
Response samples
application/json
{}

Retrieve a shipping label

Returns an existing transaction using an object ID.

SecurityAPIKeyHeader
Request
path Parameters
TransactionId
required
string

Object ID of the transaction to update

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/transactions/{TransactionId}
Request samples 
curl https://api.goshippo.com/transactions/70ae8117ee1749e393f249d5b77c45e0 \
 -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{}

Batches

A batch is a technique for creating multiple labels at once. Use the batch object to create and purchase many shipments in two API calls. After creating the batch, retrieve the batch to verify that all shipments are valid. You can add and remove shipments after you have created the batch. When all shipments are valid you can purchase the batch and retrieve all the shipping labels.

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. Servicelevel tokens can be found here.

label_filetype
string (LabelFileTypeEnum)

Print format of the label. If empty, will use the default format set from the Shippo dashboard.

Enum: "PNG" "PNG_2.3x7.5" "PDF" "PDF_2.3x7.5" "PDF_4x6" "PDF_4x8" "PDF_A4" "PDF_A5" "PDF_A6" "ZPLII"
metadata
string <= 100 characters

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

required
object (BatchShipmentPaginatedList)

Array of BatchShipment objects. The response keeps the same order as in the request array.

label_url
required
Array of strings

An array of URLs each pointing to a merged file of 100 labels each

object_created
required
string

Date and time of Batch creation

object_id
required
string

Unique identifier of the given Batch object

object_owner
required
string

Username of the user who created the Address object.

required
object

An object containing the following counts:
creation_succeeded
creation_failed
purchase_succeeded
purchase_failed

object_updated
required
string

Date and time of last update to the Batch

status
required
string

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.

Enum: "VALIDATING" "VALID" "INVALID" "PURCHASING" "PURCHASED"
test
boolean
{
  • "default_carrier_account": "078870331023437cb917f5187429b093",
  • "default_servicelevel_token": "usps_priority",
  • "label_filetype": "PDF_4x6",
  • "metadata": "BATCH #1",
  • "batch_shipments": {
    },
  • "label_url": [
    ],
  • "object_created": "2016-01-04T00:15:44.394Z",
  • "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  • "object_owner": "shippo@shippo.com",
  • "object_results": {
    },
  • "object_updated": "2016-01-04T00:48:13.841Z",
  • "status": "VALID",
  • "test": false
}

Batch Shipment

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

carrier_account
string

Object ID of the carrier account to be used for this shipment (will override batch default)

metadata
string <= 100 characters

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

servicelevel_token
string

A token that sets the shipping method for the batch, overriding the batch default. Servicelevel tokens can be found in this list or at this endpoint.

messages
Array of arrays

List of Shipment and Transaction error messages.

object_id
required
string

Object ID of this batch shipment. Can be used in the remove_shipments endpoint.

shipment
required
string

Object ID of the shipment object created for this batch shipment.

status
required
string

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.

Enum: "INVALID" "VALID" "INCOMPLETE" "TRANSACTION_FAILED"
transaction
string

Object ID of the transaction object created for this batch shipment.

{
  • "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
  • "metadata": "SHIPMENT #1",
  • "servicelevel_token": "fedex_ground",
  • "messages": [ ],
  • "object_id": "e11c95a6788d4ddcaa22f03175838740",
  • "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "status": "INVALID",
  • "transaction": "4c33736a67e2450da88b38c42deef6b7"
}

Create a batch

Creates a new batch object for purchasing shipping labels for many shipments at once. 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.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required

Batch details.

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. Servicelevel tokens can be found here.

label_filetype
string (LabelFileTypeEnum)

Print format of the label. If empty, will use the default format set from the Shippo dashboard.

Enum: "PNG" "PNG_2.3x7.5" "PDF" "PDF_2.3x7.5" "PDF_4x6" "PDF_4x8" "PDF_A4" "PDF_A5" "PDF_A6" "ZPLII"
metadata
string <= 100 characters

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

required
Array of objects (BatchShipmentCreateRequest)

Array of BatchShipment objects. The response keeps the same order as in the request array.

Responses
201
400
post/batches
Request samples
application/json
{
  • "default_carrier_account": "078870331023437cb917f5187429b093",
  • "default_servicelevel_token": "usps_priority",
  • "label_filetype": "PDF_4x6",
  • "metadata": "BATCH #1",
  • "batch_shipments": [
    ]
}
Response samples
application/json
{
  • "default_carrier_account": "078870331023437cb917f5187429b093",
  • "default_servicelevel_token": "usps_priority",
  • "label_filetype": "PDF_4x6",
  • "metadata": "BATCH #1",
  • "batch_shipments": {
    },
  • "label_url": [
    ],
  • "object_created": "2016-01-04T00:15:44.394Z",
  • "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  • "object_owner": "shippo@shippo.com",
  • "object_results": {
    },
  • "object_updated": "2016-01-04T00:48:13.841Z",
  • "status": "VALID",
  • "test": false
}

Retrieve a batch

Returns a batch using an object ID.
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 example, by passing a query param like ?object_results=creation_failed.
For more details on filtering results, see our guide on filtering.

SecurityAPIKeyHeader
Request
path Parameters
BatchId
required
string

Object ID of the batch

query Parameters
page
integer <int64>
Default: 1

The page number you want to select

results
integer <int64> <= 100
Default: 5

The number of results to return per page (max 100, default 5)

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/batches/{BatchId}
Request samples 
curl https://api.goshippo.com/batches/<BATCH OBJECT ID>?page=2&object_results=creation_failed \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "default_carrier_account": "078870331023437cb917f5187429b093",
  • "default_servicelevel_token": "usps_priority",
  • "label_filetype": "PDF_4x6",
  • "metadata": "BATCH #1",
  • "batch_shipments": {
    },
  • "label_url": [
    ],
  • "object_created": "2016-01-04T00:15:44.394Z",
  • "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  • "object_owner": "shippo@shippo.com",
  • "object_results": {
    },
  • "object_updated": "2016-01-04T00:48:13.841Z",
  • "status": "VALID",
  • "test": false
}

Add shipments to a batch

Adds batch shipments to an existing batch.

SecurityAPIKeyHeader
Request
path Parameters
BatchId
required
string

Object ID of the batch

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required

Array of shipments to add to the batch

Array
carrier_account
string

Object ID of the carrier account to be used for this shipment (will override batch default)

metadata
string <= 100 characters

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

servicelevel_token
string

A token that sets the shipping method for the batch, overriding the batch default. Servicelevel tokens can be found in this list or at this endpoint.

required
object (ShipmentCreateRequest)
Responses
200
400
post/batches/{BatchId}/add_shipments
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
{
  • "default_carrier_account": "078870331023437cb917f5187429b093",
  • "default_servicelevel_token": "usps_priority",
  • "label_filetype": "PDF_4x6",
  • "metadata": "BATCH #1",
  • "batch_shipments": {
    },
  • "label_url": [
    ],
  • "object_created": "2016-01-04T00:15:44.394Z",
  • "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  • "object_owner": "shippo@shippo.com",
  • "object_results": {
    },
  • "object_updated": "2016-01-04T00:48:13.841Z",
  • "status": "VALID",
  • "test": false
}

Purchase a batch

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

SecurityAPIKeyHeader
Request
path Parameters
BatchId
required
string

Object ID of the batch

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
202
400
post/batches/{BatchId}/purchase
Request samples 
curl -X POST https://api.goshippo.com/batches/<BATCH OBJECT ID>/purchase \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "default_carrier_account": "078870331023437cb917f5187429b093",
  • "default_servicelevel_token": "usps_priority",
  • "label_filetype": "PDF_4x6",
  • "metadata": "BATCH #1",
  • "batch_shipments": {
    },
  • "label_url": [
    ],
  • "object_created": "2016-01-04T00:15:44.394Z",
  • "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  • "object_owner": "shippo@shippo.com",
  • "object_results": {
    },
  • "object_updated": "2016-01-04T00:48:13.841Z",
  • "status": "VALID",
  • "test": false
}

Remove shipments from a batch

Removes shipments from an existing batch shipment.

SecurityAPIKeyHeader
Request
path Parameters
BatchId
required
string

Object ID of the batch

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required

Array of shipments object ids to remove from the batch

Array
string
Responses
200
400
post/batches/{BatchId}/remove_shipments
Request samples
application/json
[
  • "string"
]
Response samples
application/json
{
  • "default_carrier_account": "078870331023437cb917f5187429b093",
  • "default_servicelevel_token": "usps_priority",
  • "label_filetype": "PDF_4x6",
  • "metadata": "BATCH #1",
  • "batch_shipments": {
    },
  • "label_url": [
    ],
  • "object_created": "2016-01-04T00:15:44.394Z",
  • "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  • "object_owner": "shippo@shippo.com",
  • "object_results": {
    },
  • "object_updated": "2016-01-04T00:48:13.841Z",
  • "status": "VALID",
  • "test": false
}

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.

A tracking status of a package is an indication of current location of a package in the supply chain. For example, sorting, warehousing, or out for delivery. Use the tracking status object to track the location of your shipments.

When using your Test token for tracking, you need 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.

object (TrackingStatusFromLocation)

The sender address with city, state, zip and country information.

object (TrackingStatusToLocation)

The recipient address with city, state, zip and country information.

carrier
required
string

Name of the carrier of the shipment to track. See Carriers.

eta
string <date-time>

The estimated time of arrival according to the carrier, this might be updated by carriers during the life of the shipment.

messages
required
Array of strings
metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

original_eta
string <date-time>

The estimated time of arrival according to the carrier at the time the shipment first entered the system.

object (ServiceLevelWithParent)

Contains details regarding the service level for the given rate.

required
Array of objects (TrackingStatus)

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.

tracking_number
required
string

Tracking number to track.

object (TrackingStatus)

The latest tracking information of this shipment.

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.

{
  • "address_from": {
    },
  • "address_to": {
    },
  • "carrier": "usps",
  • "eta": "2019-08-24T14:15:22Z",
  • "messages": [
    ],
  • "metadata": "Order 000123",
  • "original_eta": "2021-07-23T00:00:00Z",
  • "servicelevel": {
    },
  • "tracking_history": [
    ],
  • "tracking_number": "9205590164917312751089",
  • "tracking_status": {
    },
  • "transaction": "string"
}

Register a tracking webhook

Registers a webhook that will send HTTP notifications to you when the status of your tracked package changes. For more details on creating a webhook, see our guides on Webhooks and Tracking.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required
carrier
required
string

Name of the carrier of the shipment to track.

metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

tracking_number
required
string

Tracking number to track.

Responses
200
400
post/tracks
Request samples
application/json
{
  • "carrier": "usps",
  • "metadata": "Order 000123",
  • "tracking_number": "9205590164917312751089"
}
Response samples
application/json
{
  • "address_from": {
    },
  • "address_to": {
    },
  • "carrier": "usps",
  • "eta": "2019-08-24T14:15:22Z",
  • "messages": [
    ],
  • "metadata": "Order 000123",
  • "original_eta": "2021-07-23T00:00:00Z",
  • "servicelevel": {
    },
  • "tracking_history": [
    ],
  • "tracking_number": "9205590164917312751089",
  • "tracking_status": {
    },
  • "transaction": "string"
}

Get a tracking status

Returns the tracking status of a shipment using a carrier name and a tracking number.

SecurityAPIKeyHeader
Request
path Parameters
TrackingNumber
required
string

Tracking number

Carrier
required
string

Name of the carrier

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/tracks/{Carrier}/{TrackingNumber}
Request samples 
curl https://api.goshippo.com/tracks/usps/9205590164917312751089 \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "address_from": {
    },
  • "address_to": {
    },
  • "carrier": "usps",
  • "eta": "2019-08-24T14:15:22Z",
  • "messages": [
    ],
  • "metadata": "Order 000123",
  • "original_eta": "2021-07-23T00:00:00Z",
  • "servicelevel": {
    },
  • "tracking_history": [
    ],
  • "tracking_number": "9205590164917312751089",
  • "tracking_status": {
    },
  • "transaction": "string"
}

Webhooks

Webhooks are a way for Shippo to notify your application when a specific event occurs. For example, when a label is purchased or when a shipment tracking status has changed. You can use webhooks to trigger actions in your application, such as sending an email or updating a database.

event
required
string

Type of event that triggers the webhook.

url
required
string

URL webhook events are sent to.

active
boolean

Determines whether the webhook is active or not.

is_test
boolean

Determines whether the webhook is a test webhook or not.

object_created
string <date-time>

Timestamp of the creation of the webhook.

object_id
string

Unique identifier of the webhook. This can be used to retrieve or delete the webhook.

object_updated
string <date-time>

Timestamp of the last update of the webhook.

object_owner
string

Username of the user who created the webhook.

{
  • "event": "track_updated",
  • "url": "https://example.com/shippo-webhook",
  • "active": true,
  • "is_test": false,
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "string",
  • "object_updated": "2019-08-24T14:15:22Z",
  • "object_owner": "string"
}

Webhook Payload

The payload is the body of the POST request Shippo sends to the URL specified at the time of webhook registration.

event
string (WebhookEventTypeEnum)

Type of event that triggered the webhook.

test
boolean

Determines whether the webhook is a test webhook or not.

object (Track)
{
  • "event": "track_updated",
  • "test": true,
  • "data": {
    }
}

Create a new webhook

Creates a new webhook to send notifications to a URL when a specific event occurs.

SecurityAPIKeyHeader
Request
Request Body schema: application/json
required
event
required
string

Type of event that triggers the webhook.

Enum: "transaction_created" "transaction_updated" "track_updated" "batch_created" "batch_purchased" "all"
url
required
string

URL webhook events are sent to.

active
boolean

Determines whether the webhook is active or not.

is_test
boolean

Determines whether the webhook is a test webhook or not.

Responses
201

Webhook created successfully

post/webhooks
Request samples
application/json
{}
Response samples
application/json
{
  • "event": "track_updated",
  • "url": "https://example.com/shippo-webhook",
  • "active": true,
  • "is_test": false,
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "string",
  • "object_updated": "2019-08-24T14:15:22Z",
  • "object_owner": "string"
}

List all webhooks

Returns a list of all webhooks you have created.

SecurityAPIKeyHeader
Responses
200

List of webhooks

get/webhooks
Request samples 
import shippo

s = shippo.Shippo(
    api_key_header='ShippoToken <API_TOKEN>',
    shippo_api_version='2018-02-08',
)


res = s.webhooks.list_webhooks()

if res is not None:
    # handle response
    pass
Response samples
application/json
{
  • "next": "baseurl?page=3&results=10",
  • "previous": "baseurl?page=1&results=10",
  • "count": 0,
  • "results": [
    ]
}

Retrieve a specific webhook

Returns the details of a specific webhook using the webhook object ID.

SecurityAPIKeyHeader
Request
path Parameters
webhookId
required
string

Object ID of the webhook to retrieve

Responses
200

Webhook details

get/webhooks/{webhookId}
Request samples 
import shippo

s = shippo.Shippo(
    api_key_header='ShippoToken <API_TOKEN>',
    shippo_api_version='2018-02-08',
)


res = s.webhooks.get_webhook(webhook_id='<id>')

if res is not None:
    # handle response
    pass
Response samples
application/json
{
  • "event": "track_updated",
  • "url": "https://example.com/shippo-webhook",
  • "active": true,
  • "is_test": false,
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "string",
  • "object_updated": "2019-08-24T14:15:22Z",
  • "object_owner": "string"
}

Update an existing webhook

Updates an existing webhook using the webhook object ID.

SecurityAPIKeyHeader
Request
path Parameters
webhookId
required
string

Object ID of the webhook to retrieve

Request Body schema: application/json
required
event
required
string

Type of event that triggers the webhook.

Enum: "transaction_created" "transaction_updated" "track_updated" "batch_created" "batch_purchased" "all"
url
required
string

URL webhook events are sent to.

active
boolean

Determines whether the webhook is active or not.

is_test
boolean

Determines whether the webhook is a test webhook or not.

Responses
200

Webhook updated successfully

put/webhooks/{webhookId}
Request samples
application/json
{}
Response samples
application/json
{
  • "event": "track_updated",
  • "url": "https://example.com/shippo-webhook",
  • "active": true,
  • "is_test": false,
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "string",
  • "object_updated": "2019-08-24T14:15:22Z",
  • "object_owner": "string"
}

Delete a specific webhook

Deletes a specific webhook using the webhook object ID.

SecurityAPIKeyHeader
Request
path Parameters
webhookId
required
string

Object ID of the webhook to delete

Responses
204

Webhook deleted successfully

delete/webhooks/{webhookId}
Request samples 
import shippo

s = shippo.Shippo(
    api_key_header='ShippoToken <API_TOKEN>',
    shippo_api_version='2018-02-08',
)


s.webhooks.delete_webhook(webhook_id='<id>')

# Use the SDK ...

Customs Items

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

description
required
string

Text description of your item.

eccn_ear99
string

Export Control Classification Number, required on some exports from the United States.

mass_unit
required
string (WeightUnitEnum)

The unit used for weight.

Enum: "g" "kg" "lb" "oz"
metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

net_weight
required
string

Total weight of this item, i.e. quantity * weight per item.

origin_country
required
string

Country of origin of the item. Example: US or DE. All accepted values can be found on the Official ISO Website.

quantity
required
integer <int64>

Quantity of this item in the shipment you send. Must be greater than 0.

sku_code
string

SKU code of the item, which is required by some carriers.

hs_code
string

HS code of the item, which is required by some carriers. If tariff_number is not provided, hs_code will be used. If both hs_code and tariff_number are provided, tariff_number will be used. 50 character limit.

tariff_number
string

The tariff number of the item. If tariff_number is not provided, hs_code will be used. If both hs_code and tariff_number are provided, tariff_number will be used. 12 character limit.

value_amount
required
string

Total value of this item, i.e. quantity * value per item.

value_currency
required
string

Currency used for value_amount. The official ISO 4217 currency codes are used, e.g. USD or EUR.

object_created
string <date-time>

Date and time of object creation.

object_id
string

Unique identifier of the given object.

object_owner
string

Username of the user who created the object.

object_state
string (ObjectStateEnum)

Indicates the validity of the enclosing object

Enum: "VALID" "INVALID"
object_updated
string <date-time>

Date and time of last object update.

test
boolean

Indicates whether the object has been created in test mode.

{
  • "description": "T-Shirt",
  • "eccn_ear99": "string",
  • "mass_unit": "lb",
  • "metadata": "Order ID \"123454\"",
  • "net_weight": "5",
  • "origin_country": "string",
  • "quantity": 20,
  • "sku_code": "HM-123",
  • "hs_code": "0901.21",
  • "tariff_number": "string",
  • "value_amount": "200",
  • "value_currency": "USD",
  • "object_created": "2014-07-17T00:49:20.631Z",
  • "object_id": "d799c2679e644279b59fe661ac8fa488",
  • "object_owner": "shippotle@shippo.com",
  • "object_state": "VALID",
  • "object_updated": "2014-07-17T00:49:20.631Z",
  • "test": true
}

List all customs items

Returns a list all customs items objects.

SecurityAPIKeyHeader
Request
query Parameters
page
integer <int64>
Default: 1

The page number you want to select

results
integer <int64> <= 100
Default: 25

The number of results to return per page (max 100)

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/customs/items
Request samples 
curl  https://api.goshippo.com/customs/items/ \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "next": "baseurl?page=3&results=10",
  • "previous": "baseurl?page=1&results=10",
  • "results": [
    ]
}

Create a new customs item

Creates a new customs item object.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required

CustomsItem details.

description
required
string

Text description of your item.

eccn_ear99
string

Export Control Classification Number, required on some exports from the United States.

mass_unit
required
string (WeightUnitEnum)

The unit used for weight.

Enum: "g" "kg" "lb" "oz"
metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

net_weight
required
string

Total weight of this item, i.e. quantity * weight per item.

origin_country
required
string

Country of origin of the item. Example: US or DE. All accepted values can be found on the Official ISO Website.

quantity
required
integer <int64>

Quantity of this item in the shipment you send. Must be greater than 0.

sku_code
string

SKU code of the item, which is required by some carriers.

hs_code
string

HS code of the item, which is required by some carriers. If tariff_number is not provided, hs_code will be used. If both hs_code and tariff_number are provided, tariff_number will be used. 50 character limit.

tariff_number
string

The tariff number of the item. If tariff_number is not provided, hs_code will be used. If both hs_code and tariff_number are provided, tariff_number will be used. 12 character limit.

value_amount
required
string

Total value of this item, i.e. quantity * value per item.

value_currency
required
string

Currency used for value_amount. The official ISO 4217 currency codes are used, e.g. USD or EUR.

Responses
201
400
post/customs/items
Request samples
application/json
{
  • "description": "T-Shirt",
  • "eccn_ear99": "string",
  • "mass_unit": "lb",
  • "metadata": "Order ID \"123454\"",
  • "net_weight": "5",
  • "origin_country": "string",
  • "quantity": 20,
  • "sku_code": "HM-123",
  • "hs_code": "0901.21",
  • "tariff_number": "string",
  • "value_amount": "200",
  • "value_currency": "USD"
}
Response samples
application/json
{
  • "description": "T-Shirt",
  • "eccn_ear99": "string",
  • "mass_unit": "lb",
  • "metadata": "Order ID \"123454\"",
  • "net_weight": "5",
  • "origin_country": "string",
  • "quantity": 20,
  • "sku_code": "HM-123",
  • "hs_code": "0901.21",
  • "tariff_number": "string",
  • "value_amount": "200",
  • "value_currency": "USD",
  • "object_created": "2014-07-17T00:49:20.631Z",
  • "object_id": "d799c2679e644279b59fe661ac8fa488",
  • "object_owner": "shippotle@shippo.com",
  • "object_state": "VALID",
  • "object_updated": "2014-07-17T00:49:20.631Z",
  • "test": true
}

Retrieve a customs item

Returns an existing customs item using an object ID

SecurityAPIKeyHeader
Request
path Parameters
CustomsItemId
required
string

Object ID of the customs item

query Parameters
page
integer <int64>
Default: 1

The page number you want to select

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/customs/items/{CustomsItemId}
Request samples 
curl  https://api.goshippo.com/customs/items/55358464c7b740aca199b395536981bd \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "description": "T-Shirt",
  • "eccn_ear99": "string",
  • "mass_unit": "lb",
  • "metadata": "Order ID \"123454\"",
  • "net_weight": "5",
  • "origin_country": "string",
  • "quantity": 20,
  • "sku_code": "HM-123",
  • "hs_code": "0901.21",
  • "tariff_number": "string",
  • "value_amount": "200",
  • "value_currency": "USD",
  • "object_created": "2014-07-17T00:49:20.631Z",
  • "object_id": "d799c2679e644279b59fe661ac8fa488",
  • "object_owner": "shippotle@shippo.com",
  • "object_state": "VALID",
  • "object_updated": "2014-07-17T00:49:20.631Z",
  • "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.

aes_itn
string

required if eel_pfc is AES_ITN
AES / ITN reference of the shipment.

b13a_filing_option
string

B13A Option details are obtained by filing a B13A Canada Export Declaration via the Canadian Export Reporting System (CERS). More information on reporting commercial exports from Canada. Allowed values available here

b13a_number
string

must be provided if and only if b13a_filing_option is provided
Represents:
the Proof of Report (POR) Number when b13a_filing_option is FILED_ELECTRONICALLY;
the Summary ID Number when b13a_filing_option is SUMMARY_REPORTING;
or the Exemption Number when b13a_filing_option is NOT_REQUIRED.

certificate
string

Certificate reference of the shipment.

certify
required
boolean

Expresses that the certify_signer has provided all information of this customs declaration truthfully.

certify_signer
required
string

Name of the person who created the customs declaration and is responsible for the validity of all information provided.

commercial_invoice
boolean
contents_explanation
string

required if contents_type is OTHER
Explanation of the type of goods of the shipment.

disclaimer
string

Disclaimer for the shipment and customs information that have been provided.

object

Specifies who will pay the duties for the shipment. Only accepted for FedEx shipments.

object (CustomsExporterIdentification)

Additional exporter identification that may be required to ship in certain countries

exporter_reference
string

Exporter reference of an export shipment.

importer_reference
string

Importer reference of an import shipment.

is_vat_collected
boolean

Indicates whether the shipment's destination VAT has been collected. May be required for some destinations.

invoice
string

Invoice reference of the shipment.

license
string

License reference of the shipment.

metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

notes
string

Additional notes to be included in the customs declaration.

address_importer
string

Object ID of the Importer address.

contents_type
required
string (CustomsDeclarationContentsType)

Type of goods of the shipment.
Allowed values available here

eel_pfc
string (CustomsDeclarationEelPfc)

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. Allowed values available here

incoterm
string (CustomsDeclarationIncoterm)

The incoterm reference of the shipment. FCA is available for DHL Express and FedEx only. eDAP is available for DPD UK only. DAP is available for DHL Express and DPD UK. If expecting DAP for other carriers, please use DDU. Allowed values available here

object (CustomsInvoicedCharges)

Additional invoiced charges to be shown on the Customs Declaration Commercial Invoice.

items
required
Array of strings

Distinct Parcel content items as Customs Items object_ids.

non_delivery_option
required
string (CustomsDeclarationNonDeliveryOption)

Indicates how the carrier should proceed in case the shipment can't be delivered. Allowed values available here

object_created
string <date-time>

Date and time of object creation.

object_id
string

Unique identifier of the given object.

object_owner
string

Username of the user who created the object.

object_state
string (ObjectStateEnum)

Indicates the validity of the enclosing object

Enum: "VALID" "INVALID"
object_updated
string <date-time>

Date and time of last object update.

test
boolean

Indicates whether the object has been created in test mode.

{
  • "aes_itn": "string",
  • "b13a_filing_option": "FILED_ELECTRONICALLY",
  • "b13a_number": "string",
  • "certificate": "string",
  • "certify": true,
  • "certify_signer": "Shawn Ippotle",
  • "commercial_invoice": true,
  • "contents_explanation": "T-Shirt purchase",
  • "disclaimer": "string",
  • "duties_payor": {
    },
  • "exporter_identification": {
    },
  • "exporter_reference": "string",
  • "importer_reference": "string",
  • "is_vat_collected": true,
  • "invoice": "#123123",
  • "license": "string",
  • "metadata": "Order ID #123123",
  • "notes": "string",
  • "address_importer": "257ba08436604d2aaf069caafe7acb2a",
  • "contents_type": "MERCHANDISE",
  • "eel_pfc": "NOEEI_30_37_a",
  • "incoterm": "DDP",
  • "invoiced_charges": {
    },
  • "items": [
    ],
  • "non_delivery_option": "RETURN",
  • "object_created": "2014-07-17T01:01:08.306Z",
  • "object_id": "e2197a54da9d470480f4f8796cc419cb",
  • "object_owner": "shippotle@shippo.com",
  • "object_state": "VALID",
  • "object_updated": "2014-07-17T01:01:08.306Z",
  • "test": true
}

List all customs declarations

Returns a a list of all customs declaration objects

SecurityAPIKeyHeader
Request
query Parameters
page
integer <int64>
Default: 1

The page number you want to select

results
integer <int64> <= 100
Default: 5

The number of results to return per page (max 100, default 5)

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/customs/declarations
Request samples 
curl https://api.goshippo.com/customs/declarations/ \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "next": "baseurl?page=3&results=10",
  • "previous": "baseurl?page=1&results=10",
  • "results": [
    ]
}

Create a new customs declaration

Creates a new customs declaration object

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required

CustomsDeclaration details.

aes_itn
string

required if eel_pfc is AES_ITN
AES / ITN reference of the shipment.

b13a_filing_option
string (CustomsDeclarationB13AFilingOptionEnum)

B13A Option details are obtained by filing a B13A Canada Export Declaration via the Canadian Export Reporting System (CERS). More information on reporting commercial exports from Canada. Allowed values available here

Enum: "FILED_ELECTRONICALLY" "SUMMARY_REPORTING" "NOT_REQUIRED"
b13a_number
string

must be provided if and only if b13a_filing_option is provided
Represents:
the Proof of Report (POR) Number when b13a_filing_option is FILED_ELECTRONICALLY;
the Summary ID Number when b13a_filing_option is SUMMARY_REPORTING;
or the Exemption Number when b13a_filing_option is NOT_REQUIRED.

certificate
string

Certificate reference of the shipment.

certify
required
boolean

Expresses that the certify_signer has provided all information of this customs declaration truthfully.

certify_signer
required
string

Name of the person who created the customs declaration and is responsible for the validity of all information provided.

commercial_invoice
boolean
contents_explanation
string

required if contents_type is OTHER
Explanation of the type of goods of the shipment.

disclaimer
string

Disclaimer for the shipment and customs information that have been provided.

object

Specifies who will pay the duties for the shipment. Only accepted for FedEx shipments.

object (CustomsExporterIdentification)

Additional exporter identification that may be required to ship in certain countries

exporter_reference
string

Exporter reference of an export shipment.

importer_reference
string

Importer reference of an import shipment.

is_vat_collected
boolean

Indicates whether the shipment's destination VAT has been collected. May be required for some destinations.

invoice
string

Invoice reference of the shipment.

license
string

License reference of the shipment.

metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

notes
string

Additional notes to be included in the customs declaration.

object (AddressImporter)

Object that represents the address of the importer

contents_type
required
string (CustomsDeclarationContentsTypeEnum)

Type of goods of the shipment.
Allowed values available here

Enum: "DOCUMENTS" "GIFT" "SAMPLE" "MERCHANDISE" "HUMANITARIAN_DONATION" "RETURN_MERCHANDISE" "OTHER"
eel_pfc
string (CustomsDeclarationEelPfcEnum)

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. Allowed values available here

Enum: "NOEEI_30_37_a" "NOEEI_30_37_h" "NOEEI_30_37_f" "NOEEI_30_36" "AES_ITN"
incoterm
string (CustomsDeclarationIncotermEnum)

The incoterm reference of the shipment. FCA is available for DHL Express and FedEx only. eDAP is available for DPD UK only. DAP is available for DHL Express and DPD UK. If expecting DAP for other carriers, please use DDU. Allowed values available here

Enum: "DDP" "DDU" "FCA" "DAP" "eDAP"
required
Array of objects (CustomsItemCreateRequest)
non_delivery_option
required
string (CustomsDeclarationNonDeliveryOptionEnum)

Indicates how the carrier should proceed in case the shipment can't be delivered. Allowed values available here

Enum: "ABANDON" "RETURN"
test
boolean
Responses
201
400
post/customs/declarations
Request samples
application/json
{
  • "aes_itn": "string",
  • "b13a_filing_option": "FILED_ELECTRONICALLY",
  • "b13a_number": "string",
  • "certificate": "string",
  • "certify": true,
  • "certify_signer": "Shawn Ippotle",
  • "commercial_invoice": true,
  • "contents_explanation": "T-Shirt purchase",
  • "disclaimer": "string",
  • "duties_payor": {
    },
  • "exporter_identification": {
    },
  • "exporter_reference": "string",
  • "importer_reference": "string",
  • "is_vat_collected": true,
  • "invoice": "#123123",
  • "license": "string",
  • "metadata": "Order ID #123123",
  • "notes": "string",
  • "address_importer": {
    },
  • "contents_type": "DOCUMENTS",
  • "eel_pfc": "NOEEI_30_37_a",
  • "incoterm": "DDP",
  • "items": [
    ],
  • "non_delivery_option": "ABANDON",
  • "test": true
}
Response samples
application/json
{
  • "aes_itn": "string",
  • "b13a_filing_option": "FILED_ELECTRONICALLY",
  • "b13a_number": "string",
  • "certificate": "string",
  • "certify": true,
  • "certify_signer": "Shawn Ippotle",
  • "commercial_invoice": true,
  • "contents_explanation": "T-Shirt purchase",
  • "disclaimer": "string",
  • "duties_payor": {
    },
  • "exporter_identification": {
    },
  • "exporter_reference": "string",
  • "importer_reference": "string",
  • "is_vat_collected": true,
  • "invoice": "#123123",
  • "license": "string",
  • "metadata": "Order ID #123123",
  • "notes": "string",
  • "address_importer": "257ba08436604d2aaf069caafe7acb2a",
  • "contents_type": "MERCHANDISE",
  • "eel_pfc": "NOEEI_30_37_a",
  • "incoterm": "DDP",
  • "invoiced_charges": {
    },
  • "items": [
    ],
  • "non_delivery_option": "RETURN",
  • "object_created": "2014-07-17T01:01:08.306Z",
  • "object_id": "e2197a54da9d470480f4f8796cc419cb",
  • "object_owner": "shippotle@shippo.com",
  • "object_state": "VALID",
  • "object_updated": "2014-07-17T01:01:08.306Z",
  • "test": true
}

Retrieve a customs declaration

Returns an existing customs declaration using an object ID

SecurityAPIKeyHeader
Request
path Parameters
CustomsDeclarationId
required
string

Object ID of the customs declaration

query Parameters
page
integer <int64>
Default: 1

The page number you want to select

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/customs/declarations/{CustomsDeclarationId}
Request samples 
curl https://api.goshippo.com/customs/declarations/e2197a54da9d470480f4f8796cc419cb \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "aes_itn": "string",
  • "b13a_filing_option": "FILED_ELECTRONICALLY",
  • "b13a_number": "string",
  • "certificate": "string",
  • "certify": true,
  • "certify_signer": "Shawn Ippotle",
  • "commercial_invoice": true,
  • "contents_explanation": "T-Shirt purchase",
  • "disclaimer": "string",
  • "duties_payor": {
    },
  • "exporter_identification": {
    },
  • "exporter_reference": "string",
  • "importer_reference": "string",
  • "is_vat_collected": true,
  • "invoice": "#123123",
  • "license": "string",
  • "metadata": "Order ID #123123",
  • "notes": "string",
  • "address_importer": "257ba08436604d2aaf069caafe7acb2a",
  • "contents_type": "MERCHANDISE",
  • "eel_pfc": "NOEEI_30_37_a",
  • "incoterm": "DDP",
  • "invoiced_charges": {
    },
  • "items": [
    ],
  • "non_delivery_option": "RETURN",
  • "object_created": "2014-07-17T01:01:08.306Z",
  • "object_id": "e2197a54da9d470480f4f8796cc419cb",
  • "object_owner": "shippotle@shippo.com",
  • "object_state": "VALID",
  • "object_updated": "2014-07-17T01:01:08.306Z",
  • "test": true
}

Carrier Accounts

Carriers are the companies who deliver your package. Shippo uses Carrier account objects as credentials to retrieve shipping rates and purchase labels from shipping Carriers.

account_id
required
string

Unique identifier of the account. Please check the carrier accounts tutorial page for the account_id per carrier.
To protect account information, this field will be masked in any API response.

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.

carrier
required
string

Carrier token, see Carriers
Please check the carrier accounts tutorial page for all supported carriers.

Account parameters (object) or FedEx account parameters (object) or UPS account parameters (object)
carrier_name
any

Carrier name, see Carriers

is_shippo_account
boolean
metadata
string
object_id
string

Unique identifier of the carrier account object.

object_owner
string

Username of the user who created the carrier account object.

Array of objects (CarrierAccountServiceLevel)
test
boolean

Indicates whether the object has been created in test mode.

{
  • "account_id": "****",
  • "active": true,
  • "carrier": "usps",
  • "parameters": { },
  • "carrier_name": "USPS",
  • "is_shippo_account": false,
  • "metadata": "string",
  • "object_id": "6aa34d5f6865448fbb1ee93636e98999",
  • "object_owner": "bob+22@gmail.com",
  • "service_levels": [
    ],
  • "test": false
}

List all carrier accounts

Returns a list of all carrier accounts connected to your Shippo account. These carrier accounts include both Shippo carrier accounts and your own carrier accounts that you have connected to your Shippo account.

Additionally, you can get information about the service levels associated with each carrier account by passing in the ?service_levels=true query parameter.
Using it appends the property service_levels to each carrier account.
By default, if the query parameter is omitted, the service_levels property will not be included in the response.

SecurityAPIKeyHeader
Request
query Parameters
service_levels
boolean

Appends the property service_levels to each returned carrier account

carrier
string (CarriersEnum)

Filter the response by the specified carrier

Enum: "airterra" "apc_postal" "apg" "aramex" "asendia_us" "australia_post" "axlehire" "better_trucks" "borderguru" "boxberry" "bring" "canada_post" "cdl" "chronopost" "collect_plus" "correios_br" "correos_espana" "colissimo" "deutsche_post" "dhl_benelux" "dhl_ecommerce" "dhl_express" "dhl_germany_c2c" "dhl_germany" "dpd_de" "dpd_uk" "estafeta" "fastway_australia" "fedex" "globegistics" "gls_us" "gophr" "gso" "hermes_germany_b2c" "hermes_uk" "hongkong_post" "lasership" "lso" "mondial_relay" "new_zealand_post" "nippon_express" "ontrac" "parcelforce" "passport" "pcf" "poste_italiane" "posti" "purolator" "royal_mail" "rr_donnelley" "russian_post" "sendle" "skypostal" "stuart" "swyft" "uds" "ups" "usps" "veho"
account_id
string

Filter the response by the specified carrier account Id

page
integer <int64>
Default: 1

The page number you want to select

results
integer <int64> <= 100
Default: 5

The number of results to return per page (max 100, default 5)

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/carrier_accounts
Request samples 
curl https://api.goshippo.com/carrier_accounts?service_levels=true \
 -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "next": "baseurl?page=3&results=10",
  • "previous": "baseurl?page=1&results=10",
  • "results": [
    ]
}

Create a new carrier account

Creates a new carrier account or connects an existing carrier account to the Shippo account.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required

Examples.

account_id
required
string
active
boolean
carrier
required
string
metadata
string
required
Account parameters (object) or FedEx account parameters (object) or UPS account parameters (object)
test
boolean
Responses
201
400
post/carrier_accounts
Request samples
application/json
{
  • "account_id": 321123,
  • "carrier": "fedex",
  • "metadata": "FedEx Account",
  • "parameters": {
    },
  • "test": false
}
Response samples
application/json
{
  • "account_id": "****",
  • "active": true,
  • "carrier": "usps",
  • "parameters": { },
  • "carrier_name": "USPS",
  • "is_shippo_account": false,
  • "metadata": "string",
  • "object_id": "6aa34d5f6865448fbb1ee93636e98999",
  • "object_owner": "bob+22@gmail.com",
  • "service_levels": [
    ],
  • "test": false
}

Retrieve a carrier account

Returns an existing carrier account using an object ID.

SecurityAPIKeyHeader
Request
path Parameters
CarrierAccountId
required
string

Object ID of the carrier account

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/carrier_accounts/{CarrierAccountId}
Request samples 
curl https://api.goshippo.com/carrier_accounts/b741b99f95e841639b54272834bc478c \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "account_id": "****",
  • "active": true,
  • "carrier": "usps",
  • "parameters": { },
  • "carrier_name": "USPS",
  • "is_shippo_account": false,
  • "metadata": "string",
  • "object_id": "6aa34d5f6865448fbb1ee93636e98999",
  • "object_owner": "bob+22@gmail.com",
  • "service_levels": [
    ],
  • "test": false
}

Update a carrier account

Updates an existing carrier account object. The account_id and carrier can't be updated. This is because they form the unique identifier together.

SecurityAPIKeyHeader
Request
path Parameters
CarrierAccountId
required
string

Object ID of the carrier account

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json

Examples.

account_id
required
string

Unique identifier of the account. Please check the carrier accounts tutorial page for the account_id per carrier.
To protect account information, this field will be masked in any API response.

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.

carrier
required
string

Carrier token, see Carriers
Please check the carrier accounts tutorial page for all supported carriers.

Account parameters (object) or FedEx account parameters (object) or UPS account parameters (object)
Responses
200
400
put/carrier_accounts/{CarrierAccountId}
Request samples
application/json
{
  • "account_id": 123356,
  • "active": true,
  • "carrier": "ups",
  • "parameters": { }
}
Response samples
application/json
{
  • "account_id": "****",
  • "active": true,
  • "carrier": "usps",
  • "parameters": { },
  • "carrier_name": "USPS",
  • "is_shippo_account": false,
  • "metadata": "string",
  • "object_id": "6aa34d5f6865448fbb1ee93636e98999",
  • "object_owner": "bob+22@gmail.com",
  • "service_levels": [
    ],
  • "test": false
}

Connect an existing carrier account using OAuth 2.0

Used by client applications to setup or reconnect an existing carrier account with carriers that support OAuth 2.0

SecurityAPIKeyHeader
Request
path Parameters
CarrierAccountObjectId
required
string

The carrier account ID (UUID) to start a signin process.

query Parameters
redirect_uri
required
string <uri>

Callback URL. The URL that tells the authorization server where to send the user back to after they approve the request.

state
string

A random string generated by the consuming application and included in the request to prevent CSRF attacks. The consuming application checks that the same value is returned after the user authorizes Shippo.

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
302

Redirects the browser to the carrier login page, with the needed parameters

400

Invalid parameters provided by the user

401

Invalid ShippoToken or unsupported carrier account provided by the user

404

Invalid carrier account provided by the user

get/carrier_accounts/{CarrierAccountObjectId}/signin/initiate
Request samples 
curl "https://api.goshippo.com/carrier_accounts/2ccf5af209bb484cb20190d9cadbb61c/signin/initiate?redirect_uri=https://client.example.com/cb&state=SplxlOBeZQQYbYS6WxSbIA" \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "title": "Missing required parameter",
  • "detail": "redirect_uri"
}

Add a Shippo carrier account

Adds a Shippo carrier account

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required

The body of the request.

carrier
required
string
Value: "canada_post"
required
object (CarrierAccountCanadaPostCreateParameters)
Responses
201
400
post/carrier_accounts/register/new
Request samples
application/json
{
  • "carrier": "canada_post",
  • "parameters": {
    }
}
Response samples
application/json
{
  • "account_id": "****",
  • "active": true,
  • "carrier": "usps",
  • "parameters": { },
  • "carrier_name": "USPS",
  • "is_shippo_account": false,
  • "metadata": "string",
  • "object_id": "6aa34d5f6865448fbb1ee93636e98999",
  • "object_owner": "bob+22@gmail.com",
  • "service_levels": [
    ],
  • "test": false
}

Get Carrier Registration status

Returns the registration status for the given account for the given carrier

SecurityAPIKeyHeader
Request
query Parameters
carrier
required
string

filter by specific carrier

Enum: "ups" "usps" "canada_post"
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/carrier_accounts/reg-status
Request samples 
import shippo
from shippo.models import operations

s = shippo.Shippo(
    api_key_header='ShippoToken <API_TOKEN>',
    shippo_api_version='2018-02-08',
)


res = s.carrier_accounts.get_registration_status(carrier=operations.Carrier.USPS)

if res is not None:
    # handle response
    pass
Response samples
application/json
{
  • "carrier_account": "99dc410d295b4a168993cc38809cb123",
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_owner": "tom@gmail.com",
  • "object_updated": "2019-08-24T14:15:22Z",
  • "status": "PENDING_TERMS"
}

Manifests

A manifest is a single-page document with a barcode that carriers can scan to accept all packages into transit without the need to scan each item individually. They are close-outs of shipping labels of a certain day. Some carriers require manifests to process the shipments.

carrier_account
required
string

ID of carrier account

shipment_date
required
string

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

transactions
Array of strings

IDs transactions to use. If you set this to null or not send this parameter, Shippo will automatically assign all applicable transactions.

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

documents
required
Array of strings

An array containing the URLs to all returned manifest documents.

errors
Array of strings

An array of codes and messages describing the error that occurred if any.

object_created
required
string <date-time>

Date and time of object creation.

object_id
required
string

Unique identifier of the given object.

object_owner
required
string

Username of the user who created the object.

object_updated
required
string <date-time>

Date and time of last object update.

status
required
string

Indicates the status of the manifest.

Enum: "QUEUED" "SUCCESS" "ERROR"
{}

Manifest Errors

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

generic_carrier_error
string

There is an error from the carrier that requires investigation. Please contact support with the object ID of this response.

carrier_account_invalid_credentials
string

The carrier account contains invalid credentials. Please update your carrier account with valid credentials.

carrier_account_access_denied
string

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
string

For this carrier, all shipments must be manifested on the same day that they are created regardless of shipment date.

manifest_no_transactions
string

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
string

The sender address is missing the zip. Please update the sender address and try again.

address_from_invalid_zip1
string

The sender address contains an invalid zip. Please update the sender address and try again.

address_from_invalid_zip2
string

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
string

The sender address is missing the city. Please update the sender address and try again.

address_from_invalid_city
string

The sender address contains an invalid city. Please update the sender address and try again.

address_from_missing_state
string

The sender address is missing the state. Please update the sender address and try again.

address_from_invalid_state
string

The sender address contains an invalid state. Please update the sender address and try again.

address_from_missing_name
string

The sender address is missing the name. Please update the sender address and try again.

shipment_date_missing
string

The shipment date is missing. Please update the shipment date and try again.

shipment_date_invalid
string

The shipment date is invalid. Please update the shipment date and try again.

{
  • "generic_carrier_error": "string",
  • "carrier_account_invalid_credentials": "string",
  • "carrier_account_access_denied": "string",
  • "manifest_invalid_transactions": "string",
  • "manifest_no_transactions": "string",
  • "address_from_missing_zip": "string",
  • "address_from_invalid_zip1": "string",
  • "address_from_invalid_zip2": "string",
  • "address_from_missing_city": "string",
  • "address_from_invalid_city": "string",
  • "address_from_missing_state": "string",
  • "address_from_invalid_state": "string",
  • "address_from_missing_name": "string",
  • "shipment_date_missing": "string",
  • "shipment_date_invalid": "string"
}

List all manifests

Returns a list of all manifest objects.

SecurityAPIKeyHeader
Request
query Parameters
page
integer <int64>
Default: 1

The page number you want to select

results
integer <int64> <= 100
Default: 5

The number of results to return per page (max 100, default 5)

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/manifests
Request samples 
curl https://api.goshippo.com/manifests/ \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{}

Create a new manifest

Creates a new manifest object.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required

Manifest details and contact info.

carrier_account
required
string

ID of carrier account

shipment_date
required
string

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

transactions
Array of strings

IDs transactions to use. If you set this to null or not send this parameter, Shippo will automatically assign all applicable transactions.

required
AddressCreateRequest (object) or string
async
boolean
Responses
201
400
post/manifests
Request samples
application/json
{
  • "carrier_account": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "shipment_date": "2014-05-16T23:59:59Z",
  • "transactions": [
    ],
  • "address_from": {
    },
  • "async": true
}
Response samples
application/json
{}

Retrieve a manifest

Returns an existing manifest using an object ID.

SecurityAPIKeyHeader
Request
path Parameters
ManifestId
required
string

Object ID of the manifest to update

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/manifests/{ManifestId}
Request samples 
curl https://api.goshippo.com/manifests/0fadebf6f60c4aca95fa01bcc59c79ae \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{}

Pickups

A pickup is when you schedule a carrier to collect a package for delivery. Use Shippo’s pickups endpoint to schedule pickups with USPS and DHL Express for eligible shipments that you have already created.

carrier_account
required
string

The object ID of your USPS or DHL Express carrier account. You can retrieve this from your Rate requests or our Carrier Accounts endpoint.

required
object (Location)

Location where the parcel(s) will be picked up.

metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

requested_end_time
required
string <date-time>

The latest that you requested your parcels to be available for pickup. Expressed in the timezone specified in the response.

requested_start_time
required
string <date-time>

The earliest that you requested your parcels to be ready for pickup. Expressed in the timezone specified in the response.

transactions
required
Array of strings

The transaction(s) object ID(s) for the parcel(s) that need to be picked up.

object_created
string <date-time>

Date and time of Pickup creation.

object_id
string

Unique identifier of the given Pickup object.

object_updated
string <date-time>

Date and time of last Pickup update.

confirmed_start_time
string <datetime>

The earliest that your parcels will be ready for pickup, confirmed by the carrier. Expressed in the timezone specified in the response.

confirmed_end_time
string <datetime>

The latest that your parcels will be available for pickup, confirmed by the carrier. Expressed in the timezone specified in the response.

cancel_by_time
string <datetime>

The latest time to cancel a pickup. Expressed in the timezone specified in the response. To cancel a pickup, you will need to contact the carrier directly. The ability to cancel a pickup through Shippo may be released in future iterations.

status
string

Indicates the status of the pickup.

Enum: "PENDING" "CONFIRMED" "ERROR" "CANCELLED"
confirmation_code
string

Pickup's confirmation code returned by the carrier. To edit or cancel a pickup, you will need to contact USPS or DHL Express directly and provide your confirmation_code.

timezone
string

The pickup time windows will be in the time zone specified here, not UTC.

messages
Array of strings

An array containing strings of any messages generated during validation.

is_test
boolean

Indicates whether the object has been created in test mode.

{
  • "carrier_account": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "location": {
    },
  • "metadata": "string",
  • "requested_end_time": "2019-08-24T14:15:22Z",
  • "requested_start_time": "2019-08-24T14:15:22Z",
  • "transactions": [
    ],
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "string",
  • "object_updated": "2019-08-24T14:15:22Z",
  • "confirmed_start_time": "2020-05-09T12:00:00Z",
  • "confirmed_end_time": "2020-05-09T23:59:59.999Z",
  • "cancel_by_time": "2020-05-09T08:00:00Z",
  • "status": "CONFIRMED",
  • "confirmation_code": "WTC310058750",
  • "timezone": "US/Pacific",
  • "messages": [ ],
  • "is_test": true
}

Create a pickup

Creates a pickup object. This request is for a carrier to come to a specified location to take a package for shipping.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required

Shippo’s pickups endpoint allows you to schedule pickups with USPS and DHL Express for eligible shipments that you have already created.

carrier_account
required
string

The object ID of your USPS or DHL Express carrier account. You can retrieve this from your Rate requests or our Carrier Accounts endpoint.

required
object (Location)

Location where the parcel(s) will be picked up.

metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

requested_end_time
required
string <date-time>

The latest that you requested your parcels to be available for pickup. Expressed in the timezone specified in the response.

requested_start_time
required
string <date-time>

The earliest that you requested your parcels to be ready for pickup. Expressed in the timezone specified in the response.

transactions
required
Array of strings

The transaction(s) object ID(s) for the parcel(s) that need to be picked up.

Responses
201
400
post/pickups
Request samples
application/json
{
  • "carrier_account": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "location": {
    },
  • "metadata": "string",
  • "requested_end_time": "2019-08-24T14:15:22Z",
  • "requested_start_time": "2019-08-24T14:15:22Z",
  • "transactions": [
    ]
}
Response samples
application/json
{
  • "carrier_account": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "location": {
    },
  • "metadata": "string",
  • "requested_end_time": "2019-08-24T14:15:22Z",
  • "requested_start_time": "2019-08-24T14:15:22Z",
  • "transactions": [
    ],
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "string",
  • "object_updated": "2019-08-24T14:15:22Z",
  • "confirmed_start_time": "2020-05-09T12:00:00Z",
  • "confirmed_end_time": "2020-05-09T23:59:59.999Z",
  • "cancel_by_time": "2020-05-09T08:00:00Z",
  • "status": "CONFIRMED",
  • "confirmation_code": "WTC310058750",
  • "timezone": "US/Pacific",
  • "messages": [ ],
  • "is_test": true
}

Orders (beta)

An order is a request from a customer to purchase goods from a merchant. Use the orders object to load orders from your system to the Shippo dashboard. You can use the orders object to create, retrieve, list, and manage orders programmatically. You can also retrieve shipping rates, purchase labels, and track shipments for each order.

currency
string

Required if total_price is provided
Currency of the total_price and total_tax amounts.

notes
string

Custom buyer- or seller-provided notes about the order.

order_number
string

An alphanumeric identifier for the order used by the seller/buyer. This identifier doesn't need to be unique.

order_status
string (OrderStatusEnum)

Current state of the order. See the orders tutorial for the logic of how the status is handled.

Enum: "UNKNOWN" "AWAITPAY" "PAID" "REFUNDED" "CANCELLED" "PARTIALLY_FULFILLED" "SHIPPED"
placed_at
required
string

Date and time when the order was placed. This datetime can be different from the datetime of the order object creation on Shippo.

shipping_cost
string

Amount paid by the buyer for shipping. This amount can be different from the price the seller will actually pay for shipping.

shipping_cost_currency
string

Required if shipping_cost is provided
Currency of the shipping_cost amount.

shipping_method
string

Shipping method (carrier + service or other free text description) chosen by the buyer. This value can be different from the shipping method the seller will actually choose.

subtotal_price
string
total_price
string

Total amount paid by the buyer for this order.

total_tax
string

Total tax amount paid by the buyer for this order.

weight
string

Total weight of the order.

weight_unit
string (WeightUnitEnum)

The unit used for weight.

Enum: "g" "kg" "lb" "oz"
object (AddressFrom)

Address object of the sender / seller. Will be returned expanded by default.

required
object (AddressTo)

Address object of the recipient / buyer. Will be returned expanded by default.

Array of objects (LineItem)

Array of line item objects representing the items in this order. All objects will be returned expanded by default.

object_id
string

Unique identifier of the order object.

object_owner
string

Username of the user who created the object.

shop_app
string (OrderShopAppEnum)

Platform the order was created on and, if applicable, imported from. Orders created via the Shippo API or dashboard will have the value "Shippo".

Enum: "Amazon" "Bigcommerce" "CSV_Import" "eBay" "ePages" "Etsy" "Godaddy" "Magento" "Shippo" "Shopify" "Spreecommerce" "StripeRelay" "Walmart" "Weebly" "WooCommerce"
transactions
Array of objects

Array of transaction objects representing all shipping labels purchased for this order. All objects are returned expanded with a limited number of fields by default.

{
  • "currency": "USD",
  • "notes": "This customer is a VIP",
  • "order_number": "#1068",
  • "order_status": "PAID",
  • "placed_at": "2016-09-23T01:28:12Z",
  • "shipping_cost": "12.83",
  • "shipping_cost_currency": "USD",
  • "shipping_method": "USPS First Class Package",
  • "subtotal_price": "12.1",
  • "total_price": "24.93",
  • "total_tax": "0.0",
  • "weight": "0.4",
  • "weight_unit": "lb",
  • "from_address": {
    },
  • "to_address": {
    },
  • "line_items": [
    ],
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_owner": "shippotle@shippo.com",
  • "shop_app": "Shippo",
  • "transactions": [
    ]
}

Line Item


Line Items, and their corresponding abstract Products and Variants, might be exposed as a separate resource in the future. Currently it's a nested object within the order resource.

A line item is an individual object in an order. For example, if your order contains a t-shirt, shorts, and a jacket, each item is represented by a line item.
currency
string

Currency of the total_price amount.

manufacture_country
string

Country the item was manufactured in. In the Shippo dashboard, this value will be used ot pre-fill the customs declaration when creating a label for this order.

max_delivery_time
string <date-time>

The date and time this item needs to be delivered by, i.e. by when the carrier delivers it to the buyer. This value is used by some platforms such as eBay to measure a seller's shipping time and performance. It will be displayed in the Shippo dashboard.

max_ship_time
string <date-time>

The date and time this item needs to be fulfilled by, i.e. by when the shipping label needs to be created and handed over to the carrier. This value is used by some platforms such as eBay to measure a seller's handling time and performance. It will be displayed in the Shippo dashboard.

quantity
integer <int64>

The quantity of this item in this order.

sku
string

The stock keeping unit value of this item.

title
string

Title of the line item.

total_price
string

Total price paid by the buyer for this item (or these items, if quantity > 1).

variant_title
string

A variant is a specific variation of an item (e.g. size M or color blue). Variants might be exposed as a separate resource in the future too. Currently the variant title is a free text field describing the variant.

weight
string

Total weight of this/these item(s). Instead of specifying the weight of all items, you can also set the total_weight value of the order object.

weight_unit
string (WeightUnitEnum)

The unit used for weight.

Enum: "g" "kg" "lb" "oz"
object_id
string

Unique identifier of the line item object.

{
  • "currency": "USD",
  • "manufacture_country": "US",
  • "max_delivery_time": "2016-07-23T00:00:00Z",
  • "max_ship_time": "2016-07-23T00:00:00Z",
  • "quantity": 20,
  • "sku": "HM-123",
  • "title": "Hippo Magazines",
  • "total_price": "12.1",
  • "variant_title": "June Edition",
  • "weight": "0.4",
  • "weight_unit": "lb",
  • "object_id": "abf7d5675d744b6ea9fdb6f796b28f28"
}

List all orders

Returns a list of all order objects.

SecurityAPIKeyHeader
Request
query Parameters
page
integer <int64>
Default: 1

The page number you want to select

results
integer <int64> <= 100
Default: 25

The number of results to return per page (max 100)

order_status[]
Array of strings (OrderStatusEnum)

Filter orders by order status

Items Enum: "UNKNOWN" "AWAITPAY" "PAID" "REFUNDED" "CANCELLED" "PARTIALLY_FULFILLED" "SHIPPED"
Example: order_status[]=PAID
shop_app
string (OrderShopAppEnum)

Filter orders by shop app

Enum: "Amazon" "Bigcommerce" "CSV_Import" "eBay" "ePages" "Etsy" "Godaddy" "Magento" "Shippo" "Shopify" "Spreecommerce" "StripeRelay" "Walmart" "Weebly" "WooCommerce"
Example: shop_app=Shippo
start_date
string

Filter orders created after the input date and time (ISO 8601 UTC format). This is based on the placed_at field, meaning when the order has been placed, not when the order object was created.

end_date
string

Filter orders created before the input date and time (ISO 8601 UTC format). This is based on the placed_at field, meaning when the order has been placed, not when the order object was created.

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/orders
Request samples 
curl https://api.goshippo.com/orders/ \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "next": "baseurl?page=3&results=10",
  • "previous": "baseurl?page=1&results=10",
  • "results": [
    ]
}

Create a new order

Creates a new order object.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required

Order details.

currency
string

Required if total_price is provided
Currency of the total_price and total_tax amounts.

notes
string

Custom buyer- or seller-provided notes about the order.

order_number
string

An alphanumeric identifier for the order used by the seller/buyer. This identifier doesn't need to be unique.

order_status
string (OrderStatusEnum)

Current state of the order. See the orders tutorial for the logic of how the status is handled.

Enum: "UNKNOWN" "AWAITPAY" "PAID" "REFUNDED" "CANCELLED" "PARTIALLY_FULFILLED" "SHIPPED"
placed_at
required
string

Date and time when the order was placed. This datetime can be different from the datetime of the order object creation on Shippo.

shipping_cost
string

Amount paid by the buyer for shipping. This amount can be different from the price the seller will actually pay for shipping.

shipping_cost_currency
string

Required if shipping_cost is provided
Currency of the shipping_cost amount.

shipping_method
string

Shipping method (carrier + service or other free text description) chosen by the buyer. This value can be different from the shipping method the seller will actually choose.

subtotal_price
string
total_price
string

Total amount paid by the buyer for this order.

total_tax
string

Total tax amount paid by the buyer for this order.

weight
string

Total weight of the order.

weight_unit
string (WeightUnitEnum)

The unit used for weight.

Enum: "g" "kg" "lb" "oz"
object (AddressFromCreateRequest)

Address object of the sender / seller. Will be returned expanded by default..

required
object (AddressToCreateRequest)

Address object of the recipient / buyer. Will be returned expanded by default.

Array of objects (LineItemCreateRequest)

Array of line item objects representing the items in this order. All objects will be returned expanded by default.

Responses
201
400
post/orders
Request samples
application/json
{
  • "currency": "USD",
  • "notes": "This customer is a VIP",
  • "order_number": "#1068",
  • "order_status": "PAID",
  • "placed_at": "2016-09-23T01:28:12Z",
  • "shipping_cost": "12.83",
  • "shipping_cost_currency": "USD",
  • "shipping_method": "USPS First Class Package",
  • "subtotal_price": "12.1",
  • "total_price": "24.93",
  • "total_tax": "0.0",
  • "weight": "0.4",
  • "weight_unit": "lb",
  • "from_address": {
    },
  • "to_address": {
    },
  • "line_items": [
    ]
}
Response samples
application/json
{
  • "currency": "USD",
  • "notes": "This customer is a VIP",
  • "order_number": "#1068",
  • "order_status": "PAID",
  • "placed_at": "2016-09-23T01:28:12Z",
  • "shipping_cost": "12.83",
  • "shipping_cost_currency": "USD",
  • "shipping_method": "USPS First Class Package",
  • "subtotal_price": "12.1",
  • "total_price": "24.93",
  • "total_tax": "0.0",
  • "weight": "0.4",
  • "weight_unit": "lb",
  • "from_address": {
    },
  • "to_address": {
    },
  • "line_items": [
    ],
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_owner": "shippotle@shippo.com",
  • "shop_app": "Shippo",
  • "transactions": [
    ]
}

Retrieve an order

Retrieves an existing order using an object ID.

SecurityAPIKeyHeader
Request
path Parameters
OrderId
required
string

Object ID of the order

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/orders/{OrderId}
Request samples 
curl https://api.goshippo.com/orders/4f2bc588e4e5446cb3f9fdb7cd5e190b/ \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "currency": "USD",
  • "notes": "This customer is a VIP",
  • "order_number": "#1068",
  • "order_status": "PAID",
  • "placed_at": "2016-09-23T01:28:12Z",
  • "shipping_cost": "12.83",
  • "shipping_cost_currency": "USD",
  • "shipping_method": "USPS First Class Package",
  • "subtotal_price": "12.1",
  • "total_price": "24.93",
  • "total_tax": "0.0",
  • "weight": "0.4",
  • "weight_unit": "lb",
  • "from_address": {
    },
  • "to_address": {
    },
  • "line_items": [
    ],
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_owner": "shippotle@shippo.com",
  • "shop_app": "Shippo",
  • "transactions": [
    ]
}

Refunds

Refunds are reimbursements for successfully created but unused shipping labels or other charges.

object_created
string <date-time>

Date and time of object creation.

object_id
string

Unique identifier of the given object.

object_owner
string

Username of the user who created the object.

object_updated
string <date-time>

Date and time of last object update.

status
string

Indicates the status of the Refund.

Enum: "QUEUED" "PENDING" "SUCCESS" "ERROR"
test
boolean

Indicates whether the object has been created in test mode.

transaction
string

Object ID of the Transaction to be refunded.

{
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_owner": "shippotle@shippo.com",
  • "object_updated": "2019-08-24T14:15:22Z",
  • "status": "SUCCESS",
  • "test": true,
  • "transaction": "915d94940ea54c3a80cbfa328722f5a1"
}

Create a refund

Creates a new refund object.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required

Refund details

async
boolean
transaction
required
string
Responses
201
400
post/refunds
Request samples
application/json
{
  • "async": false,
  • "transaction": "915d94940ea54c3a80cbfa328722f5a1"
}
Response samples
application/json
{
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_owner": "shippotle@shippo.com",
  • "object_updated": "2019-08-24T14:15:22Z",
  • "status": "SUCCESS",
  • "test": true,
  • "transaction": "915d94940ea54c3a80cbfa328722f5a1"
}

List all refunds

Returns a list all refund objects.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/refunds/
Request samples 
curl https://api.goshippo.com/refunds/ \
    -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "next": "baseurl?page=3&results=10",
  • "previous": "baseurl?page=1&results=10",
  • "results": [
    ]
}

Retrieve a refund

Returns an existing rate using a rate object ID.

SecurityAPIKeyHeader
Request
path Parameters
RefundId
required
string

Object ID of the refund to update

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/refunds/{RefundId}
Request samples 
curl https://api.goshippo.com/refunds/d7c811cff9e24e4387418876f1ffd371 \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_owner": "shippotle@shippo.com",
  • "object_updated": "2019-08-24T14:15:22Z",
  • "status": "SUCCESS",
  • "test": true,
  • "transaction": "915d94940ea54c3a80cbfa328722f5a1"
}

Service Groups

A service group is a set of service levels grouped together. Rates at checkout uses services groups to present available shipping options to customers in their shopping basket.

description
required
string

Description for the service group

flat_rate
string

String representation of an amount to be returned as the flat rate if 1. The service group is of type LIVE_RATE and no matching rates were found; or 2. The service group is of type FLAT_RATE. Either integers or decimals are accepted. Required unless type is FREE_SHIPPING

flat_rate_currency
string

required unless type is FREE_SHIPPING. (ISO 4217 currency)

free_shipping_threshold_currency
string

optional unless type is FREE_SHIPPING. (ISO 4217 currency)

free_shipping_threshold_min
string

For service groups of type FREE_SHIPPING, this field must be required to configure the minimum cart total (total cost of items in the cart) for this service group to be returned for rates at checkout. Optional unless type is FREE_SHIPPING

name
required
string

Name for the service group that will be shown to customers in the response

rate_adjustment
integer <int64>

The amount in percent (%) that the service group's returned rate should be adjusted. For example, if this field is set to 5 and the matched rate price is $5.00, the returned value of the service group will be $5.25. Negative integers are also accepted and will discount the rate price by the defined percentage amount.

type
required
string (ServiceGroupTypeEnum)

The type of the service group.
LIVE_RATE - Shippo will make a rating request and return real-time rates for the shipping group, only falling back to the specified flat rate amount if no rates match a service level in the service group.
FLAT_RATE - Returns a shipping option with the specified flat rate amount.
FREE_SHIPPING - Returns a shipping option with a price of $0 only if the total cost of items exceeds the amount defined by free_shipping_threshold_min

Enum: "LIVE_RATE" "FLAT_RATE" "FREE_SHIPPING"
object_id
required
string

The unique identifier of the given Service Group object.

is_active
boolean

True if the service group is enabled, false otherwise.

required
Array of objects (ServiceGroupAccountAndServiceLevel)
{
  • "description": "USPS shipping options",
  • "flat_rate": "5",
  • "flat_rate_currency": "USD",
  • "free_shipping_threshold_currency": "USD",
  • "free_shipping_threshold_min": "5",
  • "name": "USPS Shipping",
  • "rate_adjustment": 15,
  • "type": "FLAT_RATE",
  • "object_id": "80feb1633d4a43c898f005850",
  • "is_active": true,
  • "service_levels": [
    ]
}

List all service groups

Returns a list of service group objects.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/service-groups
Request samples 
curl https://api.goshippo.com/service-groups  \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -H "Content-Type: application/json"
Response samples
application/json
[
  • {
    }
]

Create a new service group

Creates a new service group.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required
description
required
string

Description for the service group

flat_rate
string

String representation of an amount to be returned as the flat rate if 1. The service group is of type LIVE_RATE and no matching rates were found; or 2. The service group is of type FLAT_RATE. Either integers or decimals are accepted. Required unless type is FREE_SHIPPING

flat_rate_currency
string

required unless type is FREE_SHIPPING. (ISO 4217 currency)

free_shipping_threshold_currency
string

optional unless type is FREE_SHIPPING. (ISO 4217 currency)

free_shipping_threshold_min
string

For service groups of type FREE_SHIPPING, this field must be required to configure the minimum cart total (total cost of items in the cart) for this service group to be returned for rates at checkout. Optional unless type is FREE_SHIPPING

name
required
string

Name for the service group that will be shown to customers in the response

rate_adjustment
integer <int64>

The amount in percent (%) that the service group's returned rate should be adjusted. For example, if this field is set to 5 and the matched rate price is $5.00, the returned value of the service group will be $5.25. Negative integers are also accepted and will discount the rate price by the defined percentage amount.

type
required
string (ServiceGroupTypeEnum)

The type of the service group.
LIVE_RATE - Shippo will make a rating request and return real-time rates for the shipping group, only falling back to the specified flat rate amount if no rates match a service level in the service group.
FLAT_RATE - Returns a shipping option with the specified flat rate amount.
FREE_SHIPPING - Returns a shipping option with a price of $0 only if the total cost of items exceeds the amount defined by free_shipping_threshold_min

Enum: "LIVE_RATE" "FLAT_RATE" "FREE_SHIPPING"
required
Array of objects (ServiceGroupAccountAndServiceLevel)
Responses
201
400
post/service-groups
Request samples
application/json
{
  • "description": "USPS shipping options",
  • "flat_rate": "5",
  • "flat_rate_currency": "USD",
  • "free_shipping_threshold_currency": "USD",
  • "free_shipping_threshold_min": "5",
  • "name": "USPS Shipping",
  • "rate_adjustment": 15,
  • "type": "FLAT_RATE",
  • "service_levels": [
    ]
}
Response samples
application/json
{
  • "description": "USPS shipping options",
  • "flat_rate": "5",
  • "flat_rate_currency": "USD",
  • "free_shipping_threshold_currency": "USD",
  • "free_shipping_threshold_min": "5",
  • "name": "USPS Shipping",
  • "rate_adjustment": 15,
  • "type": "FLAT_RATE",
  • "object_id": "80feb1633d4a43c898f005850",
  • "is_active": true,
  • "service_levels": [
    ]
}

Update an existing service group

Updates an existing service group object.
The object_id cannot be updated as it is the unique identifier for the object.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
description
required
string

Description for the service group

flat_rate
string

String representation of an amount to be returned as the flat rate if 1. The service group is of type LIVE_RATE and no matching rates were found; or 2. The service group is of type FLAT_RATE. Either integers or decimals are accepted. Required unless type is FREE_SHIPPING

flat_rate_currency
string

required unless type is FREE_SHIPPING. (ISO 4217 currency)

free_shipping_threshold_currency
string

optional unless type is FREE_SHIPPING. (ISO 4217 currency)

free_shipping_threshold_min
string

For service groups of type FREE_SHIPPING, this field must be required to configure the minimum cart total (total cost of items in the cart) for this service group to be returned for rates at checkout. Optional unless type is FREE_SHIPPING

name
required
string

Name for the service group that will be shown to customers in the response

rate_adjustment
integer <int64>

The amount in percent (%) that the service group's returned rate should be adjusted. For example, if this field is set to 5 and the matched rate price is $5.00, the returned value of the service group will be $5.25. Negative integers are also accepted and will discount the rate price by the defined percentage amount.

type
required
string (ServiceGroupTypeEnum)

The type of the service group.
LIVE_RATE - Shippo will make a rating request and return real-time rates for the shipping group, only falling back to the specified flat rate amount if no rates match a service level in the service group.
FLAT_RATE - Returns a shipping option with the specified flat rate amount.
FREE_SHIPPING - Returns a shipping option with a price of $0 only if the total cost of items exceeds the amount defined by free_shipping_threshold_min

Enum: "LIVE_RATE" "FLAT_RATE" "FREE_SHIPPING"
object_id
required
string

The unique identifier of the given Service Group object.

is_active
required
boolean

True if the service group is enabled, false otherwise.

required
Array of objects (ServiceGroupAccountAndServiceLevel)
Responses
200
400
put/service-groups
Request samples
application/json
{
  • "description": "USPS shipping options",
  • "flat_rate": "5",
  • "flat_rate_currency": "USD",
  • "free_shipping_threshold_currency": "USD",
  • "free_shipping_threshold_min": "5",
  • "name": "USPS Shipping",
  • "rate_adjustment": 15,
  • "type": "FLAT_RATE",
  • "object_id": "80feb1633d4a43c898f005850",
  • "is_active": true,
  • "service_levels": [
    ]
}
Response samples
application/json
{
  • "description": "USPS shipping options",
  • "flat_rate": "5",
  • "flat_rate_currency": "USD",
  • "free_shipping_threshold_currency": "USD",
  • "free_shipping_threshold_min": "5",
  • "name": "USPS Shipping",
  • "rate_adjustment": 15,
  • "type": "FLAT_RATE",
  • "object_id": "80feb1633d4a43c898f005850",
  • "is_active": true,
  • "service_levels": [
    ]
}

Delete a service group

Deletes an existing service group using an object ID.

SecurityAPIKeyHeader
Request
path Parameters
ServiceGroupId
required
string

Object ID of the service group

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
204

The service group was successfully deleted.

400
delete/service-groups/{ServiceGroupId}
Request samples 
curl -x DELETE https://api.goshippo.com/service-groups/80feb1633d4a43c898f0058506cfd82d  \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396" \
Response samples
application/json
{ }

Rates at Checkout

Rates at checkout is a tool for merchants to display up-to-date shipping estimates based on what's in their customers cart and where they’re shipping to. Merchants set up curated shipping options for customers in the checkout flow based on data in the shopping cart. The request must include the to address and item information. Optional fields are the from address and package information. If the optional fields are not included, the service will use the default address and/or package configured for rates at checkout. The response is a list of shipping options based on the Service Group configuration. (see Service Group configuration for details).

amount
string

Final Rate price, expressed in the currency used in the sender's country.

amount_local
string

Final Rate price, expressed in the currency used in the recipient's country.

currency
string

Currency used in the sender's country, refers to amount. The official ISO 4217 currency codes are used, e.g. USD or EUR.

currency_local
string

Currency used in the recipient's country, refers to amount_local. The official ISO 4217 currency codes are used, e.g. USD or "EUR".

estimated_days
integer <int64>

The estimated days in transit of the rate that powers the shipping option, if available.

title
string

The name of the service group being returned

{
  • "amount": "5.5",
  • "amount_local": "5.5",
  • "currency": "USD",
  • "currency_local": "USD",
  • "estimated_days": 2,
  • "title": "Shipping Option 1"
}

Default Parcel Template

Assign one of your user parcel templates to be the default used when generating Live Rates. This template will be used by default when generating Live Rates, unless you explicitly provide a parcel in the Live Rates request.

distance_unit
string (DistanceUnitEnum)

The measure unit used for length, width and height. Required, but if using a preset carrier template then this field must be empty.

Enum: "cm" "in" "ft" "m" "mm" "yd"
height
string

The height of the package, in units specified by the distance_unit attribute. Required, but if using a preset carrier template then this field must be empty.

length
string

The length of the package, in units specified by the distance_unit attribute. Required, but if using a preset carrier template then this field must be empty.

name
string

The name of the User Parcel Template

weight
string

The weight of the package, in units specified by the weight_unit attribute.

weight_unit
string (WeightUnitEnum)

The unit used for weight.

Enum: "g" "kg" "lb" "oz"
width
string

The width of the package, in units specified by the distance_unit attribute. Required, but if using a preset carrier template then this field must be empty.

object_created
string <date-time>

Date and time of User Parcel Template creation

object_id
string

Unique identifier of the given User Parcel Template object

object_owner
string

Username of the user who created the User Parcel Template object

object_updated
string <date-time>

Date and time of last update on User Parcel Template

object (CarrierParcelTemplate)
{
  • "distance_unit": "in",
  • "height": "6",
  • "length": "10",
  • "name": "My Custom Template",
  • "weight": "12",
  • "weight_unit": "lb",
  • "width": "8",
  • "object_created": "2013-12-11T19:38:09.729Z",
  • "object_id": "b958d3690bb04bb8b2986724872750f5",
  • "object_owner": "shippotle@shippo.com",
  • "object_updated": "2013-12-12T19:38:09.729Z",
  • "template": {
    }
}

Generate a live rates request

Initiates a live rates request. Include either the object ID for an existing address record or a fully formed address object when entering an address value. You can also enter the object ID of an existing user parcel template or a fully formed user parcel template object as the parcel value.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required

Generate rates at checkout

string or AddressCompleteCreateRequest (object)

The sender address, which includes your name, company name, street address, city, state, zip code, country, phone number, and email address (strings). Special characters should not be included in any address element, especially name, company, and email.

required
string or AddressCompleteCreateRequest (object)

The recipient address, which includes the recipient's name, company name, street address, city, state, zip code, country, phone number, and email address (strings). Special characters should not be included in any address element, especially name, company, and email.

required
Array of objects (LineItem)

Array of Line Item objects

string or Parcel (object)

Object ID for an existing User Parcel Template OR a fully formed Parcel object.

Responses
200
400
post/live-rates
Request samples
application/json
{
  • "address_from": "string",
  • "address_to": "string",
  • "line_items": [
    ],
  • "parcel": "5df144dca289442cv7a06"
}
Response samples
application/json
{
  • "next": "baseurl?page=3&results=10",
  • "previous": "baseurl?page=1&results=10",
  • "count": 123,
  • "results": [
    ]
}

Show current default parcel template

Retrieve and display the currently configured default parcel template for live rates.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/live-rates/settings/parcel-template
Request samples 
curl https://api.goshippo.com/live-rates/settings/parcel-template \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -H "Content-Type: application/json"
Response samples
application/json
{
  • "result": {
    }
}

Update default parcel template

Update the currently configured default parcel template for live rates. The object_id in the request payload should identify the user parcel template to be the new default.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
object_id
string
Responses
200
400
put/live-rates/settings/parcel-template
Request samples
application/json
{
  • "object_id": "b958d3690bb04bb8b2986724872750f5"
}
Response samples
application/json
{
  • "result": {
    }
}

Clear current default parcel template

Clears the currently configured default parcel template for live rates.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
204

The parcel template was successfully deleted.

400
delete/live-rates/settings/parcel-template
Request samples 
curl -X DELETE https://api.goshippo.com/live-rates/settings/parcel-template \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396" \
Response samples
application/json
{ }

Shippo Accounts

Shippo Accounts are used by Shippo Platform Accounts to create and manage Managed Shippo Accounts. Managed Shippo Accounts are headless accounts that represent your customers. They are opaque to your end customers, meaning customers do not need to create their own Shippo login or have a billing relationship with Shippo. They can be used by marketplaces, e-commerce platforms, and third-party logistics providers who want to offer, seamless, built-in shipping functionality to their customers. See our guide for more details.

email
required
string
first_name
required
string
last_name
required
string
company_name
string
object_created
string <date-time>
object_id
string
object_updated
string <date-time>
{
  • "email": "hippo@shippo.com",
  • "first_name": "Shippo",
  • "last_name": "Meister",
  • "company_name": "Acme",
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_updated": "2019-08-24T14:15:22Z"
}

List all Shippo Accounts

Returns a list of Shippo Managed Accounts objects.

SecurityAPIKeyHeader
Request
query Parameters
page
integer <int64>
Default: 1

The page number you want to select

results
integer <int64> <= 100
Default: 25

The number of results to return per page (max 100)

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/shippo-accounts
Request samples 
import shippo

s = shippo.Shippo(
    api_key_header='ShippoToken <API_TOKEN>',
    shippo_api_version='2018-02-08',
)


res = s.shippo_accounts.list()

if res is not None:
    # handle response
    pass
Response samples
application/json
{
  • "next": "baseurl?page=3&results=10",
  • "previous": "baseurl?page=1&results=10",
  • "results": [
    ]
}

Create a Shippo Account

Creates a new Shippo Managed Account.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
required
email
required
string
first_name
required
string
last_name
required
string
company_name
required
string
Responses
201
400
post/shippo-accounts
Request samples
application/json
{
  • "email": "hippo@shippo.com",
  • "first_name": "Shippo",
  • "last_name": "Meister",
  • "company_name": "Acme"
}
Response samples
application/json
{
  • "email": "hippo@shippo.com",
  • "first_name": "Shippo",
  • "last_name": "Meister",
  • "company_name": "Acme",
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_updated": "2019-08-24T14:15:22Z"
}

Retrieve a Shippo Account

Returns a Shippo Managed Account using an object ID.

SecurityAPIKeyHeader
Request
path Parameters
ShippoAccountId
required
string

Object ID of the ShippoAccount

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Responses
200
400
get/shippo-accounts/{ShippoAccountId}
Request samples 
import shippo

s = shippo.Shippo(
    api_key_header='ShippoToken <API_TOKEN>',
    shippo_api_version='2018-02-08',
)


res = s.shippo_accounts.get(shippo_account_id='<id>')

if res is not None:
    # handle response
    pass
Response samples
application/json
{
  • "email": "hippo@shippo.com",
  • "first_name": "Shippo",
  • "last_name": "Meister",
  • "company_name": "Acme",
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_updated": "2019-08-24T14:15:22Z"
}

Update a Shippo Account

Updates a Shippo Managed Account using an object ID.

SecurityAPIKeyHeader
Request
path Parameters
ShippoAccountId
required
string

Object ID of the ShippoAccount

header Parameters
SHIPPO-API-VERSION
string

Optional string used to pick a non-default API version to use. See our API version guide.

Example: 2018-02-08
Request Body schema: application/json
email
required
string
first_name
required
string
last_name
required
string
company_name
required
string
Responses
200
400
put/shippo-accounts/{ShippoAccountId}
Request samples
application/json
{
  • "email": "hippo@shippo.com",
  • "first_name": "Shippo",
  • "last_name": "Meister",
  • "company_name": "Acme"
}
Response samples
application/json
{
  • "email": "hippo@shippo.com",
  • "first_name": "Shippo",
  • "last_name": "Meister",
  • "company_name": "Acme",
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "object_updated": "2019-08-24T14:15:22Z"
}

Carriers

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 Jitsu
better_trucks BetterTrucks
borderguru BorderGuru
boxberry Boxberry
bring Bring (also used for Posten Norge)
canada_post Canada Post
cdl CDL
chronopost Chronopost
collect_plus CollectPlus
correios_br CorreiosBR
correos_espana Correos España
colissimo Colissimo
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_de DPD GERMANY
dpd_uk DPD UK
estafeta Estafeta
fastway_australia Aramex
fedex FedEx
globegistics Globegistics (now Asendia)
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
new_zealand_post New Zealand Post (also used for Pace and CourierPost)
nippon_express Nippon Express
ontrac OnTrac
parcelforce Parcelforce
passport Passport
pcf PCF
poste_italiane Poste Italiane
posti Posti
purolator Purolator
royal_mail Royal Mail
rr_donnelley ePost Global
russian_post Russian Post
sendle Sendle
skypostal SkyPostal
stuart Stuart
swyft Swyft
uds UDS (United Delivery Service)
ups UPS
usps USPS
veho Veho
string (CarriersEnum)
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 Jitsu
better_trucks BetterTrucks
borderguru BorderGuru
boxberry Boxberry
bring Bring (also used for Posten Norge)
canada_post Canada Post
cdl CDL
chronopost Chronopost
collect_plus CollectPlus
correios_br CorreiosBR
correos_espana Correos España
colissimo Colissimo
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_de DPD GERMANY
dpd_uk DPD UK
estafeta Estafeta
fastway_australia Aramex
fedex FedEx
globegistics Globegistics (now Asendia)
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
new_zealand_post New Zealand Post (also used for Pace and CourierPost)
nippon_express Nippon Express
ontrac OnTrac
parcelforce Parcelforce
passport Passport
pcf PCF
poste_italiane Poste Italiane
posti Posti
purolator Purolator
royal_mail Royal Mail
rr_donnelley ePost Global
russian_post Russian Post
sendle Sendle
skypostal SkyPostal
stuart Stuart
swyft Swyft
uds UDS (United Delivery Service)
ups UPS
usps USPS
veho Veho
Enum: "airterra" "apc_postal" "apg" "aramex" "asendia_us" "australia_post" "axlehire" "better_trucks" "borderguru" "boxberry" "bring" "canada_post" "cdl" "chronopost" "collect_plus" "correios_br" "correos_espana" "colissimo" "deutsche_post" "dhl_benelux" "dhl_ecommerce" "dhl_express" "dhl_germany_c2c" "dhl_germany" "dpd_de" "dpd_uk" "estafeta" "fastway_australia" "fedex" "globegistics" "gls_us" "gophr" "gso" "hermes_germany_b2c" "hermes_uk" "hongkong_post" "lasership" "lso" "mondial_relay" "new_zealand_post" "nippon_express" "ontrac" "parcelforce" "passport" "pcf" "poste_italiane" "posti" "purolator" "royal_mail" "rr_donnelley" "russian_post" "sendle" "skypostal" "stuart" "swyft" "uds" "ups" "usps" "veho"
"airterra"

Service Levels

One of:
Token Service name
usps_priority Priority Mail
usps_priority_express Priority Mail Express
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
usps_ground_advantage Ground Advantage
string (ServiceLevelUSPSEnum)
Enum: "usps_priority" "usps_priority_express" "usps_media_mail" "usps_priority_mail_international" "usps_priority_mail_express_international" "usps_first_class_package_international_service" "usps_ground_advantage"
"usps_priority"

Parcel Templates

A predefined package used by one or multiple carriers. See below 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.

If template is passed, length, width, height, and distance_unit are not required

One of:
Token Name Dimensions
FedEx_Box_10kg FedEx® 10kg Box 15.81 x 12.94 x 10.19 in
FedEx_Box_25kg FedEx® 25kg Box 54.80 x 42.10 x 33.50 in
FedEx_Box_Extra_Large_1 FedEx® Extra Large Box (X1) 11.88 x 11.00 x 10.75 in
FedEx_Box_Extra_Large_2 FedEx® Extra Large Box (X2) 15.75 x 14.13 x 6.00 in
FedEx_Box_Large_1 FedEx® Large Box (L1) 17.50 x 12.38 x 3.00 in
FedEx_Box_Large_2 FedEx® Large Box (L2) 11.25 x 8.75 x 7.75 in
FedEx_Box_Medium_1 FedEx® Medium Box (M1) 13.25 x 11.50 x 2.38 in
FedEx_Box_Medium_2 FedEx® Medium Box (M2) 11.25 x 8.75 x 4.38 in
FedEx_Box_Small_1 FedEx® Small Box (S1) 12.38 x 10.88 x 1.50 in
FedEx_Box_Small_2 FedEx® Small Box (S2) 11.25 x 8.75 x 4.38 in
FedEx_Envelope FedEx® Envelope 12.50 x 9.50 x 0.80 in
FedEx_Padded_Pak FedEx® Padded Pak 11.75 x 14.75 x 2.00 in
FedEx_Pak_1 FedEx® Large Pak 15.50 x 12.00 x 0.80 in
FedEx_Pak_2 FedEx® Small Pak 12.75 x 10.25 x 0.80 in
FedEx_Tube FedEx® Tube 38.00 x 6.00 x 6.00 in
FedEx_XL_Pak FedEx® Extra Large Pak 17.50 x 20.75 x 2.00 in
string (FedEx Parcel Template)
Enum: "FedEx_Box_10kg" "FedEx_Box_25kg" "FedEx_Box_Extra_Large_1" "FedEx_Box_Extra_Large_2" "FedEx_Box_Large_1" "FedEx_Box_Large_2" "FedEx_Box_Medium_1" "FedEx_Box_Medium_2" "FedEx_Box_Small_1" "FedEx_Box_Small_2" "FedEx_Envelope" "FedEx_Padded_Pak" "FedEx_Pak_1" "FedEx_Pak_2" "FedEx_Tube" "FedEx_XL_Pak"
"FedEx_Box_10kg"

Address Validation Source

string (AddressValidationResultsMessageSourceEnum)
Enum: "Shippo Address Validator" "UPS"
"Shippo Address Validator"

Address Validation Codes

string (AddressValidationResultsMessageCodeEnum)
Enum: "verification_error" "unknown_street" "component_mismatch_error" "multiple_match" "sub_premise_number_invalid" "sub_premise_number_missing" "premise_number_invalid" "premise_number_missing" "box_number_invalid" "box_number_missing" "pmb_number_missing" "postal_code_change" "administrative_area_change" "locality_change" "dependent_locality_change" "street_name_change" "street_type_change" "street_directional_change" "sub_premise_type_change" "sub_premise_number_change" "double_dependent_locality_change" "subadministrative_area_change" "subnational_area_change" "po_box_change" "premise_type_change" "house_number_change" "organization_change" "extraneous_information" "usps_door_inaccessible" "administrative_area_partial" "city_partial" "street_partial" "building_partial" "subpremise_partial" "administrative_area_full" "city_full" "thoroughfare_full" "premises_full" "subpremise_full" "geocoded_street" "geocoded_neighborhood" "geocoded_community" "geocoded_state" "geocoded_rooftop" "geocoded_interpolated_rooftop" "invalid_postal_code" "postal_code_not_found" "empty_request" "service_error" "street_detail_missing" "Invalid City/State/Zip" "Default Match" "Unknown Street" "Address Not Found" "Non-Deliverable ZIP4" "Multiple Responses" "Invalid Dual Address" "Invalid State" "Invalid City" "Ambiguous Address"
"verification_error"

Customs Declaration B13A Filing Option

B13A Option details are obtained by filing a B13A Canada Export Declaration via the Canadian Export Reporting System (CERS). More information on reporting commercial exports from Canada. Allowed values available here

string (CustomsDeclarationB13AFilingOptionEnum)

B13A Option details are obtained by filing a B13A Canada Export Declaration via the Canadian Export Reporting System (CERS). More information on reporting commercial exports from Canada. Allowed values available here

Enum: "FILED_ELECTRONICALLY" "SUMMARY_REPORTING" "NOT_REQUIRED"
"FILED_ELECTRONICALLY"

Customs Declaration Contents Type

Type of goods of the shipment.
Allowed values available here

string (CustomsDeclarationContentsTypeEnum)

Type of goods of the shipment.
Allowed values available here

Enum: "DOCUMENTS" "GIFT" "SAMPLE" "MERCHANDISE" "HUMANITARIAN_DONATION" "RETURN_MERCHANDISE" "OTHER"
"DOCUMENTS"

Customs Declaration EEL/PFC

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. Allowed values available here

string (CustomsDeclarationEelPfcEnum)

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. Allowed values available here

Enum: "NOEEI_30_37_a" "NOEEI_30_37_h" "NOEEI_30_37_f" "NOEEI_30_36" "AES_ITN"
"NOEEI_30_37_a"

Customs Declaration Incoterm

The incoterm reference of the shipment. FCA is available for DHL Express and FedEx only. eDAP is available for DPD UK only. DAP is available for DHL Express and DPD UK. If expecting DAP for other carriers, please use DDU. Allowed values available here

string (CustomsDeclarationIncotermEnum)

The incoterm reference of the shipment. FCA is available for DHL Express and FedEx only. eDAP is available for DPD UK only. DAP is available for DHL Express and DPD UK. If expecting DAP for other carriers, please use DDU. Allowed values available here

Enum: "DDP" "DDU" "FCA" "DAP" "eDAP"
"DDP"

Customs Declaration Non Delivery Option

Indicates how the carrier should proceed in case the shipment can't be delivered. Allowed values available here

string (CustomsDeclarationNonDeliveryOptionEnum)

Indicates how the carrier should proceed in case the shipment can't be delivered. Allowed values available here

Enum: "ABANDON" "RETURN"
"ABANDON"