Shippo: we make shipping simple

Shippo API References

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

All API URLs listed in this documentation are relative to https://api.goshippo.com/. For example, the /addresses/ resource is reachable at https://api.goshippo.com/addresses/.

Authentication

The API requires Shippo's token HTTP Authentication with your Shippo token (live or test). In order to authenticate properly, please put Authorization: ShippoToken <API_TOKEN> in your header. You can find your token on the Shippo API settings page.

For more information about authentication and test mode, please visit our Authentication guide.

The API is available via Secure Socket Layer (SSL) only. All requests to the Shippo API must use TLS version 1.2 or higher.

Request & Response Data

Request data is passed to the API by POSTing JSON objects with the appropriate key/value-pairs to the respective resource. The documentation for each API resource contains more details on the values accepted by a given resource.

Response data also formatted as JSON object. You can specify how many results per page are to be returned. For instance, /rates/?results=25 will return up to 25 results.

REST & Disposable Objects

The Shippo API is built around REST principles. Use POST requests to create objects, GET requests to retrieve objects, and PUT requests to update objects.

Only the Carrier Accounts object can be updated via PUT requests. All other objects such as Addresses, Parcels, Shipments, Rates, Transactions, Refunds, Customs Items, and Customs Declarations are disposable. This means that once you have created an object, you cannot change it. Instead, create a new one with the desired values.

API Endpoint

https://api.goshippo.com/

Documentation and Tutorials

First-time users and those looking for step-by-step tutorials, head to our full API documentation.

Client Framework and Libraries
The following libraries are available on our Shippo Github Account: Our community contributed libraries:
Questions?

Hit us up on Stack Overflow using the shippo tag. Or for account specific questions, we're happy to help at support@goshippo.com.

Addresses

Attributes
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
datetime		 Date and time of Address creation.
object_updated
datetime		 Date and time of last Address update. Since you cannot update Addresses after they were created, this time stamp reflects the time when the Address was changed by Shippo's systems for the last time, e.g., during the approximation of one or more values.
object_id
string		 Unique identifier of the given Address object. This ID is required to create a Shipment object.
object_owner
string		 Username of the user who created the Address object.
name
string		 First and Last Name of the addressee
company
string		 Company Name
street1
string		 First street line, 35 character limit. Usually street number and street name (except for DHL Germany, see street_no).
street_no
string		 Street number of the addressed building. This field can be included in street1 for all carriers except for DHL Germany.
street2
string		 Second street line, 35 character limit.
street3
string		 Third street line, 35 character limit. Only accepted for USPS international shipments, UPS domestic and UPS international shipments.
city
string		 Name of a city. When creating a Quote Address, sending a city is optional but will yield more accurate Rates. Please bear in mind that city names may be ambiguous (there are 34 Springfields in the US). Pass in a state or a ZIP code (see below), if known, it will yield more accurate results.
zip
string		 Postal code of an Address. When creating a Quote Addresses, sending a ZIP is optional but will yield more accurate Rates.
state
string		 State/Province values are required for shipments from/to the US, AU, and CA. UPS requires province for some countries (i.e Ireland). To receive more accurate quotes, passing this field is recommended. Most carriers only accept two or three character state abbreviations.
country
ISO 2 country code		 Example: 'US' or 'DE'. All accepted values can be found on the Official ISO Website. Sending a country is always required.
phone
string		 Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This increases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped.
email
email		 E-mail address of the contact person, RFC3696/5321-compliant.
is_residential
nullable boolean		 Indicates whether the address provided is a residential address or not.
validate
nullable boolean		 Set to true to validate Address object.
metadata
string		 A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
test
bool		 Indicates whether the object has been created in test mode.
validation_results
object		 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).
API Resource URL

https://api.goshippo.com/addresses/

Response Example
{
    "is_complete": true,
    "object_created": "2013-12-11T19:38:09.729Z",
    "object_updated": "2013-12-11T19:38:09.729Z",
    "object_id": "fcd9c72b564d4bfa8c03299ed6545132",
    "object_owner": "shippotle@goshippo.com",
    "validation_results": {},
    "name": "Shawn Ippotle",
    "company": "Shippo",
    "street_no": "",
    "street1": "215 Clayton St.",
    "street2": "",
    "street3":"",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "shippotle@goshippo.com",
    "is_residential":true,
    "metadata": "Customer ID 123456",
    "test": true
}

Create a new address

Creates a new address object.

Attributes
name
required for purchase		 string
company
optional		 string
street1
required for purchase		 string
street_no
optional		 string
street2
optional		 string
street3
optional		 string
city
required for purchase		 string
zip
required for purchase		 string
state
required for purchase for some countries		 string
country
required		 ISO 2 country code
phone
optional		 string
email email
is_residential
optional		 boolean
validate
optional		 boolean
metadata
optional		 string
API Resource URL

https://api.goshippo.com/addresses/

Example
// Create address object
var addressFrom  = shippo.address.create({
    "name":"Shawn Ippotle",
    "company":"Shippo",
    "street1":"215 Clayton St.",
    "city":"San Francisco",
    "state":"CA",
    "zip":"94117",
    "country":"US", // iso2 country code
    "phone":"+1 555 341 9393",
    "email":"shippotle@goshippo.com",
})
Response Example
{
   "is_complete": true,
   "object_created":"2014-07-09T02:19:13.174Z",
   "object_updated":"2014-07-09T02:19:13.174Z",
   "object_id":"d799c2679e644279b59fe661ac8fa488",
   "object_owner":"shippotle@goshippo.com",
   "validation_results": {},
   "name":"Shawn Ippotle",
   "company":"Shippo",
   "street_no": "",
   "street1":"215 Clayton St.",
   "street2":"",
   "street3":"",
   "city":"San Francisco",
   "state":"CA",
   "zip":"94117",
   "country":"US",
   "longitude": null,
   "latitude": null,
   "phone":"15553419393",
   "email":"shippotle@goshippo.com",
   "is_residential":true,
   "metadata":"Customer ID 123456"
}

Retrieve an address

Retrieve an existing address by object id.

API Resource URL

https://api.goshippo.com/addresses/<ADDRESS OBJECT ID>

Example
// Retrieve an existing address by object_id
shippo.address.retrieve('d799c2679e644279b59fe661ac8fa488');
Response Example
{
   "is_complete": true,
   "object_created":"2014-07-09T02:19:13.174Z",
   "object_updated":"2014-07-09T02:19:13.174Z",
   "object_id":"d799c2679e644279b59fe661ac8fa488",
   "object_owner":"shippotle@goshippo.com",
   "validation_results": {},
   "name":"Shawn Ippotle",
   "company":"Shippo",
   "street_no": "",
   "street1":"215 Clayton St.",
   "street2":"",
   "street3":"",
   "city":"San Francisco",
   "state":"CA",
   "zip":"94117",
   "country":"US",
   "longitude": null,
   "latitude": null,
   "phone":"15553419393",
   "email":"shippotle@goshippo.com",
   "is_residential":true,
   "metadata":"Customer ID 123456",
   "test": true
}

Validate an address

Validate an existing address by object id.

API Resource URL

https://api.goshippo.com/addresses/<ADDRESS OBJECT ID>/validate/

Example
shippo.address.validate("d799c2679e644279b59fe661ac8fa488", function(err, address) {
    // asynchronously called
});
Response Example
{
    "is_complete": false,
    "object_created": "2015-03-30T23:47:11.574Z",
    "object_updated": "2015-03-30T23:47:11.596Z", 
    "object_id": "67183b2e81e9421f894bfbcdc4236b16", 
    "object_owner": "shippotle@goshippo.com",
    "name": "Shawn Ippotle", 
    "company": "Shippo", 
    "street_no": "", 
    "street1": "215 CLAYTOON ST.", 
    "street2": "", 
    "street3":"",
    "city": "SAN FRANCISCO", 
    "state": "CA", 
    "zip": "94107", 
    "country": "US", 
    "longitude": null,
    "latitude": null,
    "phone": "", 
    "email": "shippotle@goshippo.com", 
    "is_residential": null,
    "metadata": "",
    "test": true,
    "validation_results": {
        "is_valid": false,
        "messages": [
            {
                "source": "USPS",
                "code": "Unknown Street",
                "type": "address_warning",
                "text": "City, State and ZIP Code are valid, but street address is not a match."
            }
        ]
    }
}

List all addresses

List all addresses.

API Resource URL

https://api.goshippo.com/addresses/

Example
// List all addresses
shippo.address.list();
Response Example
{
   "next":null,
   "previous":null,
   "results":[
      {
         "is_complete": true,
         "object_created":"2014-07-16T23:20:31.089Z",
         "object_updated":"2014-07-16T23:20:31.089Z",
         "object_id":"747207de2ba64443b645d08388d0309c",
         "object_owner":"shippotle@goshippo.com",
         "validation_results": {},
         "name":"Shawn Ippotle",
         "company":"Shippo",
         "street_no": "",
         "street1":"215 Clayton St.",
         "street2":"",
         "street3":"",
         "city":"San Francisco",
         "state":"CA",
         "zip":"94117",
         "country":"US",
         "longitude": null,
         "latitude": null,
         "phone":"15553419393",
         "email":"shippotle@goshippo.com",
         "is_residential":true,
         "metadata":"Customer ID 123456",
         "test": true
      },
      {...},
      {...}
   ]
}

Parcels

Attributes
object_state
"VALID"		 A Parcel will only be valid when all required values have been sent and validated successfully.
object_created
datetime		 Date and time of Parcel creation.
object_updated
datetime		 Date and time of last Parcel update. Since you cannot update Parcels after they were created, this time stamp reflects the time when the Parcel was changed by Shippo's systems for the last time, e.g., during sorting the dimensions given.
object_id
string		 Unique identifier of the given Parcel object. This ID is required to create a Shipment object.
object_owner
string		 Username of the user who created the Parcel object.
length
decimal (10,4)		 Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.
width
decimal (10,4)		 Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.
height
decimal (10,4)		 Height of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.
distance_unit
"cm"
"in"
"ft"
"mm"
"m"
"yd"		 The unit used for length, width and height.
weight
decimal (10,4)		 Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.
mass_unit
"g"
"oz"
"lb"
"kg"		 The unit used for weight.
template
string		 A parcel template is a predefined package used by one or multiple carriers. See the parcel template table for all available values and the corresponding tokens. When a template is given, the parcel dimensions do not have to be sent. The dimensions below will instead be used. The parcel weight is not affected by the use of a template.
metadata
string		 A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
extra
object		 An object holding optional extra services to be requested for each parcel in a multi-piece shipment. See the Parcel Extra table below for all available services.
test
bool		 Indicates whether the object has been created in test mode.
API Resource URL

https://api.goshippo.com/parcels/

Response Example
{
   "object_state":"VALID",
   "object_created": "2013-12-11T19:38:09.729Z",
   "object_updated": "2013-12-11T19:38:09.729Z",
   "object_id": "fcd9c72b564d4bfa8c03299ed6545132",
   "object_owner": "shippotle@goshippo.com",
   "template": null,
   "length": "20",
   "width": "15",
   "height": "12",
   "distance_unit": "in",
   "weight": "5",
   "mass_unit": "lb",
   "metadata": "Customer ID 123456",
   "extra": {},
   "test": true
}

Parcel Extras

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

COD
object		 Specify collection on delivery details (UPS, and FedEx only).
COD.amount
string		 Amount to be collected.
COD.currency
ISO 4217 currency code (string)		 Currency for the amount to be collected. Currently only USD is supported for FedEx and UPS.
COD.payment_method
"SECURED_FUNDS"
"CASH"
"ANY"		 Secured funds include money orders, certified cheques and others (see UPS and FedEx for details). If no payment_method inputted the value defaults to "ANY".)
insurance
object		 Specify collection on delivery details (UPS, FedEx and UDS only).
insurance.amount
string		 Amount to be collected.
insurance.currency
ISO 4217 currency code (string)		 Currency for the amount to be collected. Currently only USD is supported for FedEx and UPS.
insurance.provider
"FEDEX"
"UPS"
"UDS"		 Specify the carrier insurance to have Insurance provided by the carrier directly.
insurance.content
string		 Specify package content for insurance.

Create a new parcel

Creates a new parcel object.

Attributes
length
required		 decimal (10,4)
width
required		 decimal (10,4)
height
required		 decimal (10,4)
distance_unit
required		 "cm"
"in"
"ft"
"mm"
"m"
"yd"
weight
required		 decimal (10,4)
mass_unit
required		 "g"
"oz"
"lb"
"kg"
template
optional		 string
extra
optional		 object
metadata
optional		 string
API Resource URL

https://api.goshippo.com/parcels/

Example
// Create parcel object
var parcel = shippo.parcel.create({
    "length": "5",
    "width": "5",
    "height": "5",
    "distance_unit": "in",
    "weight": "2",
    "mass_unit": "lb",
})
Response Example
{
   "object_state":"VALID",
   "object_created":"2014-07-08T23:19:19.565Z",
   "object_updated":"2014-07-08T23:19:19.565Z",
   "object_id":"7df2ecf8b4224763ab7c71fae7ec8274",
   "object_owner":"shippotle@goshippo.com",
   "template":null,
   "length":"5",
   "width":"5",
   "height":"5",
   "distance_unit":"cm",
   "weight":"2",
   "mass_unit":"lb",
   "metadata":"Customer ID 123456",
   "test": true,
   "extra": {
      "reference_1": "",
      "reference_2": ""
   },
   "line_items": []
}

Retrieve an existing parcel

Retrieve an existing parcel by object id.

API Resource URL

https://api.goshippo.com/parcels/<PARCEL OBJECT ID>

Example
// Retrieve an existing parcel by object_id
shippo.parcel.retrieve('fcd9c72b564d4bfa8c03299ed6545132');
Response Example
{
   "object_state":"VALID",
   "object_created": "2013-12-11T19:38:09.729Z",
   "object_updated": "2013-12-11T19:38:09.729Z",
   "object_id": "fcd9c72b564d4bfa8c03299ed6545132",
   "object_owner": "shippotle@goshippo.com",
   "template": null,
   "length": "20",
   "width": "15",
   "height": "12",
   "distance_unit": "in",
   "weight": "5",
   "mass_unit": "lb",
   "metadata": "Customer ID 123456",
   "extra": {},
   "line_items": [],
   "test": true
}

List all parcels

List all parcel objects.

API Resource URL

https://api.goshippo.com/parcels/

Example
// List all carrier accounts
shippo.parcel.list();
Response Example
{
   "next":null,
   "previous":null,
   "results":[
      {
         "object_state":"VALID",
         "object_created": "2013-12-11T19:38:09.729Z",
         "object_updated": "2013-12-11T19:38:09.729Z",
         "object_id": "fcd9c72b564d4bfa8c03299ed6545132",
         "object_owner": "shippotle@goshippo.com",
         "template": null,
         "length": "20",
         "width": "15",
         "height": "12",
         "distance_unit": "in",
         "weight": "5",
         "mass_unit": "lb",
         "metadata": "Customer ID 123456",
         "extra": {},
         "line_items": [],
         "test": true
      },
      {...},
      {...}
   ]
}

Shipments

The heart of the Shippo API, a shipment is made up of "to" and "from" addresses and the parcel to be shipped. Once created, a shipment object can be used to retrieve shipping rates and purchase a shipping label.

Attributes
status
"WAITING"
"QUEUED"
"SUCCESS"
"ERROR"		 "Waiting" shipments have been successfully submitted but not yet been processed. "Queued" shipments are currently being processed. "Success" shipments have been processed successfully, meaning that rate generation has concluded. "Error" does not occur currently and is reserved for future use.
object_created
datetime		 Date and time of Shipment creation.
object_updated
datetime		 Date and time of last Shipment update.
object_id
string		 Unique identifier of the given Shipment object.
object_owner
string		 Username of the user who created the Shipment object.
address_from
string		 ID of the Address object that should be used as sender Address.
address_to
string		 ID of the Address object that should be used as recipient Address.
parcels
array		 Array of IDs of the Parcel objects to be shipped.
shipment_date
datetime (ISO 8601 date)		 Date the shipment will be tendered to the carrier. Must be in the format "2014-01-18T00:35:03.463Z". Defaults to current date and time if no value is provided. Please note that some carriers require this value to be in the future, on a working day, or similar.
address_return
string		 ID of the Address object where the shipment will be sent back to if it is not delivered (Only available for UPS, USPS, and Fedex shipments).
If this field is not set, your shipments will be returned to the address_from.
customs_declaration
string		 ID of the Customs Declarations object for an international shipment.
carrier_accounts
array		 An array of object_ids of the carrier account objects to be used for getting shipping rates for this shipment. If no carrier account object_ids are set in this field, Shippo will attempt to generate rates using all the carrier accounts that have the 'active' field set.
metadata
string		 A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
extra
object		 An object holding optional extra services to be requested. See the Shipment Extra table below for all available services.
rates
array		 An array with all available rates. If async has been set to false in the request, this will be populated with all available rates in the response. Otherwise rates will be created asynchronously and this array will initially be empty.
messages
array		 An array containing elements of the following schema:
"code" (string): an identifier for the corresponding message (not always available")
"message" (string): a publishable message containing further information.
test
bool		 Indicates whether the object has been created in test mode.
API Resource URL

Response Example
{
    "status": "SUCCESS",
    "object_created": "2013-12-01T06:24:20.121Z",
    "object_updated": "2013-12-01T06:24:20.121Z",
    "object_id": "5e40ead7cffe4cc1ad45108696162e42",
    "object_owner": "shippotle@goshippo.com",
    "address_from":{
        "object_id": "fdabf0abb93c4460b60aa596116872a7",
        "is_complete": true,
        "validation_results": {},
        "name": "Mrs Hippo",
        "street1": "1092 Indian Summer Ct",
        "city": "San Jose",
        "state": "CA",
        "zip": "95122",
        "country": "US",
        "phone": "4159876543",
        "email": "mrshippo@goshippo.com"
    },
    "address_to":{
        "object_id": "0476d70c612a423f9509ba5f807569db",
        "is_complete": true,
        "validation_results": {},
        "name": "Mr Hippo",
        "street1": "965 Mission St #572",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94103",
        "country": "US",
        "phone": "4151234567",
        "email": "mrhippo@goshippo.com"
    },
    "address_return":{
        "object_id": "fdabf0abb93c4460b60aa596116872a7",
        "is_complete": true,
        "validation_results": {},
        "name": "Mrs Hippo",
        "street1": "1092 Indian Summer Ct",
        "city": "San Jose",
        "state": "CA",
        "zip": "95122",
        "country": "US",
        "phone": "4159876543",
        "email": "mrshippo@goshippo.com"
    },
    "parcels":[{
        "object_id": "ec952343dd4843c39b42aca620471fd5",
        "length": "10",
        "width": "15",
        "height": "10",
        "distance_unit": "in",
        "weight": "1",
        "mass_unit": "lb"
    }],
    "shipment_date": "2013-12-03T12:00:00.000Z",
    "extra":{
      "insurance": {
        "amount": "",
        "currency": ""
      },
      "reference_1":"",
      "reference_2":""
    },
    "customs_declaration": "",
    "rates": [
        {
            "object_created": "2013-12-01T06:24:21.121Z",
            "object_id": "545ab0a1a6ea4c9f9adb2512a57d6d8b",
            "object_owner": "shippotle@goshippo.com",
            "shipment": "5e40ead7cffe4cc1ad45108696162e42",
            "attributes": [],
            "amount": "5.50",
            "currency": "USD",
            "amount_local": "5.50",
            "currency_local": "USD",
            "included_insurance_price": null,
            "provider": "UPS",
            "provider_image_75": "https://cdn2.goshippo.com/providers/75/UPS.png",
            "servicelevel": {
              "name": "Saver®",
              "token":"ups_saver",
              "terms": "",
              "extended_token": "ups_saver_eu",
              "parent_servicelevel": {
                  "name": "Saver®",
                  "token": "ups_saver",
                  "terms": "",
                  "extended_token": "ups_saver"
              }
            },
            "estimated_days": 2,
            "arrives_by": null,
            "duration_terms": "Delivery in 1 to 3 business days.",
            "messages": [],
            "carrier_account": "078870331023437cb917f5187429b093",
            "test": true
        },
        ...
    ],
    "carrier_accounts": [],
    "metadata": "Customer ID 123456",
    "messages": [],
    "test": true
}

Shipment Extras

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

signature_confirmation
"STANDARD"
"ADULT"
"CERTIFIED"
"INDIRECT"
"CARRIER_CONFIRMATION"		 Request standard or adult signature confirmation. You can alternatively request Certified Mail (USPS only) or Indirect signature (FedEx only) or Carrier Confirmation (Deutsche Post only)
authority_to_leave
boolean		 Request “true” to give carrier permission to leave the parcel in a safe place if no one answers the door (where supported). When set to “false”, if no one is available to receive the item, the parcel will not be left (*surcharges may be applicable).
saturday_delivery
boolean		 Marks shipment as to be delivered on a Saturday.
bypass_address_validation
boolean		 Bypasses address validation (USPS, UPS, & LaserShip only).
request_retail_rates
boolean		 Returns retail rates instead of account-based rates (UPS and FedEx only).
customer_branch
string		 Specify customer branch (Lasership only).
premium
boolean		 Add premium service to a shipment (DHL Germany international shipments only).
preferred_delivery_timeframe
"10001200"
"12001400"
"14001600"
"16001800"
"18002000"
"19002100"		 Required for DHL Germany Paket Sameday. Designates a desired timeframe for delivery. Format is HHMMHHMM
lasership_attrs
"TwoPersonDelivery"
"Explosive"
"Hazmat"
"ControlledSubstance"
"Refrigerated"
"Perishable"
"NoRTS"		 Specify Lasership Attributes (Lasership only). Multiple options accepted.
lasership_declared_value
string		 Declared value (Lasership only). Defaults to "50.00".
container_type
string		 Specify container type.
billing
object		 Specify billing details (UPS, FedEx, and DHL Germany only).
billing.type
"SENDER"
"RECIPIENT"
"THIRD_PARTY"
"THIRD_PARTY_CONSIGNEE"		 Party to be billed. (Leave blank for DHL Germany.)
billing.account
string		 Account number to be billed. (For DHL Germany, leave this field blank.)
billing.zip
string		 ZIP code of account number to be billed (required for UPS if there is a zip on the billing account).
billing.country
string		 Country iso2 code of account number to be billed (required for UPS third party billing only).
billing.participation_code
string		 2 digit code used to override your default participation code associated with your DHL Germany account.
COD
object		 Specify collection on delivery (DHL Germany, FedEx, GLS, OnTrac, and UPS only).
COD.amount
string		 Amount to be collected.
COD.currency
ISO 4217 currency code (string)		 Currency for the amount to be collected. Currently only USD is supported for FedEx and UPS.
COD.payment_method
"SECURED_FUNDS"
"CASH"
"ANY"		 Secured funds include money orders, certified cheques and others (see UPS and FedEx for details). If no payment_method inputted the value defaults to "ANY".)
alcohol
object		 Indicates that a shipment contains Alcohol (Fedex, UPS and Lasership only).
alcohol.contains_alcohol
boolean		 Mandatory for Fedex, UPS and Lasership. Specifies that the package contains Alcohol.
alcohol.recipient_type
"licensee", "consumer"		 Mandatory for Fedex only. License type of the recipient of the Alcohol Package.
dry_ice
object		 Specify that the package contains Dry Ice (FedEx, UPS and Lasership only).
dry_ice.contains_dry_ice
boolean		 Mandatory. Specifies that the package contains Dry Ice.
dry_ice.weight
decimal		 Mandatory. Units must be in Kilograms. Cannot be greater than package weight.
insurance
object		 Specify amount, content, provider, and currency of shipment insurance (UPS, FedEx and Ontrac only).
insurance.amount
decimal		 Insured Amount.
insurance.currency
ISO 4217 currency code (string)		 Currency for the amount to be collected.
insurance.content
string		 Specify package content for insurance.
insurance.provider
"FEDEX"
"UPS"
"ONTRAC"		 Specify the carrier insurance to have Insurance provided by the carrier directly, not by Shippo's 3rd-party insurance. Specify a value here ONLY if you do not want to use Shippo's 3rd-party insurance.
dangerous_goods_code
"01"
"02"
"03"
"04"
"05"
"06"
"07"
"08"
"09"		 Dangerous Goods Code (DHL eCommerce only). See Category Codes
is_return
boolean		 This field specifies if it is a scan-based return shipment. See the Create a return shipment section for more details.
reference_1
string		 Optional text to be printed on the shipping label. Up to 50 characters. For APG this field is required and used as order id.
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.
return_service_type
"PRINT_AND_MAIL"
"ATTEMPT_1"
"ATTEMPT_3"
"ELECTRONIC_LABEL"		 Request additional return option for return shipments (UPS only).
qr_code_requested
boolean		 Request a QR code for a given transaction when creating a shipping label (USPS domestic and Evri UK only).
ancillary_endorsement
"FORWARDING_SERVICE_REQUESTED"
"RETURN_SERVICE_REQUESTED"		 Specify an ancillary service endorsement to provide the USPS with instructions on how to handle undeliverable-as-addressed pieces (DHL eCommerce only).
carbon_neutral
boolean		 Request carbon offsets by passing true (UPS only).
delivery_instructions
string		 Specify delivery instructions. Up to 500 characters. (FedEx, OnTrac and LaserShip only).
fulfillment_center
string		 The fulfilment center where the package originates from.
carrier_hub_id
string		 Identifies the carrier injection site.
critical_pull_time
string		 Carrier arrival time to pickup packages from the fulfillment center. UTC format:
'%Y-%m-%dT%H:%M:%SZ'
carrier_hub_travel_time
integer		 Travel time in hours from fulfillment center to carrier injection site.

