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 Couriers Please 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
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": {