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
200
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, and FedEx only).)

Specify collection on delivery details (UPS, and FedEx 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"
}

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, and FedEx only).)

Specify collection on delivery details (UPS, and FedEx 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).

dangerous_goods_code
any

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

Enum: "01" "02" "03" "04" "05" "06" "07" "08" "09"
delivery_instructions
string

Specify delivery instructions. Up to 500 characters. (FedEx and OnTrac 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).

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.

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"
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",
  • "dangerous_goods_code": "01",
  • "delivery_instructions": "string",
  • "dry_ice": {
    },
  • "fulfillment_center": "string",
  • "insurance": {
    },
  • "is_return": true,
  • "lasership_attrs": "TwoPersonDelivery",
  • "lasership_declared_value": "string",
  • "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",
  • "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, and FedEx only).)

Specify collection on delivery details (UPS, and FedEx 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).

dangerous_goods_code
any

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

Enum: "01" "02" "03" "04" "05" "06" "07" "08" "09"
delivery_instructions
string

Specify delivery instructions. Up to 500 characters. (FedEx and OnTrac 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).

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.

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"
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",
  • "dangerous_goods_code": "01",
  • "delivery_instructions": "string",
  • "dry_ice": {
    },
  • "fulfillment_center": "string",
  • "insurance": {
    },
  • "is_return": true,
  • "lasership_attrs": "TwoPersonDelivery",
  • "lasership_declared_value": "string",
  • "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",
  • "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",
  • "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
  • "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
  • "servicelevel": {
    },
  • "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "test": true,
  • "zone": "1"
}

Retrieve a rate

Returns an existing rate using a rate object ID.

SecurityAPIKeyHeader
Request
path Parameters
RateId
required
string

Object ID of the rate

header Parameters
SHIPPO-API-VERSION
string

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",
  • "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
  • "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
  • "servicelevel": {
    },
  • "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
  • "test": true,
  • "zone": "1"
}

Retrieve shipment rates

Returns a paginated list of rates associated with a shipment

SecurityAPIKeyHeader
Request
path Parameters
ShipmentId
required
string

Object ID of the shipment to update

query Parameters
page
integer <int64>
Default: 1

The page number you want to select

results
integer <int64> <= 100
Default: 25

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

header Parameters
SHIPPO-API-VERSION
string

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"
metadata
string
rate
required
string
Responses
201
post/transactions
Request samples
application/json
{
  • "carrier_account": "b741b99f95e841639b54272834bc478c",
  • "label_file_type": "PDF",
  • "metadata": "Order ID",
  • "servicelevel_token": "usps_priority",
  • "shipment": {
    }
}
Response samples
application/json
{}

Retrieve a shipping label

Returns an existing transaction using an object ID.

SecurityAPIKeyHeader
Request
path Parameters
TransactionId
required
string

Object ID of the transaction to update

header Parameters
SHIPPO-API-VERSION
string

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

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

Customs Items

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

description
required
string

Text description of your item.

eccn_ear99
string

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

mass_unit
required
string (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.

net_weight
required
string

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

origin_country
required
string

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

quantity
required
integer <int64>

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

sku_code
string

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

tariff_number
string

The tariff number of the item.

value_amount
required
string

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

value_currency
required
string

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

object_created
string <date-time>

Date and time of object creation.

object_id
string

Unique identifier of the given object.

object_owner
string

Username of the user who created the object.

object_state
string (ObjectState)

Indicates the validity of the enclosing object

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

Date and time of last object update.

test
boolean

Indicates whether the object has been created in test mode.

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

List all customs items

Returns a list all customs items objects.

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

The page number you want to select

results
integer <int64> <= 100
Default: 25

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

header Parameters
SHIPPO-API-VERSION
string

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

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

Create a new customs item

Creates a new customs item object.

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

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

Request Body schema: application/json

CustomsItem details.

description
required
string

Text description of your item.

eccn_ear99
string

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

mass_unit
required
string (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.

net_weight
required
string

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

origin_country
required
string

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

quantity
required
integer <int64>

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

sku_code
string

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

tariff_number
string

The tariff number of the item.

value_amount
required
string

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

value_currency
required
string

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

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

Retrieve a customs item

Returns an existing customs item using an object ID

SecurityAPIKeyHeader
Request
path Parameters
CustomsItemId
required
string

Object ID of the customs item

query Parameters
page
integer <int64>
Default: 1

The page number you want to select

header Parameters
SHIPPO-API-VERSION
string

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

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

Customs Declarations

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

aes_itn
string

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

b13a_filing_option
string

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

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

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

certificate
string

Certificate reference of the shipment.

certify
required
boolean

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

certify_signer
required
string

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

commercial_invoice
string
contents_explanation
string

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

contents_type
required
string

Type of goods of the shipment.

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

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

eel_pfc
string

EEL / PFC type of the shipment. For most shipments from the US to CA, NOEEI_30_36 is applicable; for most other shipments from the US, NOEEI_30_37_a is applicable.

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

Exporter reference of an export shipment.

importer_reference
string

Importer reference of an import shipment.

is_vat_collected
any

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

invoice
string

Invoice reference of the shipment.

object (CustomsInvoicedCharges)

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

items
required
Array of strings

Distinct Parcel content items as Customs Items object_ids.

license
string

License reference of the shipment.

metadata
string

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

non_delivery_option
required
string

Indicates how the carrier should proceed in case the shipment can't be delivered.

Enum: "ABANDON" "RETURN"
notes
string

Additional notes to be included in the customs declaration.

object (CustomsExporterIdentification)

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

object (CustomsTaxIdentification)

Tax identification that may be required to ship in certain countries. Typically used to assess duties on goods that are crossing a border.

object_created
string <date-time>

Date and time of object creation.

object_id
string

Unique identifier of the given object.

object_owner
string

Username of the user who created the object.

object_state
string (ObjectState)

Indicates the validity of the enclosing object

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

Date and time of last object update.

test
boolean

Indicates whether the object has been created in test mode.

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

List all customs declarations

Returns a a list of all customs declaration objects

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

The page number you want to select

results
integer <int64> <= 100
Default: 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/customs/declarations
Request samples 
curl https://api.goshippo.com/customs/declarations/ \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
Response samples
application/json
{
  • "next": "baseurl?page=3&results=10",
  • "previous": "baseurl?page=1&results=10",
  • "results": [
    ]
}

Create a new customs declaration

Creates a new customs declaration object

SecurityAPIKeyHeader
Request
header Parameters
SHIPPO-API-VERSION
string

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

Request Body schema: application/json

CustomsDeclaration details.

aes_itn
string

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

b13a_filing_option
string

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

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

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

certificate
string

Certificate reference of the shipment.

certify
required
boolean

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

certify_signer
required
string

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

commercial_invoice
string
contents_explanation
string

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