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.
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
Required if total_price is provided
Currency of the total_price and total_tax amounts.
Example: "USD"
Custom buyer- or seller-provided notes about the order.
Example: "This customer is a VIP"
An alphanumeric identifier for the order used by the seller/buyer. This identifier doesn't need to be unique.
Example: "#1068"
Current state of the order. See the orders tutorial for the logic of how the status is handled.
Enum"UNKNOWN""AWAITPAY""PAID""REFUNDED""CANCELLED""PARTIALLY_FULFILLED""SHIPPED"
Date and time when the order was placed. This datetime can be different from the datetime of the order object creation on Shippo.
Example: "2016-09-23T01:28:12Z"
Amount paid by the buyer for shipping. This amount can be different from the price the seller will actually pay for shipping.
Example: "12.83"
Required if shipping_cost is provided
Currency of the shipping_cost amount.
Example: "USD"
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.
Example: "USPS First Class Package"
Address object of the sender / seller. Will be returned expanded by default.
Address object of the recipient / buyer. Will be returned expanded by default.
Array of line item objects representing the items in this order. All objects will be returned expanded by default.
Platform the order was created on and, if applicable, imported from. Orders created via the Shippo API or dashboard will have the value "Shippo".
Enum"Amazon""Bigcommerce""CSV_Import""eBay""ePages""Etsy""Godaddy""Magento""Shippo""Shopify"
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.
{ "currency": "USD", "notes": "This customer is a VIP", "order_number": "#1068", "order_status": "PAID", "placed_at": "2016-09-23T01:28:12Z", "shipping_cost": "12.83", "shipping_cost_currency": "USD", "shipping_method": "USPS First Class Package", "subtotal_price": "12.1", "total_price": "24.93", "total_tax": "0.0", "weight": "0.4", "weight_unit": "lb", "from_address": { "name": "Shwan Ippotle", "company": "Shippo", "street1": "215 Clayton St.", "street2": "string", "street3": "", "street_no": "", "city": "San Francisco", "state": "CA", "zip": "94117", "country": "US", "phone": "+1 555 341 9393", "email": "shippotle@shippo.com", "is_residential": true, "metadata": "Customer ID 123456", "is_complete": true, "latitude": 0, "longitude": 0, "object_created": "2014-07-09T02:19:13.174Z", "object_id": "d799c2679e644279b59fe661ac8fa488", "object_owner": "shippotle@shippo.com", "object_updated": "2014-07-09T02:19:13.174Z", "validation_results": { … }, "test": false }, "to_address": { "name": "Shwan Ippotle", "company": "Shippo", "street1": "215 Clayton St.", "street2": "string", "street3": "", "street_no": "", "city": "San Francisco", "state": "CA", "zip": "94117", "country": "US", "phone": "+1 555 341 9393", "email": "shippotle@shippo.com", "is_residential": true, "metadata": "Customer ID 123456", "is_complete": true, "latitude": 0, "longitude": 0, "object_created": "2014-07-09T02:19:13.174Z", "object_id": "d799c2679e644279b59fe661ac8fa488", "object_owner": "shippotle@shippo.com", "object_updated": "2014-07-09T02:19:13.174Z", "validation_results": { … }, "test": false }, "line_items": [ { … } ], "object_id": "adcfdddf8ec64b84ad22772bce3ea37a", "object_owner": "shippotle@shippo.com", "shop_app": "Shippo", "transactions": [ {} ] }
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.
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.
Example: "US"
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.
Example: "2016-07-23T00:00:00Z"
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.
Example: "2016-07-23T00:00:00Z"
Total price paid by the buyer for this item (or these items, if quantity > 1).
Example: "12.1"
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.
Example: "June Edition"
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.
Example: "0.4"
{ "currency": "USD", "manufacture_country": "US", "max_delivery_time": "2016-07-23T00:00:00Z", "max_ship_time": "2016-07-23T00:00:00Z", "quantity": 20, "sku": "HM-123", "title": "Hippo Magazines", "total_price": "12.1", "variant_title": "June Edition", "weight": "0.4", "weight_unit": "lb", "object_id": "abf7d5675d744b6ea9fdb6f796b28f28" }
Query
Filter orders by order status
Items Enum"UNKNOWN""AWAITPAY""PAID""REFUNDED""CANCELLED""PARTIALLY_FULFILLED""SHIPPED"
Example: order_status[]=PAID
Filter orders by shop app
Enum"Amazon""Bigcommerce""CSV_Import""eBay""ePages""Etsy""Godaddy""Magento""Shippo""Shopify"
Example: shop_app=Shippo
Filter orders created after the input date and time (ISO 8601 UTC format). This is based on the placed_at field, meaning when the order has been placed, not when the order object was created.
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/orders
- cURL
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl https://api.goshippo.com/orders/ \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"Response
application/json
{ "next": "baseurl?page=3&results=10", "previous": "baseurl?page=1&results=10", "results": [ { … } ] }
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