Shippo external API. (2018-02-08)

Download OpenAPI specification:Download

Use this API to integrate with the Shippo service

Overview


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

API Resources

All API URLs listed in this documentation are relative to https://api.goshippo.com/.

For example, the /addresses/ resource is reachable at https://api.goshippo.com/addresses/.

Authentication

The API requires Shippo's token HTTP Authentication with your Shippo token (live or test).

In order to authenticate properly, please put Authorization: ShippoToken <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

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.

company
string

Company Name

country
required
string

Example: US or DE. All accepted values can be found on the Official ISO Website. Sending a country is always required.

email
string

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

is_residential
boolean

Indicates whether the address provided is a residential address or not.

metadata
string

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

name
string

required for purchase
First and Last Name of the addressee

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.

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.

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.

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.

latitude
number

Latitude of address

longitude
number

Longitude of address

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.

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.

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

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

header Parameters
SHIPPO-API-VERSION
string

String used to pick a non-default API version to use

Responses
200
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

String used to pick a non-default API version to use

Request Body schema: application/json

Address details.

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.

company
string

Company Name

country
required
string

Example: US or DE. All accepted values can be found on the Official ISO Website. Sending a country is always required.

email
string

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

is_residential
boolean

Indicates whether the address provided is a residential address or not.

metadata
string

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

name
string

required for purchase
First and Last Name of the addressee

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.

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.

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.

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.

latitude
number

Latitude of address

longitude
number

Longitude of address

validate
boolean

Set to true to validate Address object.

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

String used to pick a non-default API version to use

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

String used to pick a non-default API version to use

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

distance_unit
required
string (DistanceUnitTemplate)

The measure unit used for length, width and height. Required if template is not specified.

Enum: "cm" "in" "ft" "m" "mm" "yd"
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.

height
required
string

Required if template is not specified
Height of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.

length
required
string

Required if template is not specified
Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.

mass_unit
required
string (WeightUnit)

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.

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.

ParcelTemplateFedEx (string) or ParcelTemplateUPS (string) or ParcelTemplateUSPS (string) or ParcelTemplateDHLeCommerce (string) or ParcelTemplateDPDUK (string) or ParcelTemplateCouriersPlease (string) or ParcelTemplateAramexAustralia (string) (ParcelTemplateEnumSet)

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

test
boolean

Indicates whether the object has been created in test mode.

weight
required
string

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

width
required
string

Required if template is not specified
Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.

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

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

Specify collection on delivery details (UPS only).

object (ParcelInsurance)

ParcelInsurance Specify insurance details

{
  • "COD": {
    },
  • "insurance": {
    }
}

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

String used to pick a non-default API version to use

Responses
200
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

String used to pick a non-default API version to use

Request Body schema: application/json

Parcel details.

distance_unit
required
string (DistanceUnitTemplate)

The measure unit used for length, width and height. Required if template is not specified.

Enum: "cm" "in" "ft" "m" "mm" "yd"
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.

height
required
string

Required if template is not specified. Height of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.

length
required
string

Required if template is not specified. Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.

mass_unit
required
string (WeightUnit)

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.

ParcelTemplateFedEx (string) or ParcelTemplateUPS (string) or ParcelTemplateUSPS (string) or ParcelTemplateDHLeCommerce (string) or ParcelTemplateDPDUK (string) or ParcelTemplateCouriersPlease (string) or ParcelTemplateAramexAustralia (string) (ParcelTemplateEnumSet)

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

test
boolean

Indicates whether the object has been created in test mode.

weight
required
string

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

width
required
string

Required if template is not specified. Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.

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

Retrieve a parcel

Returns an existing parcel using an object ID.

SecurityAPIKeyHeader
Request
path Parameters
ParcelId
required
string

Object ID of the parcel

header Parameters
SHIPPO-API-VERSION
string

String used to pick a non-default API version to use

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

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

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
string

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

String used to pick a non-default API version to use

Responses
200
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
[
  • {
    }
]

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

String used to pick a non-default API version to use