Create a new shipment

Creates a new shipment object.

Attributes
address_from
required		 string or object
address_to
required		 string or object
parcels
required		 string, object, or array
shipment_date
optional		 datetime
address_return
optional		 string or object
customs_declaration
optional		 string or object
extra
optional		 object
metadata
optional		 string, up to 50 characters.
async
optional		 boolean
API Resource URL

https://api.goshippo.com/shipments/

Example
// Create shipment object
var shipment = shippo.shipment.create({
    "address_from": addressFrom,
    "address_to": addressTo,
    "parcels": parcel,
    "async": true
})
Response Example
{
   "object_created":"2014-07-17T00:04:06.163Z",
   "object_updated":"2014-07-17T00:04:06.163Z",
   "object_id":"89436997a794439ab47999701e60392e",
   "object_owner":"shippotle@goshippo.com",
   "status":"SUCCESS",
   "address_from":{
      "object_id": "fdabf0abb93c4460b60aa596116872a7",
      "validation_results": {},
      "is_complete": true,
      "name": "Mrs Hippo",
      "company": "Shippo",
      "street_no": "",
      "street1": "1092 Indian Summer Ct",
      "street2": "",
      "street3": "",
      "city": "San Jose",
      "state": "CA",
      "zip": "95122",
      "country": "US",
      "phone": "4159876543",
      "email": "mrshippo@goshippo.com",
      "is_residential": null
   },
   "address_to":{
      "object_id": "0476d70c612a423f9509ba5f807569db",
      "is_complete": true,
      "validation_results": {},
      "name": "Mr Hippo",
      "company": "",
      "street_no": "",
      "street1": "965 Mission St #572",
      "street2": "",
      "street3": "",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94103",
      "country": "US",
      "phone": "4151234567",
      "email": "mrhippo@goshippo.com",
      "is_residential": null
   },
  "address_return":{
      "object_id": "fdabf0abb93c4460b60aa596116872a7",
      "is_complete": true,
      "validation_results": {},
      "name": "Mrs Hippo",
      "company": "Shippo",
      "street_no": "",
      "street1": "1092 Indian Summer Ct",
      "street2": "",
      "street3": "",
      "city": "San Jose",
      "state": "CA",
      "zip": "95122",
      "country": "US",
      "phone": "4159876543",
      "email": "mrshippo@goshippo.com",
      "is_residential": null
   },
  "parcels":[{
      "object_id": "7df2ecf8b4224763ab7c71fae7ec8274",
      "length": "10",
      "width": "15",
      "height": "10",
      "distance_unit": "in",
      "weight": "1",
      "mass_unit": "lb"
   }],
   "shipment_date":"2013-12-03T12:00:00Z",
   "extra":{
      "insurance": {
        "amount": "",
        "currency": ""
      },
      "reference_1":"",
      "reference_2":""
   },
   "alternate_address_to": null,
   "customs_declaration":null,
   "rates": [
        {
            "object_created": "2014-07-17T00:04:06.263Z",
            "object_id": "545ab0a1a6ea4c9f9adb2512a57d6d8b",
            "object_owner": "shippotle@goshippo.com",
            "shipment": "89436997a794439ab47999701e60392e",
            "attributes": [],
            "amount": "5.50",
            "currency": "USD",
            "amount_local": "5.50",
            "currency_local": "USD",
            "included_insurance_price": null,
            "provider": "USPS",
            "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
            "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
            "servicelevel": {
              "name": "Priority Mail",
              "token":"usps_priority",
              "terms": "",
              "extended_token": "usps_priority",
              "parent_servicelevel": null
            },
            "estimated_days": 2,
            "arrives_by": null,
            "duration_terms": "Delivery in 1 to 3 business days.",
            "messages": [],
            "carrier_account": "078870331023437cb917f5187429b093",
            "test": true,
            "zone": "20"
        },
        ...
    ],
   "carrier_accounts": [],
   "messages":[],
   "metadata":"Customer ID 123456",
   "test": true
}

Retrieve an existing shipment

Retrieve an existing shipment by object id.

API Resource URL

https://api.goshippo.com/shipments/<SHIPMENT OBJECT ID>

Example
// Retrieve an existing shipment by object_id
shippo.shipment.retrieve('89436997a794439ab47999701e60392e');
Response Example
{
   "object_created":"2014-07-17T00:04:06.163Z",
   "object_updated":"2014-07-17T00:06:05.416Z",
   "object_id":"89436997a794439ab47999701e60392e",
   "object_owner":"shippotle@goshippo.com",
   "status":"SUCCESS",
   "address_from":{
     "object_id": "fdabf0abb93c4460b60aa596116872a7",
     "validation_results": {},
     "is_complete": true,
     "name": "Mrs Hippo",
     "company": "Shippo",
     "street_no": "",
     "street1": "1092 Indian Summer Ct",
     "street2": "",
     "street3": "",
     "city": "San Jose",
     "state": "CA",
     "zip": "95122",
     "country": "US",
     "phone": "4159876543",
     "email": "mrshippo@goshippo.com",
     "is_residential": null
   },
   "address_to":{
     "object_id": "0476d70c612a423f9509ba5f807569db",
     "is_complete": true,
     "validation_results": {},
     "name": "Mr Hippo",
     "company": "",
     "street_no": "",
     "street1": "965 Mission St #572",
     "street2": "",
     "street3": "",
     "city": "San Francisco",
     "state": "CA",
     "zip": "94103",
     "country": "US",
     "phone": "4151234567",
     "email": "mrhippo@goshippo.com",
     "is_residential": null
   },
   "address_return": {
     "object_id": "fdabf0abb93c4460b60aa596116872a7",
     "is_complete": true,
     "validation_results": {},
     "name": "Mrs Hippo",
     "company": "Shippo",
     "street_no": "",
     "street1": "1092 Indian Summer Ct",
     "street2": "",
     "street3": "",
     "city": "San Jose",
     "state": "CA",
     "zip": "95122",
     "country": "US",
     "phone": "4159876543",
     "email": "mrshippo@goshippo.com",
     "is_residential": null
   },
   "parcels":[{
        "object_id": "7df2ecf8b4224763ab7c71fae7ec8274",
        "length": "10",
        "width": "15",
        "height": "10",
        "distance_unit": "in",
        "weight": "1",
        "mass_unit": "lb"
   }],
   "shipment_date":"2013-12-03T12:00:00Z",
   "extra":{
      "insurance": {
        "amount": "",
        "currency": ""
      },
      "reference_1":"",
      "reference_2":""
   },
   "alternate_address_to": null,
   "customs_declaration":null,
   "rates": [
        {
            "object_created": "2014-07-17T00:04:06.263Z",
            "object_id": "545ab0a1a6ea4c9f9adb2512a57d6d8b",
            "object_owner": "shippotle@goshippo.com",
            "shipment": "89436997a794439ab47999701e60392e",
            "attributes": [],
            "amount": "5.50",
            "currency": "USD",
            "amount_local": "5.50",
            "currency_local": "USD",
            "included_insurance_price": null,
            "provider": "USPS",
            "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
            "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
            "servicelevel": {
              "name":"Priority Mail Express",
              "token":"usps_priority_express",
              "terms":"",
              "extended_token": "usps_priority_express",
              "parent_servicelevel": null
            },
            "estimated_days": 2,
            "arrives_by": null,
            "duration_terms": "Delivery in 1 to 3 business days.",
            "messages": [],
            "carrier_account": "078870331023437cb917f5187429b093",
            "test": true,
            "zone": "20"
        },
        ...
    ],
   "carrier_accounts": [],
   "messages":[
      {
         "source":"UPS",
         "code":"",
         "text":"RatedShipmentWarning: User Id and Shipper Number combination is not qualified to receive negotiated rates."
      }
   ],
   "metadata":"Customer ID 123456",
   "test": true
}

List all shipments

List all shipment objects.

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

Optional path parameters:

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

Date format examples:

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

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

API Resource URL

https://api.goshippo.com/shipments/

Example
// List all shipments
shippo.shipment.list();
Response Example
{
   "next":"https://api.goshippo.com/shipments/?page=2",
   "previous":null,
   "results":[
      {
         "object_created":"2014-07-17T00:04:06.163Z",
         "object_updated":"2014-07-17T00:06:05.416Z",
         "object_id":"89436997a794439ab47999701e60392e",
         "object_owner":"shippotle@goshippo.com",
         "status":"SUCCESS",
         "address_from":{
            "object_id": "fdabf0abb93c4460b60aa596116872a7",
            "validation_results": {},
            "is_complete": true,
            "name": "Mrs Hippo",
            "company": "Shippo",
            "street_no": "",
            "street1": "1092 Indian Summer Ct",
            "street2": "",
            "street3": "",
            "city": "San Jose",
            "state": "CA",
            "zip": "95122",
            "country": "US",
            "phone": "4159876543",
            "email": "mrshippo@goshippo.com",
            "is_residential": null
         },
         "address_to":{
            "object_id": "0476d70c612a423f9509ba5f807569db",
            "is_complete": true,
            "validation_results": {},
            "name": "Mr Hippo",
            "company": "",
            "street_no": "",
            "street1": "965 Mission St #572",
            "street2": "",
            "street3": "",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94103",
            "country": "US",
            "phone": "4151234567",
            "email": "mrhippo@goshippo.com",
            "is_residential": null
         },
         "parcels":[{
            "object_id": "7df2ecf8b4224763ab7c71fae7ec8274",

            "length": "10",
            "width": "15",
            "height": "10",
            "distance_unit": "in",
            "weight": "1",
            "mass_unit": "lb"
         }],
         "shipment_date":"2013-12-03T12:00:00Z",
         "address_return":{
            "object_id": "fdabf0abb93c4460b60aa596116872a7",
            "is_complete": true,
            "validation_results": {},
            "name": "Mrs Hippo",
            "company": "Shippo",
            "street_no": "",
            "street1": "1092 Indian Summer Ct",
            "street2": "",
            "street3": "",
            "city": "San Jose",
            "state": "CA",
            "zip": "95122",
            "country": "US",
            "phone": "4159876543",
            "email": "mrshippo@goshippo.com",
            "is_residential": null
         },
        "extra":{
            "insurance": {
              "amount": "",
              "currency": ""
            },
            "reference_1":"",
            "reference_2":""
         },
         "alternate_address_to": null,
         "customs_declaration":null,
         "rates": [
           {
               "object_created": "2014-07-17T00:04:06.263Z",
               "object_id": "545ab0a1a6ea4c9f9adb2512a57d6d8b",
               "object_owner": "shippotle@goshippo.com",
               "shipment": "89436997a794439ab47999701e60392e",
               "attributes": [],
               "amount": "5.50",
               "currency": "USD",
               "amount_local": "5.50",
               "currency_local": "USD",
               "provider": "USPS",
               "included_insurance_price": null,
               "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
               "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
               "servicelevel": {
                 "name": "Priority Mail",
                 "token":"usps_priority",
                 "terms": "",
                 "extended_token": "usps_priority",
                 "parent_servicelevel": null
               },
               "estimated_days": 2,
               "arrives_by": null,
               "duration_terms": "Delivery in 1 to 3 business days.",
               "messages": [],
               "carrier_account": "078870331023437cb917f5187429b093",
               "test": true,
               "zone": "20"
           },
           ...
         ],
         "carrier_accounts": [],
         "messages":[
            {
               "source":"UPS",
               "code":"",
               "text":"RatedShipmentWarning: Ship To Address Classification is changed from Commercial to Residential"
            }
         ],
         "metadata":"Customer ID 123456",
         "test": true
      },
      {...},
      {...}
   ]
}

Rates

A rate is an available service of a shipping provider for a given shipment, typically including the price and transit time.

