Use this API to integrate with the Shippo service
Shippo external API. (2018-02-08)
Download OpenAPI description
Overview
Languages
Servers
https://api.goshippo.com
First-time users and those looking for specific integration tutorials,
see our full API documentation and guides.
Download the API Specification yaml file
API Resources
All API URLs listed in this documentation are relative to https://api.goshippo.com/.For example, the /addresses/ resource is reachable at https://api.goshippo.com/addresses/.
Authentication
The API requires Shippo's token HTTP Authentication with your Shippo token (live or test).In order to authenticate properly, please put Authorization: ShippoToken <token> in your header. You can find your token on the Shippo API settings page.
For more information about authentication and test mode, please visit our Authentication guide.
The API is available via Secure Socket Layer (SSL) only. All requests to the Shippo API must use TLS version 1.2 or higher.
Request & Response Data
Request data is passed to the API by POSTing JSON objects with the appropriate key/value-pairs to the respective resource. The documentation for each API resource contains more details on the values accepted by a given resource.Response data also formatted as JSON object. You can specify how many results per page are to be returned. For instance, /rates/?results=25 will return up to 25 results.
REST & Disposable Objects
The Shippo API is built around REST principles. Use POST requests to create objects, GET requests to retrieve objects, and PUT requests to update objects.Only the Carrier Accounts object can be updated via PUT requests. All other objects such as Addresses, Parcels, Shipments, Rates, Transactions, Refunds, Customs Items, and Customs Declarations are disposable. This means that once you have created an object, you cannot change it. Instead, create a new one with the desired values.
API Version
This reference guide supports the Shippo API version: 2018-02-08 .
To see reference guides for older API versions, see our legacy reference guide. For more information about Shippo API versions, see our API versions guide.
An object holding optional extra services to be requested for each parcel in a multi-piece shipment. The following values are supported for the extra field of the parcel object.
Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.
Example: "1"
The measure unit used for length, width and height.
Enum"cm""in""ft""m""mm""yd"
Height of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.
Example: "1"
Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.
Example: "1"
Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.
Example: "1"
Date and time of Parcel creation.
Example: "2014-07-09T02:19:13.174Z"
Unique identifier of the given Parcel object. This ID is required to create a Shipment object.
Example: "adcfdddf8ec64b84ad22772bce3ea37a"
Username of the user who created the Parcel object.
Example: "shippotle@shippo.com"
A Parcel will only be valid when all required values have been sent and validated successfully.
Value"VALID"
Example: "VALID"
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.
Example: "2014-07-09T02:19:13.174Z"
templateFedEx Parcel Template (string) or UPS Parcel Template (string) or USPS Parcel Template (string) or DHL eCommerce Parcel Template (string) or DPD UK Parcel Template (string) or Aramex Australia Parcel Template (string)(ParcelTemplateEnumSet)
One of:
- FedEx Parcel Template
- UPS Parcel Template
- USPS Parcel Template
- DHL eCommerce Parcel Template
- DPD UK Parcel Template
- Aramex Australia Parcel Template
| Token | Name | Dimensions |
|---|---|---|
| FedEx_Box_10kg | FedEx® 10kg Box | 15.81 x 12.94 x 10.19 in |
| FedEx_Box_25kg | FedEx® 25kg Box | 54.80 x 42.10 x 33.50 in |
| FedEx_Box_Extra_Large_1 | FedEx® Extra Large Box (X1) | 11.88 x 11.00 x 10.75 in |
| FedEx_Box_Extra_Large_2 | FedEx® Extra Large Box (X2) | 15.75 x 14.13 x 6.00 in |
| FedEx_Box_Large_1 | FedEx® Large Box (L1) | 17.50 x 12.38 x 3.00 in |
| FedEx_Box_Large_2 | FedEx® Large Box (L2) | 11.25 x 8.75 x 7.75 in |
| FedEx_Box_Medium_1 | FedEx® Medium Box (M1) | 13.25 x 11.50 x 2.38 in |
| FedEx_Box_Medium_2 | FedEx® Medium Box (M2) | 11.25 x 8.75 x 4.38 in |
| FedEx_Box_Small_1 | FedEx® Small Box (S1) | 12.38 x 10.88 x 1.50 in |
| FedEx_Box_Small_2 | FedEx® Small Box (S2) | 11.25 x 8.75 x 4.38 in |
| FedEx_Envelope | FedEx® Envelope | 12.50 x 9.50 x 0.80 in |
| FedEx_Padded_Pak | FedEx® Padded Pak | 11.75 x 14.75 x 2.00 in |
| FedEx_Pak_1 | FedEx® Large Pak | 15.50 x 12.00 x 0.80 in |
| FedEx_Pak_2 | FedEx® Small Pak | 12.75 x 10.25 x 0.80 in |
| FedEx_Tube | FedEx® Tube | 38.00 x 6.00 x 6.00 in |
| FedEx_XL_Pak | FedEx® Extra Large Pak | 17.50 x 20.75 x 2.00 in |
string(FedEx Parcel Template)
Enum"FedEx_Box_10kg""FedEx_Box_25kg""FedEx_Box_Extra_Large_1""FedEx_Box_Extra_Large_2""FedEx_Box_Large_1""FedEx_Box_Large_2""FedEx_Box_Medium_1""FedEx_Box_Medium_2""FedEx_Box_Small_1""FedEx_Box_Small_2"
{ "extra": { "COD": { … }, "insurance": { … }, "reference_1": "string", "reference_2": "string" }, "metadata": "Customer ID 123456", "mass_unit": "lb", "weight": "1", "distance_unit": "in", "height": "1", "length": "1", "width": "1", "object_created": "2014-07-09T02:19:13.174Z", "object_id": "adcfdddf8ec64b84ad22772bce3ea37a", "object_owner": "shippotle@shippo.com", "object_state": "VALID", "object_updated": "2014-07-09T02:19:13.174Z", "template": "FedEx_Box_10kg", "test": true }
An object holding optional extra services to be requested for each parcel in a multi-piece shipment. The following values are supported for the extra field of the parcel object.
To add insurance to your parcel, specify amount, content and currency.
If you do not want to add insurance to you parcel, do not set these parameters.
Optional text to be printed on the shipping label if supported by carrier. Up to 50 characters.
Carrier-Specific Constraints:
| Carrier | Constraints |
|---|---|
| FedEx | Max 40 characters (Express services); Max 30 characters (Ground services) |
{ "COD": { "amount": "5.5", "currency": "USD", "payment_method": "CASH" }, "insurance": { "amount": "5.5", "content": "Laptop", "currency": "USD", "provider": "UPS" }, "reference_1": "string", "reference_2": "string" }
Headers
Optional string used to pick a non-default API version to use. See our API version guide.
Example: 2018-02-08
- https://api.goshippo.com/parcels
- cURL
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl https://api.goshippo.com/parcels/ \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"Response
application/json
{ "next": "baseurl?page=3&results=10", "previous": "baseurl?page=1&results=10", "results": [ { … } ] }
A carrier parcel template represents a package used for shipping that has preset dimensions defined by a carrier. Some examples of a carrier parcel template include USPS Flat Rate Box and Fedex Small Pak. When using a carrier parcel template, the rates returned may be limited to the carrier that provides the box. You can create user parcel templates using a carrier parcel template. Shippo takes the dimensions of the carrier parcel template but you must configure the weight.
SchemasOperations
A user parcel template represents a package used for shipping that has preset dimensions and attributes defined by you. They are useful for capturing attributes of parcel-types you frequently use for shipping, allowing them to be defined once and then used for many shipments. These parcel templates can also be used for live rates.
User parcel templates can also be created using a carrier parcel template, where the dimensions will be copied from the carrier presets, but the weight can be configured by you.
SchemasOperations
A batch is a technique for creating multiple labels at once. Use the batch object to create and purchase many shipments in two API calls. After creating the batch, retrieve the batch to verify that all shipments are valid. You can add and remove shipments after you have created the batch. When all shipments are valid you can purchase the batch and retrieve all the shipping labels.
SchemasOperations
If you purchased your shipping label through Shippo, you can also get all the tracking details of your Shipment
from the Transaction object.
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.
SchemasOperations
Webhooks are a way for Shippo to notify your application when a specific event occurs. For example, when a label is purchased or when a shipment tracking status has changed. You can use webhooks to trigger actions in your application, such as sending an email or updating a database.
SchemasOperations
A manifest is a single-page document with a barcode that carriers can scan to accept all packages into transit without the need to scan each item individually. They are close-outs of shipping labels of a certain day. Some carriers require manifests to process the shipments.
SchemasOperations
An order is a request from a customer to purchase goods from a merchant. Use the orders object to load orders from your system to the Shippo dashboard. You can use the orders object to create, retrieve, list, and manage orders programmatically. You can also retrieve shipping rates, purchase labels, and track shipments for each order.
SchemasOperations
Rates at checkout is a tool for merchants to display up-to-date shipping estimates based on what's in their customers cart and where they’re shipping to. Merchants set up curated shipping options for customers in the checkout flow based on data in the shopping cart. The request must include the to address and item information. Optional fields are the from address and package information. If the optional fields are not included, the service will use the default address and/or package configured for rates at checkout. The response is a list of shipping options based on the Service Group configuration. (see Service Group configuration for details).
SchemasOperations
Shippo Accounts are used by Shippo Platform Accounts to create and manage Managed Shippo Accounts. Managed Shippo Accounts are headless accounts that represent your customers. They are opaque to your end customers, meaning customers do not need to create their own Shippo login or have a billing relationship with Shippo. They can be used by marketplaces, e-commerce platforms, and third-party logistics providers who want to offer, seamless, built-in shipping functionality to their customers. See our guide for more details.
SchemasOperations
| Token | Carrier name |
|---|---|
| airterra | Airterra |
| apc_postal | APC Postal |
| apg | APG |
| aramex | Aramex |
| asendia_us | Asendia US |
| australia_post | Australia Post (also used for Startrack) |
| axlehire | Jitsu |
| better_trucks | BetterTrucks |
| borderguru | BorderGuru |
| boxberry | Boxberry |
| bring | Bring (also used for Posten Norge) |
| canada_post | Canada Post |
| cdl | CDL |
| chronopost | Chronopost |
| collect_plus | CollectPlus |
| correios_br | CorreiosBR |
| correos_espana | Correos España |
| colissimo | Colissimo |
| deutsche_post | Deutsche Post |
| dhl_benelux | DHL Benelux |
| dhl_ecommerce | DHL eCommerce |
| dhl_express | DHL Express |
| dhl_germany_c2c | DHL Germany C2C |
| dhl_germany | DHL Germany |
| dpd_de | DPD GERMANY |
| dpd_uk | DPD UK |
| estafeta | Estafeta |
| fastway_australia | Aramex |
| fedex | FedEx |
| globegistics | Globegistics (now Asendia) |
| gls_us | GLS US |
| gophr | Gophr |
| gso | GSO |
| hermes_germany_b2c | Hermes Germany B2C |
| hermes_uk | Evri UK |
| hongkong_post | Hongkong Post |
| lasership | LaserShip |
| lso | LSO |
| mondial_relay | Mondial Relay |
| new_zealand_post | New Zealand Post (also used for Pace and CourierPost) |
| nippon_express | Nippon Express |
| ontrac | OnTrac |
| parcelforce | Parcelforce |
| passport | Passport |
| pcf | PCF |
| poste_italiane | Poste Italiane |
| posti | Posti |
| purolator | Purolator |
| royal_mail | Royal Mail |
| royal_mail_sf | Royal Mail Storefeeder |
| rr_donnelley | ePost Global |
| russian_post | Russian Post |
| skypostal | SkyPostal |
| stuart | Stuart |
| swyft | Swyft |
| uds | UDS (United Delivery Service) |
| ups | UPS |
| usps | USPS |
| veho | Veho |
Validation result codes returned by the address validation service.
Allowed values:
verification_errorunknown_streetcomponent_mismatch_errormultiple_matchsub_premise_number_invalidsub_premise_number_missingpremise_number_invalidpremise_number_missingbox_number_invalidbox_number_missingpmb_number_missingpostal_code_changeadministrative_area_changelocality_changedependent_locality_changestreet_name_changestreet_type_changestreet_directional_changesub_premise_type_changesub_premise_number_changedouble_dependent_locality_changesubadministrative_area_changesubnational_area_changepo_box_changepremise_type_changehouse_number_changeorganization_changeextraneous_informationusps_door_inaccessibleadministrative_area_partialcity_partialstreet_partialbuilding_partialsubpremise_partialadministrative_area_fullcity_fullthoroughfare_fullpremises_fullsubpremise_fullgeocoded_streetgeocoded_neighborhoodgeocoded_communitygeocoded_stategeocoded_rooftopgeocoded_interpolated_rooftopinvalid_postal_codepostal_code_not_foundempty_requestservice_errorstreet_detail_missingInvalid City/State/ZipDefault MatchUnknown StreetAddress Not FoundNon-Deliverable ZIP4Multiple ResponsesInvalid Dual AddressInvalid StateInvalid CityAmbiguous Address
B13A Option details are obtained by filing a B13A Canada Export Declaration via the Canadian Export Reporting System (CERS). More information on reporting commercial exports from Canada.
Allowed values:
FILED_ELECTRONICALLYSUMMARY_REPORTINGNOT_REQUIRED