Responses
200
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 (DistanceUnitUserTemplate)

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

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 (CarrierParcelTemplateStruct represents the fields of a template before saving it to the db.)
{
  • "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@goshippo.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

String used to pick a non-default API version to use

Responses
200
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

String used to pick a non-default API version to use

Request Body schema: application/json
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 (WeightUnit)

The unit used for weight.

Enum: "g" "kg" "lb" "oz"
Responses
200
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@goshippo.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

String used to pick a non-default API version to use

Responses
204

The user parcel template was successfully deleted.

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

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

String used to pick a non-default API version to use

Responses
200
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@goshippo.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

String used to pick a non-default API version to use

Request Body schema: application/json
distance_unit
required
string (DistanceUnitUserTemplate)

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

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
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@goshippo.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

customs_declaration
string

ID of the Customs Declarations object for an international shipment.

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.

required
Array of objects

An array containing elements of the following schema:
code (string): an identifier for the corresponding message (not always available)
message (string): a publishable message containing further information.

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

Array of IDs of the 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" "STATUS"
test
boolean

Indicates whether the object has been created in test mode.

{
  • "customs_declaration": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "extra": {
    },
  • "metadata": "Customer ID 123456",
  • "shipment_date": "2021-03-22T12:00:00Z",
  • "address_from": {
    },
  • "address_return": {
    },
  • "address_to": {
    },
  • "carrier_accounts": [
    ],
  • "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": "SUCCESS",
  • "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.

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"
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 (Alcohol)

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

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

Specify collection on delivery details (UPS only).

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

dangerous_goods_code
any

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

Enum: "01" "02" "03" "04" "05" "06" "07" "08" "09"
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.

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

object (DryIce)

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

fulfillment_center
string

The fulfilment center where the package originates from.

object (Insurance)

Specify amount, content, provider, and currency of shipment insurance (UPS, FedEx and Ontrac only).

object (InvoiceNumber)

Specify the invoice number field on the label (FedEx 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
any

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

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

Declared value (Lasership only). Defaults to 50.00.

object (PoNumber)

Specify the PO number field on the label (FedEx 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).

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. Up to 50 characters.

reference_2
string

Optional text to be printed on the shipping label. 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).

return_service_type
any

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

Enum: "PRINT_AND_MAIL" "ATTEMPT_1" "ATTEMPT_3" "ELECTRONIC_LABEL"
object (RmaNumber)

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

saturday_delivery
boolean

Marks shipment as to be delivered on a Saturday.

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"
{
  • "ancillary_endorsement": "FORWARDING_SERVICE_REQUESTED",
  • "authority_to_leave": true,
  • "alcohol": {
    },
  • "billing": {
    },
  • "bypass_address_validation": true,
  • "carbon_neutral": true,
  • "carrier_hub_id": "string",
  • "carrier_hub_travel_time": 0,
  • "COD": {
    },
  • "container_type": "string",
  • "critical_pull_time": "string",
  • "customer_branch": "string",
  • "customer_reference": {
    },
  • "dangerous_goods_code": "01",
  • "dangerous_goods": {
    },
  • "delivery_instructions": "string",
  • "dept_number": {
    },
  • "dry_ice": {
    },
  • "fulfillment_center": "string",
  • "insurance": {
    },
  • "invoice_number": {
    },
  • "is_return": true,
  • "lasership_attrs": "TwoPersonDelivery",
  • "lasership_declared_value": "string",
  • "po_number": {
    },
  • "preferred_delivery_timeframe": "10001200",
  • "premium": true,
  • "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,
  • "signature_confirmation": "STANDARD"
}

Shipment Extras

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

An object holding optional extra services to be requested.

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"
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 (Alcohol)

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

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

Specify collection on delivery details (UPS only).

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

dangerous_goods_code
any

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

Enum: "01" "02" "03" "04" "05" "06" "07" "08" "09"
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.

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

object (DryIce)

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

fulfillment_center
string

The fulfilment center where the package originates from.

object (Insurance)

Specify amount, content, provider, and currency of shipment insurance (UPS, FedEx and Ontrac only).

object (InvoiceNumber)

Specify the invoice number field on the label (FedEx 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
any

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

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

Declared value (Lasership only). Defaults to 50.00.

object (PoNumber)

Specify the PO number field on the label (FedEx 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).

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. Up to 50 characters.

reference_2
string

Optional text to be printed on the shipping label. 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).

return_service_type
any

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

Enum: "PRINT_AND_MAIL" "ATTEMPT_1" "ATTEMPT_3" "ELECTRONIC_LABEL"
object (RmaNumber)

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

saturday_delivery
boolean

Marks shipment as to be delivered on a Saturday.

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"
{
  • "ancillary_endorsement": "FORWARDING_SERVICE_REQUESTED",
  • "authority_to_leave": true,
  • "alcohol": {
    },
  • "billing": {
    },
  • "bypass_address_validation": true,
  • "carbon_neutral": true,
  • "carrier_hub_id": "string",
  • "carrier_hub_travel_time": 0,
  • "COD": {
    },
  • "container_type": "string",
  • "critical_pull_time": "string",
  • "customer_branch": "string",
  • "customer_reference": {
    },
  • "dangerous_goods_code": "01",
  • "dangerous_goods": {
    },
  • "delivery_instructions": "string",
  • "dept_number": {
    },
  • "dry_ice": {
    },
  • "fulfillment_center": "string",
  • "insurance": {
    },
  • "invoice_number": {
    },
  • "is_return": true,
  • "lasership_attrs": "TwoPersonDelivery",
  • "lasership_declared_value": "string",
  • "po_number": {
    },
  • "preferred_delivery_timeframe": "10001200",
  • "premium": true,
  • "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,
  • "signature_confirmation": "STANDARD"
}

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)

header Parameters
SHIPPO-API-VERSION
string

String used to pick a non-default API version to use

Responses
200
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

String used to pick a non-default API version to use

Request Body schema: application/json

Shipment details and contact info.

customs_declaration
string

ID of the Customs Declarations object for an international shipment.

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
object (AddressCreateRequest)

Address represents the address as retrieved from the database

object (AddressCreateRequest)

Address represents the address as retrieved from the database

required
object (AddressCreateRequest)

Address represents the address as retrieved from the database

async
boolean
required
Array of objects (ParcelCreateRequest)
Responses
201
post/shipments
Request samples
application/json
{
  • "customs_declaration": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "extra": {
    },
  • "metadata": "Customer ID 123456",
  • "shipment_date": "2021-03-22T12:00:00Z",
  • "address_from": {
    },
  • "address_return": {
    },
  • "address_to": {
    },
  • "async": true,
  • "parcels": [
    ]
}
Response samples
application/json
{
  • "customs_declaration": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "extra": {
    },
  • "metadata": "Customer ID 123456",
  • "shipment_date": "2021-03-22T12:00:00Z",
  • "address_from": {
    },
  • "address_return": {
    },
  • "address_to": {
    },
  • "carrier_accounts": [
    ],
  • "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": "SUCCESS",
  • "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

String used to pick a non-default API version to use

Responses
200
get/shipments/{ShipmentId}
Request samples
curl https://api.goshippo.com/shipments/7c47d12aa95a4cbb9d90c167cca7bea7 \
  -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "customs_declaration": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "extra": {
    },
  • "metadata": "Customer ID 123456",
  • "shipment_date": "2021-03-22T12:00:00Z",
  • "address_from": {
    },
  • "address_return": {
    },
  • "address_to": {
    },
  • "carrier_accounts": [
    ],
  • "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": "SUCCESS",
  • "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.

arrives_by
object
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.

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

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
number

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 is price is already included in the amount and amount_local fields on the Rate- do not add this field to them.

Array of objects (RateMessage)

An array containing elements of the following schema:
code (string): an identifier for the corresponding message (not always available)
message (string): a publishable message containing further information.

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

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",
  • "arrives_by": { },
  • "attributes": [
    ],
  • "carrier_account": "078870331023437cb917f5187429b093",
  • "currency": "USD",
  • "currency_local": "USD",
  • "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",
  • "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

String used to pick a non-default API version to use

Responses
200
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",
  • "arrives_by": { },
  • "attributes": [
    ],
  • "carrier_account": "078870331023437cb917f5187429b093",
  • "currency": "USD",
  • "currency_local": "USD",
  • "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",
  • "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

String used to pick a non-default API version to use

Responses
200
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

String used to pick a non-default API version to use

Responses
200
get/shipments/{ShipmentId}/rates/{CurrencyCode}
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.

eta
string

The estimated time of arrival according to the carrier.

label_file_type
string (LabelFileType)

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

messages
Array of objects

An array containing elements of the following schema:
code (string): an identifier for the corresponding message (not always available)
message (string): a publishable message containing further information.

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

Indicates the validity of the enclosing object

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

Date and time of last Transaction update.

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.

rate
string

ID of the Rate object for which a Label has to be obtained. Please note that only rates that are not older than 7 days can be purchased in order to ensure up-to-date pricing.

status
string

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

Indicates the high level status of the shipment: UNKNOWN, DELIVERED, TRANSIT, FAILURE, RETURNED.

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

String used to pick a non-default API version to use

Responses
200
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

String used to pick a non-default API version to use

Request Body schema: application/json

Examples.

One of:
async
boolean
label_file_type
string (LabelFileType)

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_A6" "ZPLII"