Attributes
object_created
datetime		 Date and time of Rate creation.
object_id
string		 Unique identifier of the given Rate object.
object_owner
string		 Username of the user who created the rate object.
attributes
array		 An array containing specific attributes of this Rate in context of the entire shipment. Attributes can be assigned 'CHEAPEST', 'FASTEST', or 'BESTVALUE'.
amount_local
decimal		 Final Rate price, expressed in the currency used in the recipient's country.
currency_local
ISO 4217 currency code		 Currency used in the recipient's country, refers to "amount_local". The official ISO 4217 currency codes are used, e.g. "USD" or "EUR".
amount
decimal		 Final Rate price, expressed in the currency used in the sender's country.
currency
ISO 4217 currency code (string)		 Currency used in the sender's country, refers to "amount". The official ISO 4217 currency codes are used, e.g. "USD" or "EUR".
included_insurance_price
decimal		 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.
provider
string		 Carrier offering the rate, e.g., "FedEx" or "Deutsche Post DHL".
provider_image_75
string		 URL to the provider logo with max. dimensions of 75*75px. Please refer to the provider's Logo Usage Guidelines before using the logo.
provider_image_200
string		 URL to the provider logo with max. dimensions of 200*200px. Please refer to the provider's Logo Usage Guidelines before using the logo.
servicelevel
object		 Contains details regarding the service level for the given rate.
servicelevel.name
string		 Name of the Rate's servicelevel, e.g. "International Priority" or "Standard Post". A servicelevel commonly defines the transit time of a Shipment (e.g., Express vs. Standard), along with other properties. These names vary depending on the provider.
servicelevel.token
string		 Token of the Rate's servicelevel, e.g. "usps_priority" or "fedex_ground". See servicelevels.
servicelevel.terms
string		 Further clarification of the service.
servicelevel.extended_token
string		 Unique, extended version of the Service Level "token". Guaranteed to be unique across all Service Levels, and may help offer insight into the specific Service Level it describes.
servicelevel.parent_servicelevel
object		 Used for some Service Levels to link to the more "generic" version of this Service Level - for example, if this Service Level is a variation specific to shipments to Europe("ups_saver_eu"), the "parent" is the fully generic version ("ups_saver"). Helpful when displaying Service Levels to users. Has the same structure of the servicelevel - "name", "token", "terms", and "extended_token", or it is otherwise null.
estimated_days
integer		 Estimated transit time (duration) in days of the Parcel at the given servicelevel. Please note that this is not binding, but only an average value as given by the provider. Shippo is not able to guarantee any transit times.
duration_terms
string		 Further clarification of the transit times. Often, this includes notes that the transit time as given in "days" is only an average, not a guaranteed time.
carrier_account
string		 Object ID of the carrier account that has been used to retrieve the rate.
zone
string		 The parcel's transit zone token. These tokens can vary depending on the provider.
messages
array		 An array containing elements of the following schema:
"code" (string): an identifier for the corresponding message (not always available")
"message" (string): a publishable message containing further information.
test
bool		 Indicates whether the object has been created in test mode.
API Resource URL

https://api.goshippo.com/shipments/<SHIPMENT OBJECT ID>/rates/[<CURRENCY CODE>/]

Response Example
{
    "object_created":"2013-12-09T01:56:52.780Z",
    "object_id":"cf6fea899f1848b494d9568e8266e076",
    "object_owner":"shippotle@goshippo.com",
    "shipment":"5e40ead7cffe4cc1ad45108696162e42",
    "attributes":[],
    "amount_local":"5.35",
    "currency_local":"USD",
    "amount":"5.35",
    "currency":"USD",
    "included_insurance_price": "1.05",
    "provider":"UPS",
    "provider_image_75":"https://cdn2.goshippo.com/providers/75/UPS.png",
    "provider_image_200":"https://cdn2.goshippo.com/providers/200/UPS.png",
    "servicelevel": {
      "name":"Saver®",
      "token":"ups_saver",
      "terms":"",
      "extended_token": "ups_saver_eu",
      "parent_servicelevel": {
          "name": "Saver®",
          "token": "ups_saver",
          "terms": "",
          "extended_token": "ups_saver"
      }
    },
    "estimated_days":2,
    "duration_terms":"Delivery within 1, 2, or 3 days based on where your package started and where it’s being sent.",
    "carrier_account":"b741b99f95e841639b54272834bc478c",
    "zone":"1",
    "messages":[],
    "test":true
}

Get shipping rates

Each valid shipment object will automatically trigger the calculation of all available rates. Depending on your shipment data, there may be none, one or multiple rates.

By default, the calculated Rates will return the price in two currencies under the amount and amount_local keys, respectively. The amount key will contain the price of a rate expressed in the currency that is used in the country from which parcel originates, and the amount_local key will contain the price expressed in the currency that is used in the country the parcel is shipped to. You can request rates with prices expressed in a different currency by adding the desired currency code in the end of the resource URL. The full list of supported currencies along with their codes can be viewed on open exchange rates.

Note: re-requesting the rates with a different currency code will re-queue the shipment (i.e. set the Shipment's status to QUEUED) and the converted currency rates will only be available when the Shipment's status is set to SUCCESS.

API Resource URL

https://api.goshippo.com/shipments/<SHIPMENT OBJECT ID>/rates/[<CURRENCY CODE>/]

Example
// Get rates for shipment by object_id
shippo.shipment.rates('5e40ead7cffe4cc1ad45108696162e42');
Response Example
{
   "next":null,
   "previous":null,
   "results":[
      {
         "object_created":"2014-07-17T00:04:10.118Z",
         "object_id":"ee81fab0372e419ab52245c8952ccaeb",
         "object_owner":"shippotle@goshippo.com",
         "shipment":"89436997a794439ab47999701e60392e",
         "attributes":[
            "CHEAPEST",
            "BESTVALUE"
         ],
         "amount":"5.35",
         "currency":"USD",
         "amount_local":"5.35",
         "currency_local":"USD",
         "included_insurance_price": null,
         "provider":"USPS",
         "provider_image_75":"https://cdn2.goshippo.com/providers/75/USPS.png",
         "provider_image_200":"https://cdn2.goshippo.com/providers/200/USPS.png",
         "servicelevel": {
            "name":"Priority Mail",
            "token":"usps_priority",
            "terms":"",
            "extended_token": "usps_priority",
            "parent_servicelevel": null
         },
         "estimated_days":1,
         "arrives_by": null,
         "duration_terms":"Delivery within 1, 2, or 3 days based on where your package started and where it’s being sent.",
         "carrier_account": "b741b99f95e841639b54272834bc478c",
         "zone":"1",
         "messages":[],
         "test": true
      },
      {
         "object_created":"2014-07-17T00:04:10.334Z",
         "object_id":"fd31f301b61c49048f861573d4364ff6",
         "object_owner":"shippotle@goshippo.com",
         "shipment":"89436997a794439ab47999701e60392e",
         "attributes":[],
         "amount":"16.03",
         "currency":"USD",
         "amount_local":"16.03",
         "currency_local":"USD",
         "provider":"USPS",
         "provider_image_75":"https://cdn2.goshippo.com/providers/75/USPS.png",
         "provider_image_200":"https://cdn2.goshippo.com/providers/200/USPS.png",
         "servicelevel": {
            "name":"Priority Mail Express",
            "token":"usps_priority_express",
            "terms":""
         },
         "estimated_days":1,
         "arrives_by": null,
         "duration_terms":"Overnight delivery to most U.S. locations.",
         "zone":"1",
         "messages":[],
         "test": true
      }
   ]
}

Retrieve an existing rate

Retrieve an existing rate by object id.

API Resource URL

https://api.goshippo.com/rates/<RATE OBJECT ID>

Example
// Get all rates for the shipment. 
if ( ( shipment.status == "QUEUED" || shipment.status == "WAITING" ) && attempts < 10 ){
    shippo.shipment.retrieve( shipment.object_id ).then(function( val ){
        ratesReady( val, attempts+1 );
    });
}
Response Example
{
   "object_created":"2014-07-17T00:04:10.118Z",
   "object_id":"ee81fab0372e419ab52245c8952ccaeb",
   "object_owner":"shippotle@goshippo.com",
   "shipment":"89436997a794439ab47999701e60392e",
   "attributes":[],
   "amount":"5.77",
   "currency":"USD",
   "amount_local":"5.77",
   "currency_local":"USD",
   "included_insurance_price": "1.05",
   "provider":"USPS",
   "provider_image_75":"https://cdn2.goshippo.com/providers/75/USPS.png",
   "provider_image_200":"https://cdn2.goshippo.com/providers/200/USPS.png",
   "servicelevel": {
      "name":"Priority Mail",
      "token": "usps_priority",
      "terms": "",
      "extended_token": "usps_priority",
      "parent_servicelevel": null
   },
   "estimated_days":1,
   "arrives_by": null,
   "duration_terms":"Delivery within 1, 2, or 3 days based on where your package started and where it’s being sent.",
   "carrier_account":"t7185b2e81ea421f854bfccdc4236b17",
   "zone":"1",
   "messages":[],
   "test": true
}

Transactions (shipping labels)

A transaction is the purchase of a shipping label from a shipping provider for a specific service.

Attributes
object_state
"VALID"
"INVALID"		 Indicates the validity of the Transaction object based on the given data, regardless of what the corresponding carrier returns.
status
"WAITING"
"QUEUED"
"SUCCESS"
"ERROR"
"REFUNDED"
"REFUNDPENDING"
"REFUNDREJECTED"		 Indicates the status of the Transaction.
object_created
datetime		 Date and time of Transaction creation.
object_updated
datetime		 Date and time of last Transaction update.
object_id
string		 Unique identifier of the given Transaction object.
object_owner
string		 Username of the user who created the Transaction object.
rate
string		 ID of the Rate object for which a Label has to be obtained. Please note that only rates that are not older than 7 days can be purchased in order to ensure up-to-date pricing.
metadata
string		 A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
label_file_type
"PNG"
"PNG_2.3x7.5"
"PDF"
"PDF_SINGLE_8X11"
"PDF_W_PSLIP_8x11"
"PDF_2.3x7.5"
"PDF_4x6"
"PDF_4x8"
"PDF_A4"
"PDF_A6"
"ZPLII"		 Specify the label file format for this label. If you don't specify this value, the API will default to your default file format that you can set on the settings page.
See supported label formats per carrier here.
Note that the 'PDF' type will print a max of two labels per 8x11 page, while "PDF_SINGLE_8X11" will print a single label per page.
test
bool		 Indicates whether the object has been created in test mode.
tracking_number
string		 The carrier-specific tracking number that can be used to track the Shipment. A value will only be returned if the Rate is for a trackable Shipment and if the Transactions has been processed successfully.
tracking_status
enum		 Indicates the high level status of the shipment: 'UNKNOWN', 'DELIVERED', 'TRANSIT', 'FAILURE', 'RETURNED'.
tracking_url_provider
url		 A link to track this item on the carrier-provided tracking website. A value will only be returned if tracking is available and the carrier provides such a service.
eta
datetime		 The estimated time of arrival according to the carrier.
label_url
url		 A URL pointing directly to the label in the format you've set in your settings. A value will only be returned if the Transactions has been processed successfully.
commercial_invoice_url
url		 A URL pointing to the commercial invoice as a 8.5x11 inch PDF file. A value will only be returned if the Transactions has been processed successfully and if the shipment is international.
messages
array		 An array containing elements of the following schema:
"code" (string): an identifier for the corresponding message (not always available")
"message" (string): a publishable message containing further information.
qr_code_url
url		 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.
API Resource URL

https://api.goshippo.com/transactions/

Response Example
{
    "object_state":"VALID",
    "status": "SUCCESS",
    "object_created": "2013-12-27T19:14:48.273Z",
    "object_updated": "2013-12-27T19:14:48.273Z",
    "object_id": "64bba01845ef40d29374032599f22588",
    "object_owner": "shippotle@goshippo.com",
    "test": true,
    "rate": "cf6fea899f1848b494d9568e8266e076",
    "tracking_number": "ZW70QJC",
    "tracking_status": "UNKNOWN",
    "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=ZW70QJC",
    "eta":"",
    "label_url": "https://shippo-delivery.s3.amazonaws.com/96.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
    "commercial_invoice_url": "",
    "metadata": "Customer ID 123456",
    "messages": [],
    "qr_code_url": "https://shippo-delivery.s3.amazonaws.com/96_qr_code.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
}

Create a transaction (shipping label) based on a rate object

Creates a new transaction object and purchases the shipping label for the provided rate.

Attributes
rate
required		 string
metadata
optional		 string
label_file_type
optional		 "PNG"
"PDF"
"PDF_4x6"
"ZPLII"
async
optional		 boolean
API Resource URL

https://api.goshippo.com/transactions/

Example
// Get the first rate in the rates results.
// Customize this based on your business logic.
var rate = shipment.rates[0];

// Purchase the desired rate.
shippo.transaction.create({
    "rate": rate.object_id,
    "label_file_type": "PDF",
    "async": false
}, function(err, transaction) {
   // asynchronous callback
});
Response Example
{
   "object_state":"VALID",
   "status":"SUCCESS",
   "object_created":"2014-07-25T02:09:34.422Z",
   "object_updated":"2014-07-25T02:09:34.513Z",
   "object_id":"ef8808606f4241ee848aa5990a09933c",
   "object_owner":"shippotle@goshippo.com",
   "test":true,
   "rate":"ee81fab0372e419ab52245c8952ccaeb",
   "tracking_number":"",
   "tracking_status":"UNKNOWN",
   "tracking_history": [],
   "tracking_url_provider":"",
   "eta":"",
   "label_url":"",
   "commercial_invoice_url": "",
   "messages":[

   ],
   "order": null,
   "metadata":"",
   "parcel": null,
   "billing": {
       "payments": []
   },
   "qr_code_url":""
}

Create a transaction (shipping label) with one API call

Creates a new transaction object and purchases the shipping label with one API call.

Attributes
shipment
required		 object (see shipments)
carrier_account
required		 string
servicelevel_token
required		 string (see servicelevels or the Carrier Accounts endpoint)
metadata
optional		 string
label_file_type
optional		 "PNG"
"PDF"
"PDF_4x6"
"ZPLII"
API Resource URL

https://api.goshippo.com/transactions/

Example
// Create a new transaction object and purchase the shipping label with one API call
shippo.transaction.create({
    "shipment": {
      "address_to": {
          "name": "Mr Hippo",
          "street1": "965 Mission St #572",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94103",
          "country": "US",
          "phone": "4151234567",
          "email": "mrhippo@goshippo.com"
      },
      "address_from": {
          "name": "Mrs Hippo",
          "street1": "1092 Indian Summer Ct",
          "city": "San Jose",
          "state": "CA",
          "zip": "95122",
          "country": "US",
          "phone": "4159876543",
          "email": "mrshippo@goshippo.com"
      },
      "parcels": [{
          "length": "10",
          "width": "15",
          "height": "10",
          "distance_unit": "in",
          "weight": "1",
          "mass_unit": "lb"
      }]
    },
    "carrier_account": "b741b99f95e841639b54272834bc478c",
    "servicelevel_token": "usps_priority"
}, function(err, transaction) {
   // asynchronous callback
});
Response Example
{
   "object_state":"VALID",
   "status":"SUCCESS",
   "object_created":"2014-07-25T02:09:34.422Z",
   "object_updated":"2014-07-25T02:09:34.513Z",
   "object_id":"ef8808606f4241ee848aa5990a09933c",
   "object_owner":"shippotle@goshippo.com",
   "test":true,
   "rate":{
      "object_id": "ee81fab0372e419ab52245c8952ccaeb",
      "amount":"5.35",
      "currency":"USD",
      "amount_local":"5.35",
      "currency_local":"USD",
      "provider":"USPS",
      "servicelevel_name":"Priority Mail",
      "servicelevel_token":"usps_priority",
      "carrier_account":"b741b99f95e841639b54272834bc478c"
   },
   "tracking_number":"",
   "tracking_status":null,
   "tracking_history": [],
   "tracking_url_provider":"",
   "eta":"",
   "label_url":"",
   "commercial_invoice_url": "",
   "messages":[

   ],
   "order": null,
   "metadata":"",
   "parcel": null,
   "billing": {
       "payments": []
   },
   "qr_code_url":""
}

Retrieve a transaction

Retrieve an existing transaction by object id.

API Resource URL

https://api.goshippo.com/transactions/<TRANSACTION OBJECT ID>

Example
// Retrieve an existing transaction by object_id
shippo.transaction.retrieve('70ae8117ee1749e393f249d5b77c45e0');
Response Example
{
   "object_state":"VALID",
   "status":"SUCCESS",
   "object_created":"2014-07-17T00:43:40.842Z",
   "object_updated":"2014-07-17T00:43:50.531Z",
   "object_id":"70ae8117ee1749e393f249d5b77c45e0",
   "object_owner":"shippotle@goshippo.com",
   "test":true,
   "rate":"ee81fab0372e419ab52245c8952ccaeb",
   "tracking_number":"9499907123456123456781",
   "tracking_status":"UNKNOWN",
   "tracking_history": [],
   "tracking_url_provider":"https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781",
   "eta":"",
   "label_url":"https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
   "commercial_invoice_url": "",
   "messages":[],
   "order": null,
   "metadata":"",
   "parcel": null,
   "billing": {
       "payments": []
   },
   "qr_code_url": "https://shippo-delivery.s3.amazonaws.com/96_qr_code.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
}

List all transactions

List all transaction objects.

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

Optional path parameters:

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

Date format examples:

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

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

API Resource URL

https://api.goshippo.com/transactions/?results=<XX>

Example
// List all transactions
shippo.transaction.list();
Response Example
{
   "next":null,
   "previous":null,
   "results":[
      {
         "object_state":"VALID",
         "status":"SUCCESS",
         "object_created":"2014-07-17T00:43:40.842Z",
         "object_updated":"2014-07-17T00:43:50.531Z",
         "object_id":"70ae8117ee1749e393f249d5b77c45e0",
         "object_owner":"shippotle@goshippo.com",
         "test":true,
         "rate":"ee81fab0372e419ab52245c8952ccaeb",
         "tracking_number":"9499907123456123456781",
         "tracking_status":"UNKNOWN",
         "tracking_history": [],
         "tracking_url_provider":"https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781",
         "eta":"",
         "label_url":"https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
         "commercial_invoice_url": "",
         "messages":[

         ],
         "order": null,
         "metadata":"",
         "parcel": null,
         "billing": {
             "payments": []
         },
         "qr_code_url": "https://shippo-delivery.s3.amazonaws.com/96_qr_code.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
      },
      {...},
      {...}
   ]
}

Customs Items

Customs items are distinct items in your international shipment parcel.

Attributes
description
string		 Text description of your item.
eccn_ear99
string		 Export Control Classification Number, required on some exports from the United States.
hs_code
string		 DEPRECATED! This field has the same purpose as tariff_number. Please use tariff_number instead. If both values are specified, the value of the tariff_number will be used.
mass_unit
"g"
"oz"
"lb"
"kg"		 The unit used for net_weight.
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
decimal		 Total weight of this item, i.e. quantity * weight per item.
object_created
datetime		 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
"VALID"
"INVALID"		 Indicates the validity of the Customs Item.
object_updated
datetime		 Date and time of last object update.
origin_country
ISO 2 country code		 Country of origin of the item. Example: 'US' or 'DE'. All accepted values can be found on the Official ISO Website.
quantity
int		 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		 This field is used to specify the tariff_number of the item, also known as harmonized code (HS code). It is a standardized numerical method of classifying traded products, and customs authorities use it worldwide.
test
bool		 Indicates whether the object has been created in test mode.
value_amount
decimal		 Total value of this item, i.e. quantity * value per item.
value_currency
ISO 4217 currency code (string)		 Currency used for value_amount. The official ISO 4217 currency codes are used, e.g. "USD" or "EUR".
API Resource URL

https://api.goshippo.com/customs/items/

Response Example
{
    "object_created": "2014-02-24T22:05:55.014",
    "object_updated": "2014-02-24T22:05:55.016",
    "object_id": "0265b7cc4d71468197b2e8584cf8fc05",
    "object_owner": "shippotle@goshippo.com",
    "object_state":"VALID",
    "description": "T-Shirt",
    "quantity": 2,
    "net_weight": "400",
    "mass_unit": "g",
    "value_amount": "20",
    "value_currency": "USD",
    "tariff_number": "",
    "origin_country": "US",
    "eccn_ear99": "",
    "metadata": "Order ID #123123",
    "test": true
}

Create a new customs item

Creates a new Customs Item object.

Attributes
description
required		 string
quantity
required		 int
net_weight
required		 decimal
mass_unit
required		 "g"
"oz"
"lb"
"kg"
value_amount
required		 decimal
value_currency
required		 ISO 4217 currency code (string)
origin_country
required		 ISO 2 country code
tariff_number
optional		 string
sku_code
optional		 string
eccn_ear99
optional		 string
metadata
optional		 string
API Resource URL

https://api.goshippo.com/customs/items/

Example
// Create customs item
shippo.customsitem.create({
	      "description": "T-Shirt",
	      "quantity": 2,
	      "net_weight": "400",
	      "mass_unit": "g",
	      "value_amount": "20",
	      "value_currency": "USD",
	      "tariff_number": "",
	      "origin_country": "US",
	      "metadata": "Order ID #123123"
});
Response Example
{
   "object_created":"2014-07-17T00:49:20.631Z",
   "object_updated":"2014-07-17T00:49:20.631Z",
   "object_id":"55358464c7b740aca199b395536981bd",
   "object_owner":"shippotle@goshippo.com",
   "object_state":"VALID",
   "description":"T-Shirt",
   "quantity":2,
   "net_weight":"400",
   "mass_unit":"g",
   "value_amount":"20",
   "value_currency":"USD",
   "origin_country":"US",
   "tariff_number":"",
   "hs_code": null,
   "sku_code": null,
   "eccn_ear99":"",
   "metadata":"Order ID '123123'",
   "test": true
}

Retrieve an existing Customs Item

Retrieve an existing Customs Item by object id.

API Resource URL

https://api.goshippo.com/customs/items/<CUSTOMS ITEM OBJECT ID>

Example
// Retrieve an existing customs item by object_id
shippo.customsitem.retrieve('55358464c7b740aca199b395536981bd');
Response Example
{
   "object_created":"2014-07-17T00:49:20.631Z",
   "object_updated":"2014-07-17T00:49:20.631Z",
   "object_id":"55358464c7b740aca199b395536981bd",
   "object_owner":"shippotle@goshippo.com",
   "object_state":"VALID",
   "description":"T-Shirt",
   "quantity":2,
   "net_weight":"400.0000",
   "mass_unit":"g",
   "value_amount":"20.00",
   "value_currency":"USD",
   "origin_country":"US",
   "tariff_number":"",
   "hs_code": null,
   "sku_code": null,
   "eccn_ear99":"",
   "metadata":"Order ID '123123'",
   "test": true
}

List all Customs Items

List all custom-items objects.

API Resource URL

https://api.goshippo.com/customs/items/

Example
// List all customs items
shippo.customsitem.list();
Response Example
{
   "next":null,
   "previous":null,
   "results":[
      {
         "object_created":"2014-07-17T00:49:20.631Z",
         "object_updated":"2014-07-17T00:49:20.631Z",
         "object_id":"55358464c7b740aca199b395536981bd",
         "object_owner":"shippotle@goshippo.com",
         "object_state":"VALID",
         "description":"T-Shirt",
         "quantity":2,
         "net_weight":"400.0000",
         "mass_unit":"g",
         "value_amount":"20.00",
         "value_currency":"USD",
         "origin_country":"US",
         "tariff_number":"",
         "hs_code": null,
         "sku_code": null,
         "eccn_ear99":"",
         "metadata":"Order ID '123123'",
         "test": true
      },
      {...},
      {...}
   ]
}

Customs Declarations

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

Attributes
object_state
"VALID"
"INVALID"		 Indicates the validity of the Customs Item.
object_created
datetime		 Date and time of object creation.
object_updated
datetime		 Date and time of last object update.
object_id
string		 Unique identifier of the given object.
object_owner
string		 Username of the user who created the object.
certify_signer
string		 Name of the person who created the customs declaration and is responsible for the validity of all information provided.
certify
boolean		 Expresses that the certify_signer has provided all information of this customs declaration truthfully.
items
Array of Customs Items object_ids		 Distinct Parcel content items as Customs Items object_ids.
non_delivery_option
'ABANDON'
'RETURN'		 Indicates how the carrier should proceed in case the shipment can't be delivered.
contents_type
'DOCUMENTS'
'GIFT'
'SAMPLE'
'MERCHANDISE'
'HUMANITARIAN_DONATION'
'RETURN_MERCHANDISE'
'OTHER'		 Type of goods of the shipment.
contents_explanation
string		 Explanation of the type of goods of the shipment.
exporter_reference
string		 Exporter reference of an export shipment.
importer_reference
string		 Importer reference of an import shipment.
invoice
string		 Invoice reference of the shipment.
license
string		 License reference of the shipment.
certificate
string		 Certificate reference of the shipment.
notes
string		 Additional notes to be included in the customs declaration.
eel_pfc
'NOEEI_30_37_a'
'NOEEI_30_37_h'
'NOEEI_30_37_f'
'NOEEI_30_36'
'AES_ITN'		 EEL / PFC type of the shipment. For most shipments from the US to CA, 'NOEEI_30_36' is applicable; for most other shipments from the US, 'NOEEI_30_37_a' is applicable.
aes_itn
string		 AES / ITN reference of the shipment.
incoterm
'DDP',
'DDU',
'FCA',
'DAP',
'eDAP'		 The incoterm reference of the shipment. FCA is available for DHL Express and FedEx only. eDAP is available for DPD UK only. DAP is available for DHL Express and DPD UK. If expecting DAP for other carriers, please use DDU.
is_vat_collected
 Indicates whether the shipment's destination VAT has been collected. May be required for some destinations.
b13a_filing_option
'FILED_ELECTRONICALLY',
'SUMMARY_REPORTING',
'NOT_REQUIRED'
 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.
b13a_number
 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.
invoiced_charges
object
optional
 An object holding optional invoiced charges data to be printed on the Commercial Invoice. See the Invoiced Charges table below for all available charges.
exporter_identification
object
optional
 An object holding optional exporter identification. See the Exporter Identification table below for all available fields.
metadata
string		 A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
disclaimer
string		 Disclaimer for the shipment and customs information that have been provided.
test
boolean		 Indicates whether the object has been created in test mode.
API Resource URL

https://api.goshippo.com/customs/declarations/

Response Example
{
    "object_created": "2014-02-24T22:35:44.358",
    "object_updated": "2014-02-24T22:35:44.358",
    "object_id": "b741b99f95e841639b54272834bc478c",
    "object_owner": "shippotle@goshippo.com",
    "object_state":"VALID",
    "exporter_reference": "",
    "importer_reference": "",
    "contents_type": "MERCHANDISE",
    "contents_explanation": "T-Shirt purchase",
    "invoice": "#123123",
    "license": "",
    "certificate": "",
    "notes": "",
    "eel_pfc": "NOEEI_30_37_a",
    "aes_itn": "",
    "non_delivery_option": "ABANDON",
    "certify": true,
    "certify_signer": "Shawn Ippotle",
    "disclaimer": "",
    "incoterm": "",
    "is_vat_collected": null,
    "b13a_filing_option": "",
    "b13a_number": "",
    "invoiced_charges": null,
    "exporter_identification": {
        "eori_number": "PL123456790ABCDE",
        "tax_id": {
            "number": "123456789",
            "type": "EIN"
        }
    },
    "items": [
        "0c1a723687164307bb2175972fbcd9ef"
    ],
    "metadata": "Order ID #123123",
    "test": true
}

Invoiced Charges

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

Attributes
currency
ISO 4217 currency code
string
required		 Currency for the invoiced charges amounts incurred on the end consumer.
total_shipping
decimal
optional		 Total shiping paid by the buyer.
total_taxes
decimal
optional		 Total taxes paid by the buyer.
total_duties
decimal
optional		 Total duties paid by the buyer.
other_fees
decimal
optional		 Other fees paid by the buyer.
API Resource URL

https://api.goshippo.com/customs/declarations/

Response Example
{
    "object_created": "2014-02-24T22:35:44.358",
    "object_updated": "2014-02-24T22:35:44.358",
    "object_id": "b741b99f95e841639b54272834bc478c",
    "object_owner": "shippotle@goshippo.com",
    "object_state":"VALID",
    "exporter_reference": "",
    "importer_reference": "",
    "contents_type": "MERCHANDISE",
    "contents_explanation": "T-Shirt purchase",
    "invoice": "#123123",
    "license": "",
    "certificate": "",
    "notes": "",
    "eel_pfc": "NOEEI_30_37_a",
    "aes_itn": "",
    "non_delivery_option": "ABANDON",
    "certify": true,
    "certify_signer": "Shawn Ippotle",
    "disclaimer": "",
    "incoterm": "",
    "is_vat_collected": null,
    "b13a_filing_option": "",
    "b13a_number": "",
    "invoiced_charges": {
        "total_shipping": "69.99",
        "total_taxes": "3.45",
        "total_duties": "4.68",
        "other_fees": "3.00",
        "currency": "USD"
    },
    "items": [
        "0c1a723687164307bb2175972fbcd9ef"
    ],
    "metadata": "Order ID #123123",
    "test": true
}

Exporter Identification

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

Attributes
eori_number
string
optional		 Economic Operators' Registration and Identification (EORI) number. Must start with a 2 character country code followed by a 6-17 character alphanumeric identifier (e.g. PL1234567890ABCDE). More information on EORI.
tax_id
object
optional		 Tax Identification. See the Tax Identification table below for all available fields.
API Resource URL

https://api.goshippo.com/customs/declarations/

Response Example
{
    "object_created": "2014-02-24T22:35:44.358",
    "object_updated": "2014-02-24T22:35:44.358",
    "object_id": "b741b99f95e841639b54272834bc478c",
    "object_owner": "shippotle@goshippo.com",
    "object_state":"VALID",
    "exporter_reference": "",
    "importer_reference": "",
    "contents_type": "MERCHANDISE",
    "contents_explanation": "T-Shirt purchase",
    "invoice": "#123123",
    "license": "",
    "certificate": "",
    "notes": "",
    "eel_pfc": "NOEEI_30_37_a",
    "aes_itn": "",
    "non_delivery_option": "ABANDON",
    "certify": true,
    "certify_signer": "Shawn Ippotle",
    "disclaimer": "",
    "incoterm": "",
    "is_vat_collected": null,
    "b13a_filing_option": "",
    "b13a_number": "",
    "invoiced_charges": null,
    "exporter_identification:": {
        "eori_number": "PL123456790ABCDE",
        "tax_id": {
            "number": "123456789",
            "type": "EIN"
        }
    },
    "items": [
        "0c1a723687164307bb2175972fbcd9ef"
    ],
    "metadata": "Order ID #123123",
    "test": true
}

Tax Identification

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

Attributes
number
string		 Tax identification number.
type
'EIN'
'VAT'
'IOSS'
'ARN'		 Type of tax identification.
  • EIN - Employer Identification Number, also known as a Federal Tax Identification Number.
  • VAT - Value Added Tax identification number.
  • IOSS - Import One-Stop Shop
  • ARN - Australian Taxation Office Reference Number
API Resource URL

https://api.goshippo.com/customs/declarations/

Response Example
{
    "object_created": "2014-02-24T22:35:44.358",
    "object_updated": "2014-02-24T22:35:44.358",
    "object_id": "b741b99f95e841639b54272834bc478c",
    "object_owner": "shippotle@goshippo.com",
    "object_state":"VALID",
    "exporter_reference": "",
    "importer_reference": "",
    "contents_type": "MERCHANDISE",
    "contents_explanation": "T-Shirt purchase",
    "invoice": "#123123",
    "license": "",
    "certificate": "",
    "notes": "",
    "eel_pfc": "NOEEI_30_37_a",
    "aes_itn": "",
    "non_delivery_option": "ABANDON",
    "certify": true,
    "certify_signer": "Shawn Ippotle",
    "disclaimer": "",
    "incoterm": "",
    "is_vat_collected": null,
    "b13a_filing_option": "",
    "b13a_number": "",
    "invoiced_charges": null,
    "exporter_identification:": {
        "tax_id": {
            "number": "123456789",
            "type": "EIN"
        }
    },
    "items": [
        "0c1a723687164307bb2175972fbcd9ef"
    ],
    "metadata": "Order ID #123123",
    "test": true
}

Create a new Customs Declaration

Creates a new Customs Declaration object.

Attributes
certify_signer
required		 string
certify
required		 boolean
items
required		 Array of Customs Items object_ids
non_delivery_option
required		 'ABANDON',
'RETURN'
contents_type
required		 'DOCUMENTS',
'GIFT',
'SAMPLE',
'MERCHANDISE',
'HUMANITARIAN_
DONATION',
'RETURN_
MERCHANDISE',
'OTHER'
contents_explanation
required if contents_type is 'OTHER'		 string
exporter_reference
optional		 string
importer_reference
optional		 string
invoice
optional		 string
license
optional		 string
certificate
optional		 string
notes
optional		 string
eel_pfc
optional		 'NOEEI_30_37_a',
'NOEEI_30_37_h',
'NOEEI_30_36',
'AES_ITN'
aes_itn
required if eel_pfc is 'AES_ITN'		 string
incoterm
optional		 'DDP',
'DDU'
is_vat_collected
optional		 boolean
b13a_filing_option
optional		 'FILED_ELECTRONICALLY',
'SUMMARY_REPORTING',
'NOT_REQUIRED'
b13a_number
must be provided if and only if b13a_filing_option is provided 		string
invoiced_charges
optional		 see Invoiced Charges above
metadata
optional		 string
API Resource URL

https://api.goshippo.com/customs/declarations/

Example
var customsItem = {
    "description":"T-Shirt",
    "quantity":20,
    "net_weight":"1",
    "mass_unit":"lb",
    "value_amount":"200",
    "value_currency":"USD",
    "origin_country":"US",
};

shippo.customsdeclaration.create({
    "contents_type": "MERCHANDISE",
    "contents_explanation": "T-Shirt purchase",
    "non_delivery_option": "RETURN",
    "certify": true,
    "certify_signer": "Simon Kreuz",
    "items": [customsItem],
}, function (err, customsDeclaration) {
    // asynchronously called
});
Response Example
{
   "object_created":"2014-07-17T01:01:08.306Z",
   "object_updated":"2014-07-17T01:01:08.306Z",
   "object_id":"e2197a54da9d470480f4f8796cc419cb",
   "object_owner":"shippotle@goshippo.com",
   "object_state":"VALID",
   "certify_signer":"Shawn Ippotle",
   "certify":true,
   "items":[
      "5087f181d1dc4b14b73fdbf636498886"
   ],
   "non_delivery_option":"ABANDON",
   "contents_type":"MERCHANDISE",
   "contents_explanation":"T-Shirt purchase",
   "exporter_reference":"",
   "importer_reference":"",
   "invoice":"#123123",
   "commercial_invoice":false,
   "license":"",
   "certificate":"",
   "notes":"",
   "eel_pfc":"NOEEI_30_37_a",
   "aes_itn":"",
   "disclaimer":"",
   "incoterm":"",
   "is_vat_collected":null,
   "b13a_filing_option":"",
   "b13a_number":"",
   "metadata":"Order ID #123123",
   "test": true
}

Retrieve an existing Customs Declaration

Retrieve an existing customs-declaration by object id.

API Resource URL

https://api.goshippo.com/customs/declarations/<CUSTOMS DEC. OBJECT ID>

Example
// Retrieve an existing customs declaration by object_id
shippo.customsdeclaration.retrieve('e2197a54da9d470480f4f8796cc419cb');
Response Example
{
   "object_created":"2014-07-17T01:01:08.306Z",
   "object_updated":"2014-07-17T01:01:08.306Z",
   "object_id":"e2197a54da9d470480f4f8796cc419cb",
   "object_owner":"shippotle@goshippo.com",
   "object_state":"VALID",
   "certify_signer":"Shawn Ippotle",
   "certify":true,
   "items":[
      "5087f181d1dc4b14b73fdbf636498886"
   ],
   "non_delivery_option":"ABANDON",
   "contents_type":"MERCHANDISE",
   "contents_explanation":"T-Shirt purchase",
   "exporter_reference":"",
   "importer_reference":"",
   "invoice":"#123123",
   "commercial_invoice":false,
   "license":"",
   "certificate":"",
   "notes":"",
   "eel_pfc":"NOEEI_30_37_a",
   "aes_itn":"",
   "disclaimer":"",
   "incoterm":"",
   "is_vat_collected":null,
   "b13a_filing_option":"",
   "b13a_number":"",
   "metadata":"Order ID #123123",
   "test": true
}

List all customs declarations

List all customs-declaration objects.

API Resource URL

https://api.goshippo.com/customs/declarations/

Example
// List all customs declarations
shippo.customsdeclaration.list();
Response Example
{
   "next":null,
   "previous":null,
   "results":[
      {
         "object_created":"2014-07-17T01:01:08.306Z",
         "object_updated":"2014-07-17T01:01:08.306Z",
         "object_id":"e2197a54da9d470480f4f8796cc419cb",
         "object_owner":"shippotle@goshippo.com",
         "object_state":"VALID",
         "certify_signer":"Shawn Ippotle",
         "certify":true,
         "items":[
            "5087f181d1dc4b14b73fdbf636498886"
         ],
         "non_delivery_option":"ABANDON",
         "contents_type":"MERCHANDISE",
         "contents_explanation":"T-Shirt purchase",
         "exporter_reference":"",
         "importer_reference":"",
         "invoice":"#123123",
         "commercial_invoice":false,
         "license":"",
         "certificate":"",
         "notes":"",
         "eel_pfc":"NOEEI_30_37_a",
         "aes_itn":"",
         "disclaimer":"",
         "incoterm":"",
         "is_vat_collected":null,
         "b13a_filing_option":"",
         "b13a_number":"",
         "metadata":"Order ID #123123",
         "test": true
      },
      {...},
      {...}
   ]
}

Refunds

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

Attributes
object_created
datetime		 Date and time of object creation.
object_updated
datetime		 Date and time of last object update.
object_id
string		 Unique identifier of the given object.
object_owner
string		 Username of the user who created the object.
status
"QUEUED"
"PENDING"
"SUCCESS"
"ERROR"		 Indicates the status of the Refund.
transaction
string		 Object ID of the Transaction to be refunded.
test
bool		 Indicates whether the object has been created in test mode.
API Resource URL

https://api.goshippo.com/refunds/

Response Example
{
    "object_created": "2014-04-21T07:12:41.044Z",
    "object_updated": "2014-04-21T07:12:41.045Z",
    "object_id": "bd7b8379a2e847bcb0818125943dde5d",
    "object_owner": "shippotle@goshippo.com",
    "status": "SUCCESS",
    "transaction": "35ed59f23a514ecfa2faeaed93a00086",
    "test": true
}

Create a new refund

Creates a new refund object.

Attributes
transaction
required		 string
async
optional		 boolean
API Resource URL

https://api.goshippo.com/refunds/

Example
shippo.refund.create({
    "transaction": "35ed59f23a514ecfa2faeaed93a00086",
    "async": false
}, function (err, refund) {
    // asynchronously called
});
Response Example
{
   "object_created":"2014-07-17T15:38:37.372Z",
   "object_updated":"2014-07-17T15:38:37.381Z",
   "object_id":"d7c811cff9e24e4387418876f1ffd371",
   "object_owner":"shippotle@goshippo.com",
   "status":"SUCCESS",
   "transaction":"8b7f25f33d2a4bb58060df94cb152434",
   "test": true
}

Retrieve an existing refund

Retrieve an existing refund by object id.

API Resource URL

https://api.goshippo.com/refunds/<REFUND OBJECT ID>

Example
// Retrieve an existing refund by object_id
shippo.refund.retrieve('d7c811cff9e24e4387418876f1ffd371');
Response Example
{
   "object_created":"2014-07-17T15:38:37.372Z",
   "object_updated":"2014-07-17T15:38:43.070Z",
   "object_id":"d7c811cff9e24e4387418876f1ffd371",
   "object_owner":"shippotle@goshippo.com",
   "status":"SUCCESS",
   "transaction":"8b7f25f33d2a4bb58060df94cb152434",
   "test": true
}

List all refund objects.

Retrieve an existing refund by object id.

API Resource URL

https://api.goshippo.com/refunds/

Example
// List all refunds
shippo.refund.list();
Response Example
{
   "next":null,
   "previous":null,
   "results":[
      {
         "object_created":"2014-07-17T15:38:37.372Z",
         "object_updated":"2014-07-17T15:38:43.070Z",
         "object_id":"d7c811cff9e24e4387418876f1ffd371",
         "object_owner":"shippotle@goshippo.com",
         "status":"SUCCESS",
         "transaction":"8b7f25f33d2a4bb58060df94cb152434",
         "test": true
      },
      {...}
   ]
}

Manifests

Manifests are close-outs of shipping labels of a certain day. Some carriers require manifests to properly process the shipments.

Attributes
object_created
datetime		 Date and time of object creation.
object_updated
datetime		 Date and time of last object update.
object_id
string		 Unique identifier of the given object.
object_owner
string		 Username of the user who created the object.
status
"QUEUED"
"SUCCESS"
"ERROR"		 Indicates the status of the manifest.
errors
array		 An array of codes and messages describing the error that occurred if any.
carrier_account
string		 ID of carrier account
shipment_date
datetime		 All shipments to be submitted on this day will be closed out. Must be in the format "2014-01-18T00:35:03.463Z" (ISO 8601 date).
address_from
string		 ID of the Address object that should be used as pickup address for the scan form. The USPS will validate this address before creating the scan form.
transactions
array		 IDs transactions to use. If you set this to null or not send this parameter, Shippo will automatically assign all applicable transactions.
documents
array		 An array containing the URLs to all returned manifest documents.
API Resource URL

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

Response Example
{
    "object_created": "2014-05-16T03:43:52.765Z",
    "object_updated": "2014-05-16T03:43:55.445Z",
    "object_id": "0fadebf6f60c4aca95fa01bcc59c79ae",
    "object_owner": "mrhippo@goshippo.com",
    "status": "SUCCESS",
    "errors": [],
    "carrier_account": "b741b99f95e841639b54272834bc478c",
    "shipment_date": "2014-05-16T23:59:59Z",
    "address_from": "28828839a2b04e208ac2aa4945fbca9a",
    "transactions": ["64bba01845ef40d29374032599f22588", "c169aa586a844cc49da00d0272b590e1"],
    "documents": [
        "https://shippo-delivery.s3.amazonaws.com/0fadebf6f60c4aca95fa01bcc59c79ae.pdf?Signature=tlQU3RECwdHUQJQadwqg5bAzGFQ%3D&Expires=1402803835&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
    ]
}

Create a new manifest

Creates a new manifest object.

Attributes
carrier_account
required		 string
shipment_date
required		 datetime
address_from
required		 string
transactions
optional		 array of transaction object_ids
async
optional		 boolean
API Resource URL

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

Example
shippo.manifest.create({
    "carrier_account": "b741b99f95e841639b54272834bc478c",
    "shipment_date": "2014-05-16T23:59:59Z",
    "transactions": [
        "64bba01845ef40d29374032599f22588",
        "c169aa586a844cc49da00d0272b590e1"
    ]
}, function(err, manifest) {
    // asynchronously called
});
Response Example
{
    "object_created": "2014-05-16T03:43:52.765Z",
    "object_updated": "2014-05-16T03:43:55.445Z",
    "object_id": "0fadebf6f60c4aca95fa01bcc59c79ae",
    "object_owner": "mrhippo@goshippo.com",
    "status": "SUCCESS",
    "errors": [],
    "provider": "usps",
    "carrier_account": "b741b99f95e841639b54272834bc478c",
    "shipment_date": "2014-05-16T23:59:59Z",
    "address_from": "d799c2679e644279b59fe661ac8fa488",
    "transactions": ["64bba01845ef40d29374032599f22588", "c169aa586a844cc49da00d0272b590e1"],
    "documents": [
        "https://shippo-delivery.s3.amazonaws.com/0fadebf6f60c4aca95fa01bcc59c79ae.pdf?Signature=tlQU3RECwdHUQJQadwqg5bAzGFQ%3D&Expires=1402803835&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
    ]
}

Retrieve an existing manifest

Retrieve an existing manifest by object id.

API Resource URL

https://api.goshippo.com/manifests/<MANIFEST OBJECT ID>

Example
// Retrieve an existing manifest by object_id
shippo.manifest.retrieve('0fadebf6f60c4aca95fa01bcc59c79ae');
Response Example
{
   "object_created":"2014-05-16T03:43:52.765Z",
   "object_updated":"2014-05-16T03:43:55.445Z",
   "object_id":"0fadebf6f60c4aca95fa01bcc59c79ae",
   "object_owner":"mrhippo@goshippo.com",
   "status":"SUCCESS",
   "errors": [],
   "provider": "usps",
   "carrier_account": "b741b99f95e841639b54272834bc478c",
   "shipment_date":"2014-05-16T23:59:59Z",
   "address_from":"008ee72b723c4f129371b7346fe2f55f",
   "transactions": ["64bba01845ef40d29374032599f22588", "c169aa586a844cc49da00d0272b590e1"],
   "documents":[
      "https://shippo-delivery.s3.amazonaws.com/0fadebf6f60c4aca95fa01bcc59c79ae.pdf?Signature=tlQU3RECwdHUQJQadwqg5bAzGFQ%3D&Expires=1402803835&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
   ]
}

List all manifests

List all Manifest objects.

API Resource URL

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

Example
// List all manifests
shippo.manifest.list();
Response Example
{
   "next":null,
   "previous":null,
   "results":[
      {
         "object_created":"2014-07-17T16:09:46.079Z",
         "object_updated":"2014-07-17T16:09:46.079Z",
         "object_id":"aa41ad380c53413ab2cee8ba98d2cc34",
         "object_owner":"mrhippo@goshippo.com",
         "status":"SUCCESS",
         "errors": [],
         "provider": "usps",
         "carrier_account": "b741b99f95e841639b54272834bc478c",
         "shipment_date":"2014-05-16T23:59:59Z",
         "address_from":"d799c2679e644279b59fe661ac8fa488",
         "transactions": ["64bba01845ef40d29374032599f22588", "c169aa586a844cc49da00d0272b590e1"],
         "documents": [
            "https://shippo-delivery.s3.amazonaws.com/0fadebf6f60c4aca95fa01bcc59c79ae.pdf?Signature=tlQU3RECwdHUQJQadwqg5bAzGFQ%3D&Expires=1402803835&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
         ]
      },
      {...}
   ]
}

Manifest Errors

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

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

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

Response Example
{
    "object_created": "2014-05-16T03:43:52.765Z",
    "object_updated": "2014-05-16T03:43:55.445Z",
    "object_id": "0fadebf6f60c4aca95fa01bcc59c79ae",
    "object_owner": "mrhippo@goshippo.com",
    "object_status": "ERROR",
    "errors": [
        {
            "code": "shipment_date_invalid",
            "message": "The shipment date is invalid. Please update the shipment date and try again."
        }
    ],
    "provider": "usps",
    "carrier_account": "b741b99f95e841639b54272834bc478c",
    "submission_date": "2014-05-16T23:59:59Z",
    "address_from": "28828839a2b04e208ac2aa4945fbca9a",
    "transactions": [],
    "documents": []
}

Carrier Accounts

Carrier accounts are used as credentials to retrieve shipping rates and purchase labels from a shipping provider.

To protect account information, we will mask the account ID and parameters in the response objects

Attributes
object_id
string		 Unique identifier of the carrier account object.
object_owner
string		 Username of the user who created the carrier account object.
carrier
string		 Name of the carrier (as a token). Please check the carrier accounts tutorial page for all supported carriers.
account_id
string		 Unique identifier of the account. Please check the carrier accounts tutorial page for the account_id per carrier.
To protect account information, this field will be masked in any API response.
parameters
array		 An array of additional parameters for the account, such as e.g. password or token. Please check the carrier accounts tutorial page for the parameters per carrier.
To protect account information, this field will be masked in any API response.
test
boolean		 Indicates whether the object has been created in test mode.
active
boolean		 Determines whether the account is active. When creating a shipment, if no carrier_accounts are explicitly passed Shippo will query all carrier accounts that have this field set. By default, this is set to True.
API Resource URL

https://api.goshippo.com/carrier_accounts/

Response Example
{
    "object_id":"b741b99f95e841639b54272834bc478c",
    "object_owner": "shippotle@goshippo.com",
    "carrier": "fedex",
    "carrier_name": "FedEx",
    "carrier_images": {
        "75": "https://shippo-static.s3.amazonaws.com/providers/75/FedEx.png",
        "200": "https://shippo-static.s3.amazonaws.com/providers/200/FedEx.png"
    },
    "account_id": "******",
    "parameters": {
        "meter": "******"
    },
    "test": false,
    "active": true
}

Create a new carrier account

Creates a new carrier account object.

Attributes
carrier
required		 Name of the carrier. Please check the Carrier Capabilities page for all supported carrier names.
account_id
required		 Unique identifier of the account. Please check the Carrier Capabilities page for the account_id per carrier.
For security reasons, this field will be censored in any API response.
parameters
required		 An array of additional parameters for the account, such as e.g. password or token. Please check the Carrier Capabilities page for the parameters per carrier.
For security reasons, this field will be censored in any API response.
active Determines whether the account is enabled.
API Resource URL

https://api.goshippo.com/carrier_accounts/

Example
shippo.carrieraccount.create({
    "carrier":"fedex", 
    "account_id":"321123", 
    "parameters":{"meter":"789987"},
    "active":true
}, function(err, account) {
  // asynchronously called
});
Response Example
{
    "object_id":"b741b99f95e841639b54272834bc478c",
    "object_owner": "shippotle@goshippo.com",
    "carrier": "fedex",
    "carrier_name": "FedEx",
    "carrier_images": {
        "75": "https://shippo-static.s3.amazonaws.com/providers/75/FedEx.png",
        "200": "https://shippo-static.s3.amazonaws.com/providers/200/FedEx.png"
    },
    "account_id": "******",
    "parameters": {
        "meter": "******"
    },
    "test": false,
    "active": true
}

Retrieve an existing carrier account

Retrieve an existing carrier account by object id.

Additionally, you can get information about the service levels associated with a carrier account by passing in the ?service_levels=1 query parameter. Using it appends the property service_levels to the carrier account response.

This is useful as an up-to-date, programmatic alternative to the list of service levels specified here.

By default, if the query parameter is omitted, the service_levels property will not be included in the response.

API Resource URL

https://api.goshippo.com/carrier_accounts/<CARRIER ACCOUNT OBJECT ID>

Example
// Retrieve an existing carrier account by object_id
shippo.carrieraccount.retrieve('b741b99f95e841639b54272834bc478c');
Response Example
{
    "object_id":"b741b99f95e841639b54272834bc478c",
    "object_owner": "shippotle@goshippo.com",
    "carrier": "fedex",
    "carrier_name": "FedEx",
    "carrier_images": {
        "75": "https://shippo-static.s3.amazonaws.com/providers/75/FedEx.png",
        "200": "https://shippo-static.s3.amazonaws.com/providers/200/FedEx.png"
    },
    "account_id": "******",
    "parameters": {
        "meter": "******"
    },
    "test": false,
    "active": true
}

List all carrier accounts

List all carrier accounts.

Additionally, you can get information about the service levels associated with each carrier account by passing in the ?service_levels=1 query parameter. Using it appends the property service_levels to each carrier account.

This is useful as an up-to-date, programmatic alternative to the list of service levels specified here.

By default, if the query parameter is omitted, the service_levels property will not be included in the response.

API Resource URL

https://api.goshippo.com/carrier_accounts/

Example
// List all carrier accounts
shippo.carrieraccount.list();
Response Example
{
   "next":null,
   "previous":null,
   "results":[
         {
            "object_id":"b741b99f95e841639b54272834bc478c",
             "object_owner": "shippotle@goshippo.com",
             "carrier": "fedex",
             "carrier_name": "FedEx",
             "carrier_images": {
                 "75": "https://shippo-static.s3.amazonaws.com/providers/75/FedEx.png",
                 "200": "https://shippo-static.s3.amazonaws.com/providers/200/FedEx.png"
             },
             "service_levels": [
                 {
                     "token": "fedex_same_day",
                     "name": "SameDay®",
                     "supports_return_labels": false
                 },
                 {...}
             ],
             "account_id": "******",
             "parameters": {
                 "meter": "******"
             },
             "test": false,
             "active": true
         },
         {...},
         {...}
   ]
}

Update an existing carrier account

PUT request to update an existing carrier account object. The account_id and carrier can't be updated, because they form the unique identifier together.

Attributes
carrier
required		 Name of the carrier. Please check the Carrier Capabilities page for all supported carrier names.
account_id
required		 Unique identifier of the account. Please check the Carrier Capabilities page for the account_id per carrier.
For security reasons, this field will be censored in any API response.
parameters
optional		 An array of additional parameters for the account, such as e.g. password or token. Please check the Carrier Capabilities page for the parameters per carrier.
For security reasons, this field will be censored in any API response.
active
optional		 Determines whether the account is active. When creating a shipment, if no carrier_accounts are explicitly passed Shippo will query all carrier accounts that have this field set. By default, this is set to True.
API Resource URL

https://api.goshippo.com/carrier_accounts/<CARRIER ACCOUNT OBJECT ID>

Example
// To update a carrier account we need the account's object_id. 
// If you haven't stored it in your system, retrieve it first.
// You can list all your accounts like this.
var accounts = shippo.carrieraccount.list();
console.log(accounts);

//  Now you can update the account with the corresponding object_id.
var fedex_account = shippo.carrieraccount.update("b741b99f95e841639b54272834bc478c", {"active":true}, function(err, account) {
  // asynchronously called
});
Response Example
{
    "object_id":"b741b99f95e841639b54272834bc478c",
    "object_owner": "shippotle@goshippo.com",
    "carrier": "fedex",
    "carrier_name": "FedEx",
    "carrier_images": {
        "75": "https://shippo-static.s3.amazonaws.com/providers/75/FedEx.png",
        "200": "https://shippo-static.s3.amazonaws.com/providers/200/FedEx.png"
    },
    "account_id": "******",
    "parameters": {
        "meter": "******"
    },
    "test": false,
    "active": true
}

Tracking Status

If you purchased your shipping label through Shippo, you can also get all the tracking details of your Shipment from the Transaction object.

Tracking Status objects are used to track shipments.

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

Attributes
carrier
string		 Name of the carrier of the shipment to track. See Carriers.
tracking_number
string		 Tracking number to track.
address_from
hash		 The sender address with city, state, zip and country information.
address_to
hash		 The recipient address with city, state, zip and country information.
transaction
string		 The object_id of the transaction associated with this tracking object. This field is visible only to the object owner of the transaction.
eta
datetime		 The estimated time of arrival according to the carrier, this might be updated by carriers during the life of the shipment.
original_eta
datetime		 The estimated time of arrival according to the carrier at the time the shipment first entered the system.
servicelevel
hash		 The service level of the shipment as token and full name.
tracking_status
hash		 The latest tracking information of this shipment.
tracking_status.status
'UNKNOWN'
'PRE_TRANSIT'
'TRANSIT'
'DELIVERED'
'RETURNED'
'FAILURE'		 Indicates the high level status of the shipment.
tracking_status.status_details
string		 The human-readable description of the status.
tracking_status.status_date
datetime		 Date and time when the carrier scanned this tracking event. This is displayed in UTC.
tracking_status.location
object		 An object containing zip, city, state and country information of the tracking event.
tracking_history
array		 A list of tracking events, following the same structure as tracking_status. It contains a full history of all tracking statuses, starting with the earlier tracking event first.
metadata
string		 A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
Additional response attributes
API Resource URL

https://api.goshippo.com/tracks/

Response Example
{
  "carrier": "usps",
  "tracking_number": "9205590164917312751089",
  "address_from": {
    "city": "Las Vegas",
    "state": "NV",
    "zip": "89101",
    "country": "US"
  },
  "address_to": {
    "city": "Spotsylvania",
    "state": "VA",
    "zip": "22551",
    "country": "US"
  },
  "transaction": "1275c67d754f45bf9d6e4d7a3e205314",
  "eta": "2016-07-23T00:00:00Z",
  "original_eta": "2016-07-23T00:00:00Z",
  "servicelevel": {
    "token": "usps_priority",
    "name": "Priority Mail"
  },
  "metadata": null,
  "tracking_status": {
    "object_created": "2016-07-23T20:35:26.129Z",
    "object_updated": "2016-07-23T20:35:26.129Z",
    "object_id": "ce48ff3d52a34e91b77aa98370182624",
    "status": "DELIVERED",
    "status_details": "Your shipment has been delivered at the destination mailbox.",
    "status_date": "2016-07-23T13:03:00Z",
    "location": {
      "city": "Spotsylvania",
      "state": "VA",
      "zip": "22551",
      "country": "US"
    }
  },
  "tracking_history": [
    {
      "object_created": "2016-07-22T14:36:50.943Z",
      "object_id": "265c7a7c23354da5b87b2bf52656c625",
      "status": "TRANSIT",
      "status_details": "Your shipment has been accepted.",
      "status_date": "2016-07-21T15:33:00Z",
      "location": {
        "city": "Las Vegas",
        "state": "NV",
        "zip": "89101",
        "country": "US"
      }
    },
    ...

    {
      "object_created": "2016-07-23T20:35:26.129Z",
      "object_id": "aab1d7c0559d43ccbba4ff8603089e56",
      "status": "DELIVERED",
      "status_details": "Your shipment has been delivered at the destination mailbox.",
      "status_date": "2016-07-23T13:03:00Z",
      "location": {
        "city": "Spotsylvania",
        "state": "VA",
        "zip": "22551",
        "country": "US"
      }
    }
  ]
}

Get a tracking update

Request the tracking status of a shipment by sending a GET request.

API Resource URL

https://api.goshippo.com/tracks/<CARRIER>/<TRACKING NUMBER>/

Example
Response Example
{
  "carrier": "usps",
  "tracking_number": "9205590164917312751089",
  "address_from": {
    "city": "Las Vegas",
    "state": "NV",
    "zip": "89101",
    "country": "US"
  },
  "address_to": {
    "city": "Spotsylvania",
    "state": "VA",
    "zip": "22551",
    "country": "US"
  },
  "transaction": "1275c67d754f45bf9d6e4d7a3e205314",
  "eta": "2016-07-23T00:00:00Z",
  "original_eta": "2016-07-23T00:00:00Z",
  "servicelevel": {
    "token": "usps_priority",
    "name": "Priority Mail"
  },
  "metadata": null,
  "tracking_status": {
    "object_created": "2016-07-23T20:35:26.129Z",
    "object_updated": "2016-07-23T20:35:26.129Z",
    "object_id": "ce48ff3d52a34e91b77aa98370182624",
    "status": "DELIVERED",
    "status_details": "Your shipment has been delivered at the destination mailbox.",
    "status_date": "2016-07-23T13:03:00Z",
    "location": {
      "city": "Spotsylvania",
      "state": "VA",
      "zip": "22551",
      "country": "US"
    }
  },
  "tracking_history": [
    {
      "object_created": "2016-07-22T14:36:50.943Z",
      "object_id": "265c7a7c23354da5b87b2bf52656c625",
      "status": "TRANSIT",
      "status_details": "Your shipment has been accepted.",
      "status_date": "2016-07-21T15:33:00Z",
      "location": {
        "city": "Las Vegas",
        "state": "NV",
        "zip": "89101",
        "country": "US"
      }
    },
    {...},
    {
      "object_created": "2016-07-23T20:35:26.129Z",
      "object_id": "aab1d7c0559d43ccbba4ff8603089e56",
      "status": "DELIVERED",
      "status_details": "Your shipment has been delivered at the destination mailbox.",
      "status_date": "2016-07-23T13:03:00Z",
      "location": {
        "city": "Spotsylvania",
        "state": "VA",
        "zip": "22551",
        "country": "US"
      }
    }
  ],
  "messages": []
}

Register a tracking webhook

You can register your webhook(s) for a Shipment (and request the current status at the same time) by POSTing to the tracking endpoint. This way Shippo will send HTTP notifications to your track_updated webhook(s) whenever the status changes.

Attributes
carrier
required		 Name of the carrier of the shipment to track. See Carriers.
tracking_number
required		 Tracking number to track.
metadata
optional		 A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
API Resource URL

https://api.goshippo.com/tracks/

Example
// Client library is currently being updated to support this API endpoint--please check back soon!
Response Example
{
  "carrier": "usps",
  "tracking_number": "9205590164917312751089",
  "address_from": {
    "city": "Las Vegas",
    "state": "NV",
    "zip": "89101",
    "country": "US"
  },
  "address_to": {
    "city": "Spotsylvania",
    "state": "VA",
    "zip": "22551",
    "country": "US"
  },
  "transaction": "1275c67d754f45bf9d6e4d7a3e205314",
  "original_eta": "2016-07-23T00:00:00Z",
  "eta": "2016-07-23T00:00:00Z",
  "servicelevel": {
    "token": "usps_priority",
    "name": "Priority Mail"
  },
  "metadata": null,
  "tracking_status": {
    "object_created": "2016-07-23T20:35:26.129Z",
    "object_updated": "2016-07-23T20:35:26.129Z",
    "object_id": "ce48ff3d52a34e91b77aa98370182624",
    "status": "DELIVERED",
    "status_details": "Your shipment has been delivered at the destination mailbox.",
    "status_date": "2016-07-23T13:03:00Z",
    "location": {
      "city": "Spotsylvania",
      "state": "VA",
      "zip": "22551",
      "country": "US"
    }
  },
  "tracking_history": [
    {
      "object_created": "2016-07-22T14:36:50.943Z",
      "object_id": "265c7a7c23354da5b87b2bf52656c625",
      "status": "TRANSIT",
      "status_details": "Your shipment has been accepted.",
      "status_date": "2016-07-21T15:33:00Z",
      "location": {
        "city": "Las Vegas",
        "state": "NV",
        "zip": "89101",
        "country": "US"
      }
    },
    {...},
    {
      "object_created": "2016-07-23T20:35:26.129Z",
      "object_id": "aab1d7c0559d43ccbba4ff8603089e56",
      "status": "DELIVERED",
      "status_details": "Your shipment has been delivered at the destination mailbox.",
      "status_date": "2016-07-23T13:03:00Z",
      "location": {
        "city": "Spotsylvania",
        "state": "VA",
        "zip": "22551",
        "country": "US"
      }
    }
  ],
  "messages": []
}

Batches

The batch endpoint allows you to create and purchase many shipments in one API call. After creating the batch, retrieve the batch to verify that all shipments are valid. You can add and remove shipments after the batch has been created. When all shipments are valid you can purchase the batch and retrieve the shipping labels.

Attributes
status
"VALIDATING"
"VALID"
"INVALID"
"PURCHASING"
"PURCHASED"		 Batches that are VALIDATING are being created and validated

VALID batches can be purchased

INVALID batches cannot be purchased, INVALID BatchShipments must be removed

Batches that are in the PURCHASING state are being purchased

PURCHASED batches are finished purchasing.
object_created
datetime		 Date and time of Batch creation
object_updated
datetime		 Date and time of last update to the Batch
object_id
string		 Unique identifier of the given Batch object
object_owner
string		 Username of the user who created the Address object.
default_carrier_account
string		 ID of the Carrier Account object to use as the default for all shipments in this Batch. The carrier account can be changed on a per-shipment basis by changing the carrier_account in the corresponding BatchShipment object.
default_servicelevel_token
string		 Token of the service level to use as the default for all shipments in this Batch. The servicelevel can be changed on a per-shipment basis by changing the servicelevel_token in the corresponding BatchShipment object. Servicelevel tokens can be found here.
label_filetype
"PDF"
"PDF_4x6"
"ZPLII"
"PNG"		 Print format of the label. If empty, will use the default format set from the Shippo dashboard.
metadata
string		 A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
batch_shipments
array		 Array of BatchShipment objects. The response keeps the same order as in the request array.
label_url
array		 An array of URLs each pointing to a merged file of 100 labels each
object_results An object containing the following counts:
creation_succeeded
creation_failed
purchase_succeeded
purchase_failed
API Resource URL

https://api.goshippo.com/batches/

Response Example
{
  "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  "object_owner": "shippo@goshippo.com",
  "status": "VALID",
  "object_created": "2016-01-04T00:15:44.394Z",
  "object_updated": "2016-01-04T00:48:13.841Z",
  "metadata": "BATCH #170",
  "default_carrier_account": "078870331023437cb917f5187429b093",
  "default_servicelevel_token": "usps_priority",
  "label_filetype": "PDF_4x6",
  "batch_shipments": {
    "next": null,
    "previous": null,
    "results": [
      {
        "metadata": "",
        "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
        "servicelevel_token": "fedex_2_day",
        "shipment": "99c326a150f54e638b08623833ef152f",
        "transaction": null,
        "object_id": "aa7dea463a5a48b0b8fb21f90e72d779",
        "status": "VALID",
        "messages": []
      },
      {
        "metadata": "",
        "carrier_account": null,
        "servicelevel_token": null,
        "shipment": "77fd9aeaf9b347da9aa95eb250997dc3",
        "transaction": null,
        "object_id": "e11c95a6788d4ddcaa22f03175838740",
        "status": "VALID",
        "messages": []
      }
    ]
  },
  "object_results": {
    "purchase_succeeded": 0,
    "purchase_failed": 0,
    "creation_failed": 0,
    "creation_succeeded": 2
  },
  "label_url": []
}

The batch shipment object

The batch shipment object is a wrapper around a Shipment object, which include shipment-specific information for batch processing.
Note: batch shipments can only be created on the Batch endpoint, either when creating a Batch object or by through the /batches/{BATCH_OBJECT_ID}/add_shipments endpoint

Attributes
object_id
string		 Object ID of this batch shipment. Can be used in the remove_shipments endpoint.
status
"INVALID"
"VALID"
"INCOMPLETE"
"TRANSACTION_
FAILED"		 INVALID batch shipments cannot be purchased and will have to be removed, fixed, and added to the batch again.

VALID batch shipments can be purchased.

batch shipments with the status TRANSACTION_FAILED were not able to be purchased and the error will be displayed on the message field

INCOMPLETE batch shipments have an issue with the Address and will need to be removed, fixed, and added to the batch again.
carrier_account
string		 Object ID of the carrier account to be used for this shipment (will override batch default)
servicelevel_token
string		 A token that sets the shipping method for the batch, overriding the batch default. Servicelevel tokens can be found in this list or at this endpoint.
shipment
string or object		 Object ID of a previously created shipment, to be added to the batch

OR required fields of a new Shipment Object, to be created.
transaction
string		 Object ID of the transaction object created for this batch shipment.
message
array		 List of Shipment and Transaction error messages.
metadata
string		 A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
API Resource URL

https://api.goshippo.com/batches/

Example
{
  "metadata": "",
  "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
  "servicelevel_token": "usps_priority",
  "shipment": "77fd9aeaf9b347da9aa95eb250997dc3",
  "transaction": null,
  "object_id": "adf7a342264b4df1ac5f3c3955fb7603",
  "status": "VALID",
  "messages": []
}

Create a batch

Creates a new batch object which allows you to purchase shipping labels for many shipments with one API call. Batches are created asynchronously. This means that the API response won't include your batch shipments yet. You need to retrieve the batch later to verify that all batch shipments are valid.

Attributes
default_carrier_account
required		 string ID of the Carrier Account object to use as the default for all shipments in this Batch. The carrier account can be changed on a per-shipment basis by changing the carrier_account in the corresponding BatchShipment object.
default_servicelevel_token
required		 string Token of the service level to use as the default for all shipments in this Batch. The servicelevel can be changed on a per-shipment basis by changing the servicelevel_token in the corresponding BatchShipment object.
label_filetype
optional		 "PNG"
"PDF"
"PDF_4x6"
"ZPLII"		 Print format of the label. If empty, will use the default format set from the Shippo dashboard.
metadata
optional		 string A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
batch_shipments
required		 array Array of BatchShipment objects. The response keeps the same order as in the request array.
API Resource URL

https://api.goshippo.com/batches/

Example
var batch = shippo.batch.create({
  "default_carrier_account": "078870331023437cb917f5187429b093",
  "default_servicelevel_token": "usps_priority",
  "label_filetype": "PDF_4x6",
  "metadata": "BATCH #170",
  "batch_shipments": [
    {
      "shipment": {
        "address_from": addressFromOne,
        "address_to": addressToOne,
        "parcels": parcelsOne
      }
    },
    {
      "shipment": {
        "address_from": addressFromTwo,
        "address_to": addressToTwo,
        "parcels": parcelsTwo
      }
    }
  ]
})
Response Example
{
  "object_id": "a015eb693cca465dbb6523ce6d2e3c65",
  "object_owner": "admin",
  "status": "VALIDATING",
  "object_created": "2016-09-12T15:25:43.465Z",
  "object_updated": "2016-09-12T15:25:43.465Z",
  "metadata": "BATCH #170",
  "default_carrier_account": "078870331023437cb917f5187429b093",
  "default_servicelevel_token": "usps_priority",
  "label_filetype": "PDF_4x6",
  "batch_shipments": {
      "next": null,
      "previous": null,
      "results": []
  },
  "object_results": {
      "purchase_succeeded": 0,
      "purchase_failed": 0,
      "creation_failed": 0,
      "creation_succeeded": 0
  },
  "label_url": []
}

Retrieve a batch

Batch shipments are displayed 100 at a time. You can iterate through each "page" using the ?page= query parameter. You can also filter based on batch shipment status; for instance by passing a query param like ?object_results=creation_failed.

Attributes
object_results
optional GET parameter		 "creation_failed"
"creation_succeeded"
"purchase_succeeded"
"purchase_failed"		Filter based on the status of the batch shipment.
API Resource URL

https://api.goshippo.com/batches/<BATCH OBJECT ID>

Example
shippo.batch.retrieve(batchObjectId)
Response Example
{
  "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  "object_owner": "shippo@goshippo.com",
  "status": "INVALID",
  "object_created": "2016-01-04T00:15:44.394Z",
  "object_updated": "2016-01-04T00:48:13.841Z",
  "metadata": "",
  "default_carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
  "default_servicelevel_token": "usps_priority",
  "label_filetype": "PDF_4x6",
  "batch_shipments": {
    "next": "https://api.goshippo.com/batches/5ef63c54f5bf45d3b1f8fb37dcb1c5f4?object_results=creation_failed&page=3",
    "previous": "https://api.goshippo.com/batches/5ef63c54f5bf45d3b1f8fb37dcb1c5f4?object_results=creation_failed&page=1",
    "results": [
      {
        "metadata": "",
        "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
        "servicelevel_token": "fedex_ground",
        "shipment": null,
        "transaction": null,
        "object_id": "e11c95a6788d4ddcaa22f03175838740",
        "status": "INVALID",
        "messages": [
          [
            {
              "address_to": [
                "This field is required."
              ]
            }
          ]
        ]
      }
    ]
  },
  "object_results": {
    "purchase_succeeded": 0,
    "purchase_failed": 0,
    "creation_failed": 3,
    "creation_succeeded": 5
  },
  "label_url": []
}

Add batch shipments to a batch

Add batch shipments to an existing batch.

Attributes
Array
required		 An array consisting of batch shipment objects
API Resource URL

https://api.goshippo.com/batches/<BATCH OBJECT ID>/add_shipments

Example
// Client library is currently being updated to support this API endpoint--please check back soon!
Response Example
{
  "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  "object_owner": "shippo@goshippo.com",
  "status": "VALID",
  "object_created": "2016-01-04T00:15:44.394Z",
  "object_updated": "2016-01-04T00:48:13.841Z",
  "metadata": "",
  "default_carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
  "default_servicelevel_token": "usps_priority",
  "label_filetype": "PDF_4x6",
  "batch_shipments": {
    "next": null,
    "previous": null,
    "results": [
      {
        "metadata": "add batchshipment1",
        "carrier_account": "e11c95a6788d4ddcaa22f03175838740",
        "servicelevel_token": "fedex_2_day",
        "shipment": "99c326a150f54e638b08623833ef152f",
        "transaction": null,
        "object_id": "aa7dea463a5a48b0b8fb21f90e72d779",
        "status": "VALID",
        "messages": []
      },
      {
        "metadata": "add batchshipment2",
        "carrier_account": "d2ce085dd3734a22b20c6df36a63aa07",
        "servicelevel_token": "ups_ground",
        "shipment": "2ba26e9733954b3fb8fef38fbb742676",
        "transaction": null,
        "object_id": "f11b46440c144ce3b97fb5ddf02b8c71",
        "status": "VALID",
        "messages": []
      },
      {
        "metadata": "add batchshipment3",
        "carrier_account":"a4391cd4ab974f478f55dc08b5c8e3b3",
        "servicelevel_token": "usps_priority_express",
        "shipment": "77fd9aeaf9b347da9aa95eb250997dc3",
        "transaction": null,
        "object_id": "5400f9078f764b1bbb121bcd08de127f",
        "status": "VALID",
        "messages": []
      },
      {
        "metadata": "add batchshipment4",
        "carrier_account": null,
        "servicelevel_token": null,
        "shipment": "77fd9aeaf9b347da9aa95eb250997dc3",
        "transaction": null,
        "object_id": "2ab2b452392545908d2cef8861a39c35",
        "status": "VALID",
        "messages": []
      }
    ]
  },
  "object_results": {
    "purchase_succeeded": 0,
    "purchase_failed": 0,
    "creation_failed": 0,
    "creation_succeeded": 4
  },
  "label_url": []
}

Remove batch shipments from a batch

Remove batch shipments from an existing batch.

Attributes
Array
required		 An array consisting of batch shipment object IDs
API Resource URL

https://api.goshippo.com/batches/<BATCH OBJECT ID>/remove_shipments

Example
// Client library is currently being updated to support this API endpoint--please check back soon!
Response Example
{
  "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  "object_owner": "shippo@goshippo.com",
  "status": "VALID",
  "object_created": "2016-01-04T00:15:44.394Z",
  "object_updated": "2016-01-04T00:48:13.841Z",
  "metadata": "",
  "default_carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
  "default_servicelevel_token": "usps_priority",
  "label_filetype": "PDF_4x6",
  "batch_shipments": {
    "next": null,
    "previous": null,
    "results": []
  },
  "object_results": {
    "purchase_succeeded": 0,
    "purchase_failed": 0,
    "creation_failed": 0,
    "creation_succeeded": 0
  },
  "label_url": []
}

Purchase a batch

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

API Resource URL

https://api.goshippo.com/batches/<BATCH OBJECT ID>/purchase

Example
// Client library is currently being updated to support this API endpoint--please check back soon!
Response Example
{
  "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  "object_owner": "shippo@goshippo.com",
  "status": "PURCHASING",
  "object_created": "2016-01-04T00:15:44.394Z",
  "object_updated": "2016-01-04T00:48:13.841Z",
  "metadata": "",
  "default_carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
  "default_servicelevel_token": "usps_priority",
  "label_filetype": "PDF_4x6",
  "batch_shipments": {
    "next": null,
    "previous": null,
    "results": [
      {
        "metadata": "",
        "carrier_account": null,
        "servicelevel_token": null,
        "shipment": "99c326a150f54e638b08623833ef152f",
        "transaction": null,
        "object_id": "aa7dea463a5a48b0b8fb21f90e72d779",
        "status": "VALID",
        "messages": []
      },
      {
        "metadata": "",
        "carrier_account": null,
        "servicelevel_token": null,
        "shipment": "2ba26e9733954b3fb8fef38fbb742676",
        "transaction": null,
        "object_id": "f11b46440c144ce3b97fb5ddf02b8c71",
        "status": "VALID",
        "messages": []
      },
      {
        "metadata": "",
        "carrier_account": null,
        "servicelevel_token": null,
        "shipment": "77fd9aeaf9b347da9aa95eb250997dc3",
        "transaction": null,
        "object_id": "5400f9078f764b1bbb121bcd08de127f",
        "status": "VALID",
        "messages": []
      },
      {
        "metadata": "",
        "carrier_account": null,
        "servicelevel_token": null,
        "shipment": "77fd9aeaf9b347da9aa95eb250997dc3",
        "transaction": null,
        "object_id": "2ab2b452392545908d2cef8861a39c35",
        "status": "VALID",
        "messages": []
      }
    ]
  },
  "object_results": {
    "purchase_succeeded": 1,
    "purchase_failed": 0,
    "creation_failed": 0,
    "creation_succeeded": 4
  },
  "label_url": []
}

Orders

Attributes
object_id
string		 Unique identifier of the order object.
object_owner
string		 Username of the user who created the object.
order_number
string		 An alphanumeric identifier for the order used by the seller/buyer. This identifier doesn't need to be unique.
order_status
"UNKNOWN"
"AWAITPAY"
"PAID"
"REFUNDED"
"CANCELLED"
"PARTIALLY_FULFILLED"
"SHIPPED"		 Current state of the order. See the orders tutorial for the logic of how the status is handled.
placed_at
datetime		 Date and time when the order was placed. This datetime can be different from the datetime of the order object creation on Shippo.
to_address
Address object		 Address object of the recipient / buyer. Will be returned expanded by default.
from_address
Address object		 Address object of the sender / seller. Will be returned expanded by default.
line_items
array of line item objects		 Array of line item objects representing the items in this order. All objects will be returned expanded by default.
shipping_cost
decimal		 Amount paid by the buyer for shipping. This amount can be different from the price the seller will actually pay for shipping.
shipping_cost_currency
ISO 4217 currency code		 Currency of the shipping_cost amount.
shipping_method
string		 Shipping method (carrier + service or other free text description) chosen by the buyer. This value can be different from the shipping method the seller will actually choose.
shop_app
"Amazon"
"Bigcommerce"
"CSV_Import"
"eBay"
"ePages"
"Etsy"
"Godaddy"
"Magento"
"Shippo"
"Shopify"
"Spreecommerce"
"StripeRelay"
"Weebly"
"WooCommerce"		 Platform the order was created on and, if applicable, imported from. Orders created via the Shippo API or dashboard will have the value "Shippo".
total_price
decimal		 Total amount paid by the buyer for this order.
total_tax
decimal		 Total tax amount paid by the buyer for this order.
currency
ISO 4217 currency code		 Currency of the total_price and total_tax amounts.
transactions
array of transaction objects		 Array of transaction objects representing all shipping labels purchased for this order. All objects are returned expanded with a limited number of fields by default.
weight
decimal		 Total weight of the order.
weight_unit
"g"
"oz"
"lb"
"kg"		 The unit used for the weight field.
notes
string		 Custom buyer- or seller-provided notes about the order.
API Resource URL

https://api.goshippo.com/orders/

Response Example
{
    "object_id": "4f2bc588e4e5446cb3f9fdb7cd5e190b",
    "object_owner": "shippotle@goshippo.com",
    "order_number": "#1068",
    "order_status": "PAID",
    "placed_at": "2016-09-23T01:28:12Z",
    "to_address": {
        "object_created": "2016-09-23T01:38:56Z",
        "object_updated": "2016-09-23T01:38:56Z",
        "object_id": "d799c2679e644279b59fe661ac8fa488",
        "object_owner": "shippotle@goshippo.com",
        "is_complete": true,
        "validation_results": {},
        "name": "Mr Hippo",
        "company": "Shippo",
        "street1": "215 Clayton St.",
        "street2": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "phone": "15553419393",
        "email": "shippotle@goshippo.com",
        "is_residential": null,
        "metadata": ""
    },
    "from_address": null,
    "line_items": [
        {
            "object_id": "abf7d5675d744b6ea9fdb6f796b28f28",
            "title": "Hippo Magazines",
            "variant_title": "",
            "sku": "HM-123",
            "quantity": 1,
            "total_price": "12.10",
            "currency": "USD",
            "weight": "0.40",
            "weight_unit": "lb",
            "manufacture_country": null,
            "max_ship_time": null,
            "max_delivery_time": null
        }
    ],
    "shipping_cost": "12.83",
    "shipping_cost_currency": "USD",
    "shipping_method": "USPS First Class Package",
    "shop_app": "Shippo",
    "subtotal_price": "12.10",
    "total_price": "24.93",
    "total_tax": "0.00",
    "currency": "USD",
    "transactions": [
        {
          "object_id": "aef7b48d3aee44eb9a0f26bf75fef2b8",
          "object_status": "SUCCESS",
          "label_url": "https://shippo-delivery-east.s3.amazonaws.com/aef7b48d3aee44eb9a0f26bf75fef2b8.pdf?Signature=r0aI21Hxm289KiMiybWVqWEJimk%3D&Expires=1539232637&AWSAccessKeyId=AKIAJGLCC5MYLLWIG42A",
          "test": false
        }
    ],
    "weight": "0.40",
    "weight_unit": "lb",
    "notes": null
}

The line item object

Line Items, and their corresponding abstract Products and Variants, might be exposed as a separate resource in the future. Currently it's a nested object within the order resource.
Attributes
object_id
string		 Unique identifier of the line item object.
title
string		 Title of the line item.
variant_title
string		 A variant is a specific variation of an item (e.g. "size M" or "color blue"). Variants might be exposed as a separate resource in the future too. Currently the variant title is a free text field describing the variant.
sku
string		 The stock keeping unit value of this item.
quantity
integer		 The quantity of this item in this order.
total_price
decimal		 Total price paid by the buyer for this item (or these items, if quantity > 1).
currency
ISO 4217 currency code		 Currency of the total_price amount.
weight
decimal		 Total weight of this/these item(s). Instead of specifying the weight of all items, you can also set the total_weight value of the order object.
weight_unit
"g"
"oz"
"lb"
"kg"		 The unit used for the weight field.
manufacture_country
string		 Country the item was manufactured in. In the Shippo dashboard, this value will be used ot pre-fill the customs declaration when creating a label for this order.
max_ship_time
datetime		 The date and time this item needs to be fulfilled by, i.e. by when the shipping label needs to be created and handed over to the carrier. This value is used by some platforms such as eBay to measure a seller's handling time and performance. It will be displayed in the Shippo dashboard.
max_delivery_time
datetime		 The date and time this item needs to be delivered by, i.e. by when the carrier delivers it to the buyer. This value is used by some platforms such as eBay to measure a seller's shipping time and performance. It will be displayed in the Shippo dashboard.
API Resource URL

Response Example
{
    "object_id": "abf7d5675d744b6ea9fdb6f796b28f28",
    "title": "Hippo Magazines",
    "variant_title": "June edition",
    "sku": "HM-123",
    "quantity": 1,
    "total_price": "12.10",
    "currency": "USD",
    "weight": "0.40",
    "weight_unit": "lb",
    "manufacture_country": "US",
    "max_ship_time": "2016-07-23T00:00:00Z",
    "max_delivery_time": "2016-07-25T00:00:00Z"
}

Create a new order

Creates a new order object.

Attributes
order_number
optional		 An alphanumeric identifier for the order used by the seller/buyer. This identifier doesn't need to be unique.
order_status
optional		 Current state of the order. See the orders tutorial for the logic of how the status is handled.
placed_at
required		 Date and time when the order was placed. This datetime can be different from the datetime of the order object creation on Shippo.
to_address
required		 Address object of the recipient / buyer. Will be returned expanded by default.
from_address
optional		 Address object of the sender / seller. Will be returned expanded by default.
line_items
optional		 Array of line item objects representing the items in this order. All objects will be returned expanded by default.
shipping_cost
optional		 Amount paid by the buyer for shipping. This amount can be different from the price the seller will actually pay for shipping.
shipping_cost_currency
optional (required if shipping_cost is provided)		 Currency of the shipping_cost amount.
shipping_method
optional		 Shipping method (carrier + service or other free text description) chosen by the buyer. This value can be different from the shipping method the seller will actually choose.
total_price
optional		 Total amount paid by the buyer for this order.
total_tax
optional		 Total tax amount paid by the buyer for this order.
currency
optional (required if total_price is provided)		 Currency of the total_price and total_tax amounts.
weight
required		 Total weight of the order.
weight_unit
required		 The unit used for the weight field.
notes
optional		 Custom buyer- or seller-provided notes about the order.
API Resource URL

https://api.goshippo.com/orders/

Example
Response Example
{
    "object_id": "4f2bc588e4e5446cb3f9fdb7cd5e190b",
    "object_owner": "shippotle@goshippo.com",
    "order_number": "#1068",
    "order_status": "PAID",
    "placed_at": "2016-09-23T01:28:12Z",
    "to_address": {
        "object_state": "VALID",
        "object_purpose": "PURCHASE",
        "object_source": "FULLY_ENTERED",
        "object_created": "2016-09-23T01:38:56Z",
        "object_updated": "2016-09-23T01:38:56Z",
        "object_id": "d799c2679e644279b59fe661ac8fa488",
        "object_owner": "shippotle@goshippo.com",
        "is_complete": true,
        "validation_results": {},
        "name": "Mr Hippo",
        "company": "Shippo",
        "street_no": "",
        "street1": "215 Clayton St.",
        "street2": "",
        "street3": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "longitude": null,
        "latitude": null,
        "phone": "15553419393",
        "email": "shippotle@goshippo.com",
        "is_residential": null,
        "ip": null,
        "messages": [],
        "metadata": ""
    },
    "from_address": null,
    "line_items": [
        {
            "object_id": "abf7d5675d744b6ea9fdb6f796b28f28",
            "title": "Hippo Magazines",
            "variant_title": "",
            "sku": "HM-123",
            "quantity": 1,
            "total_price": "12.10",
            "currency": "USD",
            "weight": "0.40",
            "weight_unit": "lb",
            "manufacture_country": null,
            "max_ship_time": null,
            "max_delivery_time": null
        }
    ],
    "items": [],
    "hidden": false,
    "shipping_cost": "12.83",
    "shipping_cost_currency": "USD",
    "shipping_method": "USPS First Class Package",
    "shop_app": "Shippo",
    "subtotal_price": "12.10",
    "total_price": "24.93",
    "total_tax": "0.00",
    "currency": "USD",
    "transactions": [],
    "weight": "0.40",
    "weight_unit": "lb",
    "notes": null
}

Retrieve an existing order

Retrieve an existing order by object id.

API Resource URL

https://api.goshippo.com/orders/<ORDER OBJECT ID>

Example
Response Example
{
    "object_id": "4f2bc588e4e5446cb3f9fdb7cd5e190b",
    "object_owner": "shippotle@goshippo.com",
    "order_number": "#1068",
    "order_status": "PAID",
    "placed_at": "2016-09-23T01:28:12Z",
    "to_address": {
        "object_state": "VALID",
        "object_purpose": "PURCHASE",
        "object_source": "FULLY_ENTERED",
        "object_created": "2016-09-23T01:38:56Z",
        "object_updated": "2016-09-23T01:38:56Z",
        "object_id": "d799c2679e644279b59fe661ac8fa488",
        "object_owner": "shippotle@goshippo.com",
        "is_complete": true,
        "validation_results": {},
        "name": "Mr Hippo",
        "company": "Shippo",
        "street_no": "",
        "street1": "215 Clayton St.",
        "street2": "",
        "street3": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "longitude": null,
        "latitude": null,
        "phone": "15553419393",
        "email": "shippotle@goshippo.com",
        "is_residential": null,
        "ip": null,
        "messages": [],
        "metadata": ""
    },
    "from_address": null,
    "line_items": [
        {
            "object_id": "abf7d5675d744b6ea9fdb6f796b28f28",
            "title": "Hippo Magazines",
            "variant_title": "",
            "sku": "HM-123",
            "quantity": 1,
            "total_price": "12.10",
            "currency": "USD",
            "weight": "0.40",
            "weight_unit": "lb",
            "manufacture_country": null,
            "max_ship_time": null,
            "max_delivery_time": null
        }
    ],
    "items": [],
    "hidden": false,
    "shipping_cost": "12.83",
    "shipping_cost_currency": "USD",
    "shipping_method": "USPS First Class Package",
    "shop_app": "Shippo",
    "subtotal_price": "12.10",
    "total_price": "24.93",
    "total_tax": "0.00",
    "currency": "USD",
    "transactions": [],
    "weight": "0.40",
    "weight_unit": "lb",
    "notes": null
}

List all orders

List all order objects.

API Resource URL

https://api.goshippo.com/orders/

Example
Response Example
{
   "next":null,
   "previous":null,
   "results":[
      {
         "object_id": "4f2bc588e4e5446cb3f9fdb7cd5e190b",
         "object_owner": "shippotle@goshippo.com",
         "order_number": "#1068",
         "order_status": "PAID",
         "placed_at": "2016-09-23T01:28:12Z",
         "to_address": {
            "object_state": "VALID",
            "object_purpose": "PURCHASE",
            "object_source": "FULLY_ENTERED",
            "object_created": "2016-09-23T01:38:56Z",
            "object_updated": "2016-09-23T01:38:56Z",
            "object_id": "d799c2679e644279b59fe661ac8fa488",
            "object_owner": "shippotle@goshippo.com",
            "is_complete": true,
            "validation_results": {},
            "name": "Mr Hippo",
            "company": "Shippo",
            "street_no": "",
            "street1": "215 Clayton St.",
            "street2": "",
            "street3": "",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94117",
            "country": "US",
            "longitude": null,
            "latitude": null,
            "phone": "15553419393",
            "email": "shippotle@goshippo.com",
            "is_residential": null,
            "ip": null,
            "messages": [],
            "metadata": ""
         },
         "from_address": null,
         "line_items": [
            {
               "object_id": "abf7d5675d744b6ea9fdb6f796b28f28",
               "title": "Hippo Magazines",
               "variant_title": "",
               "sku": "HM-123",
               "quantity": 1,
               "total_price": "12.10",
               "currency": "USD",
               "weight": "0.40",
               "weight_unit": "lb",
               "manufacture_country": null,
               "max_ship_time": null,
               "max_delivery_time": null
            }
         ],
         "items": [],
         "hidden": false,
         "shipping_cost": "12.83",
         "shipping_cost_currency": "USD",
         "shipping_method": "USPS First Class Package",
         "shop_app": "Shippo",
         "subtotal_price": "12.10",
         "total_price": "24.93",
         "total_tax": "0.00",
         "currency": "USD",
         "transactions": [],
         "weight": "0.40",
         "weight_unit": "lb",
         "notes": null
      },
      {...},
      {...}
   ]
}

Pickups

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

Attributes
object_created
datetime		 Date and time of Pickup creation.
object_updated
datetime		 Date and time of last Pickup update.
object_id
string		 Unique identifier of the given Pickup object.
carrier_account
string		 The object ID of your USPS or DHL Express carrier account. You can retrieve this from your Rate requests or our /carrier_accounts endpoint.
location
object		 Location where the parcel(s) will be picked up.
location.building_location_type
"Front Door"
"Back Door"
"Side Door"
"Knock on Door"
"Ring Bell"
"Mail Room"
"Office"
"Reception"
"In/At Mailbox"
"Security Deck"
"Shipping Dock"
"Other"		 Where your parcels will be available for pickup. "Security Deck" and "Shipping Dock" are only supported for DHL Express.
location.building_type
"apartment"
"building"
"department"
"floor"
"room"
"suite"		 The type of building where the pickup is located.
location.instructions
string		 Pickup instructions for the courier. This is a mandatory field if the building_location_type is “Other”.
location.address
object		 The pickup address, which includes your name, company name, street address, city, state, zip code, country, phone number, and email address (strings). Special characters should not be included in any address element, especially name, company, and email.
transactions
array		 The transaction(s) object ID(s) for the parcel(s) that need to be picked up.
requested_start_time
datetime (ISO 8601 date)		 The earliest that you requested your parcels to be ready for pickup. Expressed in the timezone specified in the response.
requested_end_time
datetime (ISO 8601 date)		 The latest that you requested your parcels to be available for pickup. Expressed in the timezone specified in the response.
confirmed_start_time
datetime (ISO 8601 date)		 The earliest that your parcels will be ready for pickup, confirmed by the carrier. Expressed in the timezone specified in the response.
confirmed_end_time
datetime (ISO 8601 date)		 The latest that your parcels will be available for pickup, confirmed by the carrier. Expressed in the timezone specified in the response.
cancel_by_time
datetime (ISO 8601 date)		 The latest time to cancel a pickup. Expressed in the timezone specified in the response. To cancel a pickup, you will need to contact the carrier directly. The ability to cancel a pickup through Shippo may be released in future iterations.
status
"PENDING"
"CONFIRMED"
"ERROR"
"CANCELLED"		 Indicates the status of the pickup.
confirmation_code
string		 Pickup's confirmation code returned by the carrier. To edit or cancel a pickup, you will need to contact USPS or DHL Express directly and provide your confirmation_code.
timezone
string		 The pickup time windows will be in the time zone specified here, not UTC.
messages
array		 An array containing strings of any messages generated during validation.
metadata
string		 A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
is_test
bool		 Indicates whether the object has been created in test mode.
API Resource URL

https://api.goshippo.com/pickups/

Response Example
{
    "object_created": "2020-05-08T17:09:48.028Z",
    "object_updated": "2020-05-08T17:09:48.884Z",
    "object_id": "e0cefba8a75f401e893db1eb09075efb",
    "carrier_account": "6c51273296864869829b96a80fb13ea1",
    "location": {
        "instructions": "Behind screen door",
        "building_location_type": "Other",
        "building_type": "suite",
        "address": {
            "object_id": "50ed4a6f0b0d4635b05315c79529798g",
            "name": "Mrs Hippo",
            "company": "Hungry Hippos",
            "street1": "965 Mission St #201",
            "street2": "",
            "city": "San Francisco",
            "state": "CA",
            "zip": "95122",
            "country": "US",
            "phone": "+14159876543",
            "email": "mrshippo@goshippo.com"
        }
    },
    "transactions": [
        "7439c279b374494c9a80ca24f59e6fc5"
    ],
    "requested_start_time": "2020-05-12T19:00:00Z",
    "requested_end_time": "2020-05-12T23:00:00Z",
    "confirmed_start_time": "2020-05-09T12:00:00Z",
    "confirmed_end_time": "2020-05-09T23:59:59.999Z",
    "cancel_by_time": "2020-05-09T08:00:00Z",
    "status": "CONFIRMED",
    "confirmation_code": "WTC310058750",
    "timezone": "US/Pacific",
    "messages": null,
    "metadata": "Customer ID 123456",
    "is_test": false
}

Create a pickup

You can create a pickup request by sending a POST request to the pickups endpoint.

Attributes
carrier_account
required		 string
location
required		 object
location.building_location_type
required		 "Front Door"
"Back Door"
"Side Door"
"Knock on Door"
"Ring Bell"
"Mail Room"
"Office"
"Reception"
"In/At Mailbox"
"Security Deck"
"Shipping Dock"
"Other"
location.building_type
optional		 "apartment"
"building"
"department"
"floor"
"room"
"suite"
location.instructions
conditional		 string, up to 256 characters
location.address
required		 object
transactions
required		 array of transaction object_ids
requested_start_time
required		 datetime (UTC)
Format "2020-05-12T19:00:00Z"
requested_end_time
required		 datetime (UTC)
Format "2020-05-12T19:00:00Z"
metadata
optional		 string, up to 100 characters
is_test
optional		 boolean
API Resource URL

https://api.goshippo.com/pickups/

Example
Response Example
{
    "object_created": "2020-05-08T17:09:48.028Z",
    "object_updated": "2020-05-08T17:09:48.884Z",
    "object_id": "e0cefba8a75f401e893db1eb09075efb",
    "carrier_account": "6c51273296864869829b96a80fb13ea1",
    "location": {
        "instructions": "Behind screen door",
        "building_location_type": "Other",
        "building_type": "suite",
        "address": {
            "object_id": "50ed4a6f0b0d4635b05315c79529798g",
            "name": "Mrs Hippo",
            "company": "Hungry Hippos",
            "street1": "965 Mission St #201",
            "street2": "",
            "city": "San Francisco",
            "state": "CA",
            "zip": "95122",
            "country": "US",
            "phone": "+14159876543",
            "email": "mrshippo@goshippo.com"
        }
    },
    "transactions": [
        "7439c279b374494c9a80ca24f59e6fc5"
    ],
    "requested_start_time": "2020-05-12T19:00:00Z",
    "requested_end_time": "2020-05-12T23:00:00Z",
    "confirmed_start_time": "2020-05-09T12:00:00Z",
    "confirmed_end_time": "2020-05-09T23:59:59.999Z",
    "cancel_by_time": "2020-05-09T08:00:00Z",
    "status": "CONFIRMED",
    "confirmation_code": "WTC310058750",
    "timezone": "US/Pacific",
    "messages": null,
    "metadata": "Customer ID 123456",
    "is_test": false
}

Service Groups

A service group represents a set of service levels that can be grouped together to organize Rates at Checkout shipping options.

Attributes
name
string		 Name for the service group that will be shown to customers in the response
description
string		 Description for the service group.
type
'LIVE_RATE'
'FLAT_RATE'
'FREE_SHIPPING'		 The type of the service group.
LIVE_RATE: Shippo will make a rating request and return real-time rates for the shipping group, only falling back to the specified flat rate amount if no rates match a service level in the service group.
FLAT_RATE: Returns a shipping option with the specified flat rate amount.
FREE_SHIPPING: Returns a shipping option with a price of $0 only if the total cost of items exceeds the amount defined by free_shipping_threshold_min.
object_id
string		 The unique identifier of the given Service Group object.
flat_rate
string		 String representation of an amount to be returned as the flat rate if 1. The service group is of type LIVE_RATE and no matching rates were found; or 2. The service group is of type FLAT_RATE. Either integers or decimals are accepted.
flat_rate_currency
ISO 4217 currency code (string)		 Currency for the flat rate value. The official ISO 4217 currency codes are used, e.g. "USD", or "EUR".
free_shipping_threshold_min
string		 For service groups of type FREE_SHIPPING, this field must be required to configure the minimum cart total (total cost of items in the cart) for this service group to be returned for rates at checkout.
free_shipping_threshold_currency
ISO 4217 currency code (string)		 Currency for the free shipping cart threshold. The official ISO 4217 currency codes are used, e.g. "USD", or "EUR".
rate_adjustment
integer		 The amount in percent (%) that the service group's returned rate should be adjusted. For example, if this field is set to 5 and the matched rate price is $5.00, the returned value of the service group will be $5.25. Negative integers are also accepted and will discount the rate price by the defined percentage amount.
service_levels
Array of type Service Level		 Defines the service levels for this service group. The Rates at Checkout service will generate rates and compare the service levels in each service group to find a matching rate. The service level object must contain the token of the service level and the object ID of the associated carrier account.
is_active
boolean		 True if the service group is enabled, false otherwise.
API Resource URL

https://api.goshippo.com/service-groups

Response Example
[
  {
      "description": "USPS shipping options",
      "flat_rate": "10",
      "flat_rate_currency": "USD",
      "free_shipping_threshold_currency": null,
      "free_shipping_threshold_min": null,
      "is_active": true,
      "name": "USPS Shipping",
      "object_id": "7552000a5f71473c9378e98fc7322c99",
      "rate_adjustment": 0,
      "service_levels": [
          {
              "account_object_id": "cf27d119739647f68442b191996784e7",
              "service_level_token": "usps_priority_express"
          },
          {
              "account_object_id": "cf27d119739647f68442b191996784e7",
              "service_level_token": "usps_priority_mail_express_international"
          }
      ],
      "type": "LIVE_RATE"
  }
]

List all service groups

List all service group objects.

API Resource URL

https://api.goshippo.com/service-groups

Example
Response Example
[
  {
      "description": "UPS shipping options",
      "flat_rate": "5",
      "flat_rate_currency": "USD",
      "free_shipping_threshold_currency": null,
      "free_shipping_threshold_min": null,
      "is_active": true,
      "name": "UPS shipping",
      "object_id": "7552000a5f71473c9378e98fc7322c99",
      "rate_adjustment": 15,
      "service_levels": [
        {
            "account_object_id": "80feb1633d4a43c898f0058506cfd82d",
            "service_level_token": "ups_next_day_air_saver"
        },
        {
            "account_object_id": "80feb1633d4a43c898f0058506cfd82d",
            "service_level_token": "ups_ground"
        }
      ],
      "type": "LIVE_RATE"
  }
]

Create a new service group

Creates a new service group.

Attributes
name
required, max 50 characters		 string
description
required, max 100 characters		 string
flat_rate
required unless type is FREE_SHIPPING		 positive decimal
flat_rate_currency
required unless type is FREE_SHIPPING		 string (ISO 4217 currency)
free_shipping_threshold_min
optional unless type is FREE_SHIPPING		 positive integer
free_shipping_threshold_currency
optional unless type is FREE_SHIPPING		 string (ISO 4217 currency)
type
required		 string
rate_adjustment
optional		 integer
service_levels
required		 object
API Resource URL

https://api.goshippo.com/service-groups

Example
Response Example
[
  {
      "description": "UPS shipping options",
      "flat_rate": "5",
      "flat_rate_currency": "USD",
      "free_shipping_threshold_currency": null,
      "free_shipping_threshold_min": null,
      "is_active": true,
      "name": "UPS shipping",
      "object_id": "7552000a5f71473c9378e98fc7322c99",
      "rate_adjustment": 15,
      "service_levels": [
        {
            "account_object_id": "80feb1633d4a43c898f0058506cfd82d",
            "service_level_token": "ups_next_day_air_saver"
        },
        {
            "account_object_id": "80feb1633d4a43c898f0058506cfd82d",
            "service_level_token": "ups_ground"
        }
      ],
      "type": "LIVE_RATE"
  }
]

Update an existing service group

PUT request to update an existing service group object. The object_id cannot be updated as it is the unique identifier for the object.

Attributes
object_id
required		 Object ID of the service group to update.
name
required, max 50 characters		 string
description
required, max 50 characters		 string, max 100 characters
flat_rate
required unless type is FREE_SHIPPING		 positive decimal
flat_rate_currency
required unless type is FREE_SHIPPING		 string (ISO 4217 currency)
free_shipping_threshold_min
optional unless type is FREE_SHIPPING		 positive integer
free_shipping_threshold_currency
optional unless type is FREE_SHIPPING		 string (ISO 4217 currency)
type
required		 string
rate_adjustment
optional		 integer
service_levels
required		 object
API Resource URL

https://api.goshippo.com/service-groups

Example
Response Example
[
  {
      "description": "UPS shipping options, updated",
      "flat_rate": "20",
      "flat_rate_currency": "USD",
      "free_shipping_threshold_currency": null,
      "free_shipping_threshold_min": null,
      "is_active": true,
      "name": "UPS shipping",
      "object_id": "7552000a5f71473c9378e98fc7322c99",
      "rate_adjustment": 15,
      "service_levels": [
        {
            "account_object_id": "80feb1633d4a43c898f0058506cfd82d",
            "service_level_token": "ups_next_day_air_saver"
        },
        {
            "account_object_id": "80feb1633d4a43c898f0058506cfd82d",
            "service_level_token": "ups_ground"
        }
      ],
      "type": "LIVE_RATE"
  }
]

Delete a service group

Delete a service group by object ID.

API Resource URL

https://api.goshippo.com/service-groups/<SERVICE GROUP OBJECT ID>

Example
Response Example
204 No Content

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. If the shipment is using a carrier parcel template, the rates returned may be limited to the carrier that provides the box. User parcel templates can be created using a carrier parcel template, where the dimensions will be copied in but the weight can be configured.

Attributes
name
string		 The name of the carrier parcel template
token
string		 The unique string representation of the carrier parcel template
carrier
string		 The name of the carrier that provides this parcel template
length
string		 The length of the package, in units specified by the distance_unit attribute
width
string		 The width of the package, in units specified by the distance_unit attribute
height
string		 The height of the package, in units specified by the distance_unit attribute
distance_unit
*in*
*cm*
*mm*		 The measure unit of the package dimensions in inches, cm, or mm.
is_variable_dimensions
boolean		 True if the carrier parcel template allows custom dimensions, such as USPS Softpack.
API Resource URL

https://api.goshippo.com/parcel-templates

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

List all carrier parcel templates

List all carrier parcel template objects. Use the following querystring 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

API Resource URL

https://api.goshippo.com/parcel-templates

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

Retrieve a specific carrier parcel templates

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

API Resource URL

https://api.goshippo.com/parcel-templates/<CARRIER PARCEL TEMPLATE TOKEN>

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

User Parcel Templates

A user parcel template represents a package used for shipping that has preset dimensions and attributes defined by the user. 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 be created using a carrier parcel template, where the dimensions will be copied from the Carrier presets, but the weight can be configured by the user.

Attributes
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_created
datetime		 Date and time of User Parcel Template creation
object_updated
datetime		 Date and time of last update on User Parcel Template
name
string		 The name of the User Parcel Template
template
object		 The object representing the carrier parcel template, if the template was created from a preset carrier template. Otherwise null.
length
string		 The length of the package, in units specified by the distance_unit attribute
width
string		 The width of the package, in units specified by the distance_unit attribute
height
string		 The height of the package, in units specified by the distance_unit attribute
distance_unit
*in*
*cm*
*mm*		 The measure unit of the package dimensions in inches, cm, or mm
weight
string		 The weight of the package, in units specified by the weight_unit attribute
weight_unit
*lb*
*g*
*kg*
*oz*		 The weight unit of the package, as lb, g, kg, or oz
API Resource URL

https://api.goshippo.com/user-parcel-templates

Response Example
{
  "object_id": "b958d3690bb04bb8b2986724872750f5",
  "object_owner": "shippotle@goshippo.com",
  "object_created": "2013-12-11T19:38:09.729Z",
  "object_updated": "2013-12-11T19:38:09.729Z",
  "name": "My Custom Template",
  "length": "10",
  "width": "8",
  "height": "6",
  "distance_unit": "in",
  "weight": "12",
  "weight_unit": "lb"
}

List all user parcel templates

List all user parcel template objects.

API Resource URL

https://api.goshippo.com/user-parcel-templates

Example
// List user parcel template objects
Response Example
{
  "results": [
    {
      "object_id": "b958d3690bb04bb8b2986724872750f5",
      "object_owner": "shippotle@goshippo.com",
      "object_created": "2013-12-11T19:38:09.729Z",
      "object_updated": "2013-12-11T19:38:09.729Z",
      "name": "My Custom Template",
      "length": "10",
      "width": "8",
      "height": "6",
      "distance_unit": "in",
      "weight": "12",
      "weight_unit": "lb"
    }
  ]
}

Retrieve a specific user parcel template

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

API Resource URL

https://api.goshippo.com/user-parcel-templates/<USER PARCEL TEMPLATE OBJECT ID>

Example
// Retrieve user parcel template object
Response Example
{
  "object_id": "b958d3690bb04bb8b2986724872750f5",
  "object_owner": "shippotle@goshippo.com",
  "object_created": "2013-12-11T19:38:09.729Z",
  "object_updated": "2013-12-11T19:38:09.729Z",
  "name": "My Custom Template",
  "length": "10",
  "width": "8",
  "height": "6",
  "distance_unit": "in",
  "weight": "12",
  "weight_unit": "lb"
}

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 from scratch.

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.

Attributes
name
required		 string
template
optional		 string
length
required, but if using a preset carrier template then this field must be empty		 string
width
required, but if using a preset carrier template then this field must be empty		 string
height
required, but if using a preset carrier template then this field must be empty		 string
distance_unit
required, but if using a preset carrier template then this field must be empty		 'in'
'cm'
'mm'
weight
optional		 string
weight_unit
required if weight is nonempty, empty otherwise		 'lb'
'g'
'kg'
'oz'
API Resource URL

https://api.goshippo.com/user-parcel-templates

Example
// Create user parcel template object
Response Example
{
    "object_id": "b958d3690bb04bb8b2986724872750f5",
    "object_owner": "shippotle@goshippo.com",
    "object_created": "2013-12-11T19:38:09.729Z",
    "object_updated": "2013-12-11T19:38:09.729Z",
    "name": "My Custom Template",
    "length": "10",
    "width": "8",
    "height": "6",
    "distance_unit": "in",
    "weight": "12",
    "weight_unit": "lb"
}

Update an existing user parcel template

Updates an existing user parcel template.

Attributes
name
required		 string
template
optional		 string
length
required, but if using a preset carrier template then this field must be empty		 string
width
required, but if using a preset carrier template then this field must be empty		 string
height
required, but if using a preset carrier template then this field must be empty		 string
distance_unit
required, but if using a preset carrier template then this field must be empty		 'in'
'cm'
'mm'
weight
optional		 string
weight_unit
required if weight is nonempty, empty otherwise		 'lb'
'g'
'kg'
'oz'
API Resource URL

https://api.goshippo.com/user-parcel-templates/<USER PARCEL TEMPLATE OBJECT ID>

Example
// Update user parcel template object
Response Example
{
    "object_id": "b958d3690bb04bb8b2986724872750f5",
    "object_owner": "shippotle@goshippo.com",
    "object_created": "2013-12-11T19:38:09.729Z",
    "object_updated": "2013-12-11T19:38:09.729Z",
    "name": "My Custom Template",
    "length": "10",
    "width": "8",
    "height": "6",
    "distance_unit": "in",
    "weight": "12",
    "weight_unit": "lb"
}

Delete a user parcel template

Delete a user parcel template by object ID.

API Resource URL

https://api.goshippo.com/user-parcel-templates/<USER PARCEL TEMPLATE OBJECT ID>

Example
// Delete user parcel template object
Response Example
204 No Content

Rates at Checkout

Rates at Checkout is a feature that allows merchants to set up curated shipping options for customers in the checkout flow based on data in the shopping cart. The request must include the to address and item information. Optional fields are the from address and package information. If the optional fields are not included, the service will use the default address and/or package configured for Rates at Checkout. The response will be a list of shipping options based on the Service Group configuration (see Service Group configuration for details).

Attributes
title
string		 The name of the service group being returned
amount
string		 The value of the price for the service group, in units of currency of the sender address
currency
string		 The ISO 4217 currency code for the price
amount_local
string		 The value of the price for the service group, in the currency of the destination address
currency_local
string		 The ISO 4217 currency code for the currency describing amount_local
estimated_days
number		 The estimated days in transit of the rate that powers the shipping option, if available.
API Resource URL

https://api.goshippo.com/live-rates

Response Example
{
  "count": 123,
  "next": "https://api.goshippo.com/live-rates?page=2",
  "previous": null,
  "results": [
    {
      "title": "Shipping Option 1",
      "amount": "12.34",
      "currency": "USD",
      "amount_local": "15.48",
      "currency_local": "CAD",
      "estimated_days": 2
    },
    ...
  ],
}

Default Parcel Template for Live Rates

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

Attributes
object_id
string		 Unique identifier of the given User Parcel Template object
name
string		 The name of the User Parcel Template
template
object		 The object representing the carrier parcel template, if the template was created from a preset carrier template. Otherwise null.
length
string		 The length of the package, in units specified by the distance_unit attribute
width
string		 The width of the package, in units specified by the distance_unit attribute
height
string		 The height of the package, in units specified by the distance_unit attribute
distance_unit
*in*
*cm*
*mm*		 The measure unit of the package dimensions in inches, cm, or mm
weight
string		 The weight of the package, in units specified by the weight_unit attribute
weight_unit
*lb*
*g*
*kg*
*oz*		 The weight unit of the package, as lb, g, kg, or oz
API Resource URL

https://api.goshippo.com/live-rates/settings/parcel-template

Response Example
{
  "object_id": "b958d3690bb04bb8b2986724872750f5",
  "name": "My Custom Template",
  "length": "10",
  "width": "8",
  "height": "6",
  "distance_unit": "in",
  "weight": "12",
  "weight_unit": "lb",
  "template": null
}

Generate a live rates request

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

Attributes
address_from
optional		 Fully formed Address object OR the object ID for an existing Address
address_to
required		 Fully formed Address object OR the object ID for an existing Address
line_items
required		 Array of Line Item objects
parcel
optional		 Fully formed Parcel object OR the object ID for an existing User Parcel Template
API Resource URL

https://api.goshippo.com/live-rates

Example
Response Example
{
  "count": 123,
  "next": "https://api.goshippo.com/live-rates?page=2",
  "previous": null,
  "results": [
    {
      "title": "Shipping Option 1",
      "amount": "12.34",
      "currency": "USD",
      "amount_local": "15.48",
      "currency_local": "CAD",
      "estimated_days": 2
    },
    ...
  ]
}

Show current default parcel template

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

API Resource URL

https://api.goshippo.com/live-rates/settings/parcel-template

Example
Response Example
{
  "result": {
    "object_id": "b958d3690bb04bb8b2986724872750f5",
    "name": "My Custom Template",
    "length": "10",
    "width": "8",
    "height": "6",
    "distance_unit": "in",
    "weight": "12",
    "weight_unit": "lb",
    "template": null
  }
}

Update default parcel template

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

Attributes
object_id
required		 string
API Resource URL

https://api.goshippo.com/live-rates/settings/parcel-template

Example
Response Example
{
  "result": {
    "object_id": "b958d3690bb04bb8b2986724872750f5",
    "name": "My Custom Template",
    "length": "10",
    "width": "8",
    "height": "6",
    "distance_unit": "in",
    "weight": "12",
    "weight_unit": "lb",
    "template": null
  }
}

Clear current default parcel template

Clear the currently configured default parcel template for live rates.

API Resource URL

https://api.goshippo.com/live-rates/settings/parcel-template

Example
Response Example
204 No Content

Carriers

The following carrier tokens can be used to reference carriers, e.g. when tracking shipments.

Token Carrier name
airterraAirterra
apc_postalAPC Postal
apgAPG
aramexAramex
asendia_usAsendia US
australia_postAustralia Post (also used for Startrack)
axlehireAxlehire
better_trucksBetterTrucks
borderguruBorderGuru
boxberryBoxberry
bringBring (also used for Posten Norge)
canada_postCanada Post
cdlCDL
chronopostChronopost
collect_plusCollectPlus
correios_brCorreiosBR
correos_espanaCorreos Espana
courierspleaseCouriers Please
deutsche_postDeutsche Post
dhl_beneluxDHL Benelux
dhl_ecommerceDHL eCommerce
dhl_expressDHL Express
dhl_germany_c2cDHL Germany C2C
dhl_germanyDHL Germany
dpd_germanyDPD GERMANY
dpdDPD
dpd_ukDPD UK
estafetaEstafeta
fastway_australiaFastway Australia
fedexFedEx
globegisticsGlobegistics
gls_usGLS US
gophrGophr
gsoGSO
hermes_germany_b2cHermes Germany B2C
hermes_ukEvri UK
hongkong_postHongkong Post
lasershipLaserShip
lsoLSO
mondial_relayMondial Relay
newgisticsNewgistics
new_zealand_postNew Zealand Post (also used for Pace and CourierPost)
nippon_expressNippon Express
ontracOnTrac
orangedsOrangeDS
parcelforceParcelforce
parcelParcel
passportPassport
pcfPCF
postiPosti
purolatorPurolator
royal_mailRoyal Mail
rr_donnelleyRR Donnelley
russian_postRussian Post
sendleSendle
skypostalSkyPostal
stuartStuart
swyftSwyft
udsUDS (United Delivery Service)
upsUPS
uspsUSPS
yodelYodel

Service Levels

The following service level tokens can be used to reference specific rates when purchasing shipping labels using single call label creation (instalabel) and batch label creation endpoints.

You can also find all of the possible service levels for each of your carrier accounts by using this endpoint.

USPS

Token Service name
usps_priorityPriority Mail
usps_priority_expressPriority Mail Express
usps_firstFirst Class Mail/Package
usps_parcel_selectParcel Select
usps_media_mailMedia Mail, only for existing Shippo customers with grandfathered Media Mail option.
usps_priority_mail_internationalPriority Mail International
usps_priority_mail_express_internationalPriority Mail Express International
usps_first_class_package_international_serviceFirst Class Package International

FedEx

Token Service name
fedex_groundFedEx Ground
fedex_home_deliveryFedEx Home Delivery®
fedex_smart_postFedEx SmartPost®
fedex_2_dayFedEx 2Day®
fedex_2_day_amFedEx 2Day® A.M.
fedex_express_saverFedEx Express Saver®
fedex_standard_overnightFedEx Standard Overnight®
fedex_priority_overnightFedEx Priority Overnight®
fedex_first_overnightFedEx First Overnight®
fedex_freight_priorityFedEx Freight® Priority
fedex_next_day_freightFedEx Next Day Freight
fedex_freight_economyFedEx Freight® Economy
fedex_first_freightFedEx First Freight
fedex_international_economyFedEx International Economy
fedex_international_priorityFedEx International Priority®
fedex_international_firstFedEx International First®
fedex_europe_first_international_priorityFedEx International First®
fedex_international_connect_plusFedEx International Connect Plus
fedex_international_economy_freightFedEx International Economy Freight
fedex_international_priority_expressFedEx International Priority® Express
fedex_international_priority_freightFedEx International Priority Freight
fedex_europe_first_international_priorityEurope First International Priority

UPS

Token Service name
ups_standardStandard℠
ups_groundGround
ups_saverSaver®
ups_3_day_select3 Day Select®
ups_second_day_air2nd Day Air®
ups_second_day_air_am2nd Day Air® A.M.
ups_next_day_airNext Day Air®
ups_next_day_air_saverNext Day Air Saver®
ups_next_day_air_early_amNext Day Air® Early
ups_mail_innovations_domesticMail Innovations (domestic)
ups_surepostSurepost
ups_surepost_bound_printed_matterSurePost® Bound Printed Matter
ups_surepost_lightweightSurepost Lightweight
ups_surepost_mediaSurePost® Media
ups_expressExpress®
ups_express_1200Express 12:00
ups_express_plusExpress Plus®
ups_expeditedExpedited®
ups_express_earlyExpress® Early
ups_access_point_economyAccess Point™ Economy

Airterra

Token Service name
airterra_groundGroundXC
airterra_postalFastPost

APC Postal

Token Service name
apc_postal_parcelconnect_expeditedparcelConnect Expedited
apc_postal_parcelconnect_priorityparcelConnect Priority
apc_postal_parcelconnect_priority_delconparcelConnect Priority Delcon
apc_postal_parcelconnect_priority_pqwparcelConnect Priority PQW
apc_postal_parcelconnect_book_serviceparcelConnect Book Service
apc_postal_parcelconnect_standardparcelConnect Standard
apc_postal_parcelconnect_epmiparcelConnect ePMI
apc_postal_parcelconnect_epacketparcelConnect ePacket
apc_postal_parcelconnect_epmeiparcelConnect ePMEI

APG

Token Service name
epacketePacket
epacket_plusePacket Plus
eparcel_premiumeParcel premium
apg_eparcel_expeditedeParcel Expedited

Asendia

Token Service name
asendia_us_priority_trackedAsendia USA Priority Tracked
asendia_us_international_expressAsendia USA International Express
asendia_us_international_priority_airmailAsendia USA International Priority Airmail
asendia_us_international_surface_airliftAsendia USA International Surface Air Lift
asendia_us_priority_mail_internationalAsendia USA Priority Mail International
asendia_us_priority_mail_express_internationalAsendia USA Priority Mail Express International
asendia_us_epacketAsendia USA International ePacket
asendia_us_otherAsendia USA Other Services (custom)

Australia Post

Token Service name
australia_post_express_postExpress Post
australia_post_parcel_postParcel Post
australia_post_pack_and_track_internationalPack and Track International
australia_post_international_airmailInternational Airmail
australia_post_express_post_internationalExpress Post International
australia_post_express_courier_internationalExpress Courier International
australia_post_international_expressInternational Express
australia_post_international_standardInternational Standard
australia_post_international_economyInternational Economy

AxleHire

Token Service name
axlehire_next_dayNext Day

BetterTrucks

Token Service name
better_trucks_same_daySame Day
better_trucks_next_dayNext Day
better_trucks_expressExpress

Canada Post

Token Service name
canada_post_regular_parcelRegular Parcel
canada_post_expedited_parcelExpedited Parcel
canada_post_priorityPriority
canada_post_xpresspostXpresspost
canada_post_xpresspost_internationalXpresspost International
canada_post_xpresspost_usaXpresspost USA
canada_post_expedited_parcel_usaExpedited Parcel USA
canada_post_tracked_packet_usaTracked Packet USA
canada_post_small_packet_usa_airSmall Packet USA Air
canada_post_tracked_packet_internationalTracked Packet International
canada_post_small_packet_international_airSmall Package International Air

CDL

Token Service name
cdl_next_dayNext Day

Chronopost

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

Colissimo

Token Service name
colissimo_homeDomicile
colissimo_pick_up_pointPoint Retrait
colissimo_return_mainland_franceRetour France

Correos España

Token Service name
correos_estandard_home Paquete Estándar
correos_premium_home Paquete Premium

CouriersPlease

Token Service name
couriersplease_domestic_priority_auth_to_leaveDomestic Priority - Authority To Leave/POPPoints
couriersplease_domestic_priority_sign_requiredDomestic Priority - Signature Required
couriersplease_gold_domestic_auth_to_leaveGold Domestic - Authority To Leave/POPPoints
couriersplease_gold_domestic_sign_requiredGold Domestic - Signature Required
couriersplease_off_peak_auth_to_leaveOff Peak - Authority To Leave/POPPoints
couriersplease_off_peak_sign_requiredOff Peak - Signature Required
couriersplease_parcel_auth_to_leaveParcel - Authority To Leave
couriersplease_parcel_sign_requiredParcel - Signature Required
couriersplease_road_expressRoad Express
couriersplease_satchel_auth_to_leaveSatchel - Authority To Leave
couriersplease_satchel_sign_requiredSatchel - Signature Required

Purolator

Token Service name
purolator_groundGround
purolator_ground9_amGround 9am
purolator_ground1030_amGround 10:30am
purolator_ground_distributionGround Distribution
purolator_ground_eveningGround Evening
purolator_ground_usGround US
purolator_expressExpress
purolator_express9_amExpress 9am
purolator_express1030_amExpress 10am
purolator_express_eveningExpress Evening
purolator_express_usExpress US
purolator_express_us9_amExpress US 9am
purolator_express_us1030_amExpress US 10:30am
purolator_express_us1200Express US 12pm
purolator_express_internationalExpress International
purolator_express_international9_amExpress International 9am
purolator_express_international1030_amExpress International 10:30am
purolator_express_international1200Express International 12pm

DHL Express

Token Service name
dhl_express_domestic_express_docDomestic Express Doc
dhl_express_economy_select_docEconomy Select Doc
dhl_express_worldwide_nondocExpress Worldwide Nondoc
dhl_express_worldwide_docExpress Worldwide Doc
dhl_express_worldwideWorldwide
dhl_express_worldwide_eu_docExpress Worldwide EU Doc
dhl_express_break_bulk_express_docBreak Bulk Express Doc
dhl_express_express_9_00_nondocExpress 9:00 NonDoc
dhl_express_economy_select_nondocEconomy Select NonDoc
dhl_express_break_bulk_economy_docBreak Bulk Economy Doc
dhl_express_express_9_00_docExpress 9:00 Doc
dhl_express_express_10_30_docExpress 10:30 Doc
dhl_express_express_10_30_nondocExpress 10:30 NonDoc
dhl_express_express_12_00_docExpress 12:00 Doc
dhl_express_europack_nondocEuropack NonDoc
dhl_express_express_envelope_docExpress Envelope Doc
dhl_express_express_12_00_nondocExpress 12:00 NonDoc
dhl_express_express_12_docDomestic Express 12:00
dhl_express_worldwide_b2c_docExpress Worldwide (B2C) Doc
dhl_express_worldwide_b2c_nondocExpress Worldwide (B2C) NonDoc
dhl_express_medical_expressMedical Express
dhl_express_express_easy_nondocExpress Easy NonDoc

DHL eCommerce

Token Service name
dhl_ecommerce_marketing_parcel_expeditedMarketing Parcel Expedited
dhl_ecommerce_globalmail_business_ipaGlobalMail Business IPA
dhl_ecommerce_parcel_international_directParcel International Direct
dhl_ecommerce_parcels_expedited_maxParcels Expedited Max
dhl_ecommerce_bpm_groundBounded Printed Matter Ground
dhl_ecommerce_priority_expeditedPriority Expedited
dhl_ecommerce_globalmail_packet_ipaGlobalMail Packet IPA
dhl_ecommerce_globalmail_packet_isalGlobalMail Packet ISAL
dhl_ecommerce_easy_return_plusEasy Return Plus
dhl_ecommerce_marketing_parcel_groundMarketing Parcel Ground
dhl_ecommerce_first_class_parcel_expeditedFirst Class Parcel Expedited
dhl_ecommerce_globalmail_business_priorityGlobalMail Business Priority
dhl_ecommerce_parcels_expeditedParcels Expedited
dhl_ecommerce_globalmail_business_isalGlobalMail Business ISAL
dhl_ecommerce_parcel_plus_expedited_maxParcel Plus Expedited Max
dhl_ecommerce_globalmail_packet_plusGlobalMail Packet Plus
dhl_ecommerce_parcels_groundParcels Ground
dhl_ecommerce_expeditedExpedited
dhl_ecommerce_parcel_plus_groundParcel Plus Ground
dhl_ecommerce_parcel_international_standardParcel International Standard
dhl_ecommerce_bpm_expeditedBounded Printed Matter Expedited
dhl_ecommerce_parcel_international_expeditedParcel International Expedited
dhl_ecommerce_globalmail_packet_priorityGlobalMail Packet Priority
dhl_ecommerce_easy_return_lightEasy Return Light
dhl_ecommerce_parcel_plus_expeditedParcel Plus Expedited
dhl_ecommerce_globalmail_business_standardGlobalMail Packet Standard
dhl_ecommerce_groundGround
dhl_ecommerce_globalmail_packet_standardGlobalMail Business Standard

DHL Germany

Token Service name
dhl_germany_europaketDHL Germany Europaket
dhl_germany_paketDHL Germany Paket
dhl_germany_paket_connectDHL Germany Paket Connect
dhl_germany_paket_internationalDHL Germany Paket International
dhl_germany_paket_priorityDHL Germany Paket Priority
dhl_germany_paket_samedayDHL Germany Paket Sameday

DPD DE

Token Service name
dpd_de_classic DPD Classic

DPD UK

Token Service name
dpd_uk_ship_to_shopShip to shop
dpd_uk_1030Door to door 10.30 next day
dpd_uk_1200Door to door 12.00 next day
dpd_uk_saturdaySaturday Delivery
dpd_uk_saturday_1030Saturday Delivery 10.30
dpd_uk_saturday_1200Saturday Delivery 12.00
dpd_uk_sundaySunday Delivery
dpd_uk_sunday_1030Sunday Delivery 10.30
dpd_uk_sunday_1200Sunday Delivery 12.00
dpd_uk_next_dayNext day
dpd_uk_two_dayTwo day
dpd_uk_classicDPD Classic
dpd_uk_air_classicDPD Air Classic
dpd_uk_air_expressDPD Air Express
dpd_uk_directDPD Direct
dpd_uk_direct_tracked_mailDPD Tracked Mail
dpd_uk_pickup_returnsPickup Returns

Deutsche Post

Token Service name
deutsche_post_postkartePostkarte
deutsche_post_standardbriefStandardbrief
deutsche_post_kompaktbriefKompaktbrief
deutsche_post_grossbriefGrossbrief
deutsche_post_maxibriefMaxibrief
deutsche_post_maxibrief_plusMaxibrief Plus
deutsche_post_warenpost_international_xsWarenpost International XS
deutsche_post_warenpost_international_sWarenpost International S
deutsche_post_warenpost_international_mWarenpost International M
deutsche_post_warenpost_international_lWarenpost International L

Fastway Australia

Token Service name
fastway_australia_parcelParcel
fastway_australia_satchelSatchel
fastway_australia_box_smallBox Small
fastway_australia_box_mediumBox Medium
fastway_australia_box_largeBox Large

Globegistics

Token Service name
globegistics_priority_mail_express_internationalGlobegistics Priority Mail Express International
globegistics_priority_mail_internationalGlobegistics Priority Mail International
globegistics_priority_mail_express_international_pdsGlobegistics Priority Mail Express International PreSort Drop Ship
globegistics_priority_mail_international_pdsGlobegistics Priority Mail International PreSort Drop Ship
globegistics_epacketGlobegistics ePacket
globegistics_ecom_tracked_ddpGlobegistics eCom Tracked DDP
globegistics_ecom_packet_ddpGlobegistics eCom Packet DDP
globegistics_ecom_priority_mail_international_ddpGlobegistics eCom Priority Mail International DDP
globegistics_ecom_priority_mail_express_international_ddpGlobegistics eCom Priority Mail Express International DDP
globegistics_ecom_extraGlobegistics eCom Extra
globegistics_ecom_international_priority_airmailGlobegistics eCom International Priority Airmail
globegistics_ecom_international_surface_airliftGlobegistics eCom International Surface Air Lift

GLS US

Token Service name
gls_us_cpsGSO Ground
gls_us_epsEarly Priority Overnight
gls_us_essEarly Saturday Delivery
gls_us_npsNoon Priority Overnight
gls_us_pdsPriority Overnight
gls_us_sdsSaturday Delivery

LSO

Token Service name
lso_groundGround
lso_economy_next_dayEconomy Next Day
lso_saturday_deliverySaturday Delivery
lso_2nd_day2nd Day
lso_priority_next_dayPriority Next Day
lso_early_overnightEarly Overnight

Mondial Relay

Token Service name
mondial_relay_pointrelaisPoint Relais

Parcelforce

Token Service name
parcelforce_express48Express 48
parcelforce_express24Express 24
parcelforce_expressamExpress AM

Poste Italiane

Token Service name
poste_italiane_delivery_business_express Poste Delivery Business Express

RR Donnelley

Token Service name
rr_donnelley_domestic_economy_parcelDomestic Economy Parcel
rr_donnelley_domestic_priority_parcelDomestic Priority Parcel
rr_donnelley_domestic_parcel_bpmDomestic Parcel BPM
rr_donnelley_priority_domestic_priority_parcel_bpmDomestic Priority Parcel BPM
rr_donnelley_priority_parcel_delconInternational Priority Parcel DelCon
rr_donnelley_priority_parcel_nondelconInternational Priority Parcel NonDelcon
rr_donnelley_economy_parcelEconomy Parcel Service
rr_donnelley_ipaInternational Priority Airmail (IPA)
rr_donnelley_courierInternational Courier
rr_donnelley_isalInternational Surface Air Lift (ISAL)
rr_donnelley_epackete-Packet
rr_donnelley_pmiPriority Mail International
rr_donnelley_emiExpress Mail International

Royal Mail

Token Service name
royal_mail_tracked_letter_boxable_24_no_signatureRoyal Mail Tracked Letter-Boxable 24 No Signature
royal_mail_tracked_letter_boxable_48_no_signatureRoyal Mail Tracked Letter-Boxable 48 No Signature
royal_mail_tracked_24_returnsRoyal Mail Tracked Returns 24
royal_mail_tracked_48_returnsRoyal Mail Tracked Returns 48

Sendle

Token Service name
sendle_parcelSendle Parcel

Swyft

Token Service name
same_daySame day
next_dayNext day

UDS

Token Service name
uds_next_dayNext day

Newgistics

Token Service name
newgistics_parcel_select_lightweightParcel Select Lightweight
newgistics_parcel_selectParcel Select
newgistics_priority_mailPriority Mail
newgistics_first_class_mailFirst Class Mail

OnTrac

Token Service name
ontrac_groundGround
ontrac_sunrise_goldSunrise Gold
ontrac_sunriseSunrise

Lasership

Token Service name
lasership_routed_deliveryRouted Delivery

Evri UK

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

Parcel Templates

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

FedEx

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

UPS

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

USPS

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

DHL eCommerce

Token Name Dimensions
DHLeC_Irregular Irregular Shipment
DHLeC_SM_Flats Flats

DPD UK

Token Name Dimensions
DPD_UK_Express_Pak DPD UK Express Pak

CouriersPlease

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

Fastway Australia

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