Use this API to integrate with the Shippo service
- List all shipping labels
Transaction
Create a shipping label
Retrieve a shipping label
List all shipping labels
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 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.
Any of:
An object with details about the user who created the Transaction (purchased the label). A value will be returned only for Transactions that can be associated with a specific user, e.g. when a logged-in user purchases a label via the Shippo Web application; but not for Transactions purchased e.g. via the API using a ShippoToken, which is associated with the account but not any specific user.
Print format of the label. If empty, will use the default format set from the Shippo dashboard.
Enum"PNG""PNG_2.3x7.5""PDF""PDF_2.3x7.5""PDF_4x6""PDF_4x8""PDF_A4""PDF_A5""PDF_A6""ZPLII"
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.
Example: "https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
Unique identifier of the given Transaction object.
Example: "915d94940ea54c3a80cbfa328722f5a1"
Username of the user who created the Transaction object.
Example: "shippotle@shippo.com"
Indicates the validity of the enclosing object
Enum"VALID""INVALID"
Object ID of the Parcel object that is being shipped.
Example: "e94c7fdfdc7b495dbb390a28d929d90a"
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.
Example: "https://shippo-delivery.s3.amazonaws.com/96_qr_code.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
ID of the Rate object for which a Label has to be obtained.
If you purchase a label by calling the transaction endpoint without a rate (instalabel), this field will be a simplified Rate object in the Transaction model returned from the POST request.
Note, only rates less than 7 days old can be purchased to ensure up-to-date pricing.
One of:
ID of the Rate object for which a Label has to be obtained.
If you purchase a label by calling the transaction endpoint without a rate (instalabel), this field will be a simplified Rate object in the Transaction model returned from the POST request.
Note, only rates less than 7 days old can be purchased to ensure up-to-date pricing.
Indicates the status of the Transaction.
Enum"WAITING""QUEUED""SUCCESS""ERROR""REFUNDED""REFUNDPENDING""REFUNDREJECTED"
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.
Example: "9499907123456123456781"
Indicates the high level status of the shipment.
Enum"UNKNOWN""PRE_TRANSIT""TRANSIT""DELIVERED""RETURNED""FAILURE"
{ "commercial_invoice_url": "string", "created_by": { "first_name": "Shwan", "last_name": "Ippotle", "username": "shippotle@shippo.com" }, "eta": "string", "label_file_type": "PDF_4x6", "label_url": "https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA", "messages": [ { … } ], "metadata": "string", "object_created": "2019-08-24T14:15:22Z", "object_id": "915d94940ea54c3a80cbfa328722f5a1", "object_owner": "shippotle@shippo.com", "object_state": "VALID", "object_updated": "2019-08-24T14:15:22Z", "parcel": "e94c7fdfdc7b495dbb390a28d929d90a", "qr_code_url": "https://shippo-delivery.s3.amazonaws.com/96_qr_code.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA", "rate": { "amount": "5.5", "amount_local": "5.5", "currency": "USD", "currency_local": "USD", "object_id": "adcfdddf8ec64b84ad22772bce3ea37a", "provider": "USPS", "carrier_account": "078870331023437cb917f5187429b093", "servicelevel_name": "Priority Mail", "servicelevel_token": "fedex_ground" }, "status": "SUCCESS", "test": true, "tracking_number": "9499907123456123456781", "tracking_status": "DELIVERED", "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781" }
Query
Filter by object status
Enum"WAITING""QUEUED""SUCCESS""ERROR""REFUNDED""REFUNDPENDING""REFUNDREJECTED"
Example: object_status=SUCCESS
Filter by tracking status
Enum"UNKNOWN""PRE_TRANSIT""TRANSIT""DELIVERED""RETURNED""FAILURE"
Example: tracking_status=DELIVERED
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/transactions
- cURL
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl https://api.goshippo.com/transactions/ \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"Response
application/json
{ "next": "baseurl?page=3&results=10", "previous": "baseurl?page=1&results=10", "results": [ { … } ] }
Request
Creates a new transaction object and purchases the shipping label using a rate object that has previously been created.
OR
Creates a new transaction object and purchases the shipping label instantly using shipment details, an existing carrier account, and an existing service level token.
Security
APIKeyHeader
Headers
Bodyapplication/jsonrequiredOptional string used to pick a non-default API version to use. See our API version guide.
Example: 2018-02-08
Examples.
One of:
Print format of the label. If empty, will use the default format set from the Shippo dashboard.
Enum"PNG""PNG_2.3x7.5""PDF""PDF_2.3x7.5""PDF_4x6""PDF_4x8""PDF_A4""PDF_A5""PDF_A6""ZPLII"
- https://api.goshippo.com/transactions
- cURL
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken {{token}}' \
--header 'Content-Type: application/json' \
--header 'SHIPPO-API-VERSION: 2018-02-08' \
--data-raw '{
"rate": "a5c9d1bec93149f5bedc3a9374b50970",
"async": false,
"label_file_type": "PDF"
}'Bodyapplication/json
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.
Any of:
An object with details about the user who created the Transaction (purchased the label). A value will be returned only for Transactions that can be associated with a specific user, e.g. when a logged-in user purchases a label via the Shippo Web application; but not for Transactions purchased e.g. via the API using a ShippoToken, which is associated with the account but not any specific user.
Print format of the label. If empty, will use the default format set from the Shippo dashboard.
Enum"PNG""PNG_2.3x7.5""PDF""PDF_2.3x7.5""PDF_4x6""PDF_4x8""PDF_A4""PDF_A5""PDF_A6""ZPLII"
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.
Example: "https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
Unique identifier of the given Transaction object.
Example: "915d94940ea54c3a80cbfa328722f5a1"
Username of the user who created the Transaction object.
Example: "shippotle@shippo.com"
Indicates the validity of the enclosing object
Enum"VALID""INVALID"
Object ID of the Parcel object that is being shipped.
Example: "e94c7fdfdc7b495dbb390a28d929d90a"
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.
Example: "https://shippo-delivery.s3.amazonaws.com/96_qr_code.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
ID of the Rate object for which a Label has to be obtained.
If you purchase a label by calling the transaction endpoint without a rate (instalabel), this field will be a simplified Rate object in the Transaction model returned from the POST request.
Note, only rates less than 7 days old can be purchased to ensure up-to-date pricing.
One of:
ID of the Rate object for which a Label has to be obtained.
If you purchase a label by calling the transaction endpoint without a rate (instalabel), this field will be a simplified Rate object in the Transaction model returned from the POST request.
Note, only rates less than 7 days old can be purchased to ensure up-to-date pricing.
Indicates the status of the Transaction.
Enum"WAITING""QUEUED""SUCCESS""ERROR""REFUNDED""REFUNDPENDING""REFUNDREJECTED"
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.
Example: "9499907123456123456781"
Indicates the high level status of the shipment.
Enum"UNKNOWN""PRE_TRANSIT""TRANSIT""DELIVERED""RETURNED""FAILURE"
Response
application/json
{ "commercial_invoice_url": "string", "created_by": { "first_name": "Shwan", "last_name": "Ippotle", "username": "shippotle@shippo.com" }, "eta": "string", "label_file_type": "PDF_4x6", "label_url": "https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA", "messages": [ { … } ], "metadata": "string", "object_created": "2019-08-24T14:15:22Z", "object_id": "915d94940ea54c3a80cbfa328722f5a1", "object_owner": "shippotle@shippo.com", "object_state": "VALID", "object_updated": "2019-08-24T14:15:22Z", "parcel": "e94c7fdfdc7b495dbb390a28d929d90a", "qr_code_url": "https://shippo-delivery.s3.amazonaws.com/96_qr_code.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA", "rate": { "amount": "5.5", "amount_local": "5.5", "currency": "USD", "currency_local": "USD", "object_id": "adcfdddf8ec64b84ad22772bce3ea37a", "provider": "USPS", "carrier_account": "078870331023437cb917f5187429b093", "servicelevel_name": "Priority Mail", "servicelevel_token": "fedex_ground" }, "status": "SUCCESS", "test": true, "tracking_number": "9499907123456123456781", "tracking_status": "DELIVERED", "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781" }
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