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
Shipment represents the parcel as retrieved from the database
A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
Example: "Customer ID 123456"
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.
Example: "2021-03-22T12:00:00Z"
Address object of the sender / seller. Will be returned expanded by default.
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.
Address object of the recipient / buyer. Will be returned expanded by default.
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.
Unique identifier of the given Shipment object.
Example: "adcfdddf8ec64b84ad22772bce3ea37a"
Username of the user who created the Shipment object.
Example: "pp@gmail.com"
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.
Waiting shipments have been successfully submitted but not yet been processed. Queued shipments are currently being processed. Success shipments have been processed successfully, meaning that rate generation has concluded. Error does not occur currently and is reserved for future use.
Enum"ERROR""QUEUED""SUCCESS""WAITING"
Example: "QUEUED"
{ "extra": { "accounts_receivable_customer_account": { … }, "alcohol": { … }, "ancillary_endorsement": "FORWARDING_SERVICE_REQUESTED", "appropriation_number": { … }, "authority_to_leave": true, "bill_of_lading_number": { … }, "billing": { … }, "bypass_address_validation": true, "carbon_neutral": true, "carrier_hub_id": "string", "carrier_hub_travel_time": 0, "COD": { … }, "cod_number": { … }, "container_type": "string", "critical_pull_time": "string", "customer_branch": "string", "customer_reference": { … }, "dangerous_goods": { … }, "dangerous_goods_code": "01", "dealer_order_number": { … }, "delivery_instructions": "string", "dept_number": { … }, "dry_ice": { … }, "fda_product_code": { … }, "fulfillment_center": "string", "insurance": { … }, "invoice_number": { … }, "is_return": true, "lasership_attrs": [ … ], "lasership_declared_value": "string", "manifest_number": { … }, "model_number": { … }, "part_number": { … }, "po_number": { … }, "preferred_delivery_timeframe": "10001200", "premium": true, "production_code": { … }, "purchase_request_number": { … }, "qr_code_requested": true, "reference_1": "string", "reference_2": "string", "request_retail_rates": true, "return_service_type": "PRINT_AND_MAIL", "rma_number": { … }, "saturday_delivery": true, "salesperson_number": { … }, "serial_number": { … }, "signature_confirmation": "STANDARD", "store_number": { … }, "transaction_reference_number": { … }, "usmca_eligible": true }, "metadata": "Customer ID 123456", "shipment_date": "2021-03-22T12:00:00Z", "address_from": { "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 }, "address_return": { "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 }, "address_to": { "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 }, "carrier_accounts": [ "string" ], "customs_declaration": { "aes_itn": "string", "b13a_filing_option": "FILED_ELECTRONICALLY", "b13a_number": "string", "certificate": "string", "certify": true, "certify_signer": "Shawn Ippotle", "commercial_invoice": true, "contents_explanation": "T-Shirt purchase", "disclaimer": "string", "duties_payor": { … }, "exporter_identification": { … }, "exporter_reference": "string", "importer_reference": "string", "is_vat_collected": true, "invoice": "#123123", "license": "string", "metadata": "Order ID #123123", "notes": "string", "address_importer": "257ba08436604d2aaf069caafe7acb2a", "contents_type": "MERCHANDISE", "eel_pfc": "NOEEI_30_37_a", "incoterm": "DDP", "invoiced_charges": { … }, "items": [ … ], "non_delivery_option": "RETURN", "object_created": "2014-07-17T01:01:08.306Z", "object_id": "e2197a54da9d470480f4f8796cc419cb", "object_owner": "shippotle@shippo.com", "object_state": "VALID", "object_updated": "2014-07-17T01:01:08.306Z", "test": true }, "messages": [ { … } ], "object_created": "2019-08-24T14:15:22Z", "object_id": "adcfdddf8ec64b84ad22772bce3ea37a", "object_owner": "pp@gmail.com", "object_updated": "2019-08-24T14:15:22Z", "parcels": [ { … } ], "rates": [ { … } ], "status": "QUEUED", "test": true }
An object holding optional extra services to be requested.
UPS only. Adds custom accounts receivable customer account reference to UPS labels.
Specify an ancillary service endorsement to provide the USPS with instructions on how to handle undeliverable-as-addressed pieces (DHL eCommerce only).
Enum"FORWARDING_SERVICE_REQUESTED""RETURN_SERVICE_REQUESTED"
UPS only. Adds custom appropriation number reference to UPS labels.
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).
UPS only. Adds custom bill of lading number reference to UPS labels.
Travel time in hours from fulfillment center to carrier injection site.
Carrier arrival time to pickup packages from the fulfillment center. UTC format: %Y-%m-%dT%H:%M:%SZ
Specify the reference field on the label (FedEx and UPS only).
Container for specifying the presence of dangerous materials. This is specific to USPS, and if any contents are provided, only certain USPS service levels will be eligible. For more information, see our guide on hazardous or dangerous materials shipping.
Dangerous Goods Code (DHL eCommerce only). See Category Codes
Enum"01""02""03""04""05""06""07""08""09"
UPS only. Adds custom dealer order number reference to UPS labels.
Specify delivery instructions. Up to 500 characters. (FedEx and OnTrac only).
Specify the department number field on the label (FedEx and UPS only).
UPS only. Adds custom FDA product code reference to UPS labels.
To add 3rd party insurance powered by XCover, specify
amount, content, and currency.
Alternatively, you can choose carrier provided insurance by additionally specifying provider (UPS, FedEx and OnTrac only).
If you do not want to add insurance to your shipment, do not set these parameters.
Specify the invoice number field on the label (FedEx and UPS only).
This field specifies if it is a scan-based return shipment. See the Create a return shipment section for more details.
Specify Lasership Attributes (Lasership only). Multiple options accepted.
Items Enum"TwoPersonDelivery""Explosive""Alcohol""Hazmat""ControlledSubstance""Refrigerated""DryIce""Perishable""NoRTS"
UPS only. Adds custom manifest number reference to UPS labels.
Required for DHL Germany Paket Sameday. Designates a desired timeframe for delivery. Format is HHMMHHMM
Enum"10001200""12001400""14001600""16001800""18002000""19002100"
UPS only. Adds custom product code reference to UPS labels.
UPS only. Adds custom purchase request number reference to UPS labels.
Request a QR code for a given transaction when creating a shipping label (USPS domestic and Evri UK only).
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) |
Optional text to be printed on the shipping label if supported by carrier. Up to 50 characters. For DHL eCommerce, this field can be used for billing reference.
Carrier-Specific Constraints:
| Carrier | Constraints |
|---|---|
| FedEx | Max 30 characters |
Returns retail rates instead of account-based rates (UPS and FedEx only).
return_service_typeShipmentExtraReturnServiceTypeUPSEnum (string) or ShipmentExtraReturnServiceTypeLasershipEnum (string)
Request additional return option for return shipments (UPS and Lasership only).
One of:
Request additional return option for return shipments (UPS and Lasership only).
string(ShipmentExtraReturnServiceTypeUPSEnum)
Enum"PRINT_AND_MAIL""ATTEMPT_1""ATTEMPT_3""ELECTRONIC_LABEL"
UPS only. Adds custom salesperson number reference to UPS labels.
Request standard or adult signature confirmation. You can alternatively request Certified Mail (USPS only) or Indirect signature (FedEx only) or Carrier Confirmation (Deutsche Post only).
Enum"STANDARD""ADULT""CERTIFIED""INDIRECT""CARRIER_CONFIRMATION"
UPS only. Adds custom transaction reference number to UPS labels.
UPS only. Request USMCA (United States-Mexico-Canada Agreement) preferential tariff treatment. When enabled, it includes the USMCA eligibility declaration in customs documentation.
Supported routes and value limits:
- USA/Canada → Mexico: ≤ $1,000 USD
- Canada/Mexico → USA: ≤ $2,500 USD
- USA/Mexico → Canada: ≤ $3,300 CAD
Only for declaration-only shipments, full USMCA - FormType 04 (Certificate of Origin) is not supported.
{ "accounts_receivable_customer_account": { "prefix": "ABC", "value": "value", "ref_sort": 1 }, "alcohol": { "contains_alcohol": true, "recipient_type": "licensee" }, "ancillary_endorsement": "FORWARDING_SERVICE_REQUESTED", "appropriation_number": { "prefix": "ABC", "value": "value", "ref_sort": 1 }, "authority_to_leave": true, "bill_of_lading_number": { "prefix": "ABC", "value": "value", "ref_sort": 1 }, "billing": { "account": "string", "country": "string", "participation_code": "string", "type": "SENDER", "zip": "string" }, "bypass_address_validation": true, "carbon_neutral": true, "carrier_hub_id": "string", "carrier_hub_travel_time": 0, "COD": { "amount": "5.5", "currency": "USD", "payment_method": "CASH" }, "cod_number": { "prefix": "ABC", "value": "value", "ref_sort": 1 }, "container_type": "string", "critical_pull_time": "string", "customer_branch": "string", "customer_reference": { "prefix": "string", "value": "string", "ref_sort": 1 }, "dangerous_goods": { "contains": true, "biological_material": { … }, "lithium_batteries": { … } }, "dangerous_goods_code": "01", "dealer_order_number": { "prefix": "ABC", "value": "value", "ref_sort": 1 }, "delivery_instructions": "string", "dept_number": { "prefix": "string", "value": "string", "ref_sort": 3 }, "dry_ice": { "contains_dry_ice": true, "weight": "string" }, "fda_product_code": { "prefix": "ABC", "value": "value", "ref_sort": 1 }, "fulfillment_center": "string", "insurance": { "amount": "5.5", "content": "string", "currency": "USD", "provider": "FEDEX" }, "invoice_number": { "prefix": "string", "value": "string", "ref_sort": 2 }, "is_return": true, "lasership_attrs": [ "TwoPersonDelivery" ], "lasership_declared_value": "string", "manifest_number": { "prefix": "ABC", "value": "value", "ref_sort": 1 }, "model_number": { "prefix": "ABC", "value": "value", "ref_sort": 1 }, "part_number": { "prefix": "ABC", "value": "value", "ref_sort": 1 }, "po_number": { "prefix": "string", "value": "string", "ref_sort": 2 }, "preferred_delivery_timeframe": "10001200", "premium": true, "production_code": { "prefix": "ABC", "value": "value", "ref_sort": 1 }, "purchase_request_number": { "prefix": "ABC", "value": "value", "ref_sort": 1 }, "qr_code_requested": true, "reference_1": "string", "reference_2": "string", "request_retail_rates": true, "return_service_type": "PRINT_AND_MAIL", "rma_number": { "prefix": "string", "value": "string", "ref_sort": 1 }, "saturday_delivery": true, "salesperson_number": { "prefix": "ABC", "value": "value", "ref_sort": 1 }, "serial_number": { "prefix": "ABC", "value": "value", "ref_sort": 1 }, "signature_confirmation": "STANDARD", "store_number": { "prefix": "ABC", "value": "value", "ref_sort": 1 }, "transaction_reference_number": { "prefix": "ABC", "value": "value", "ref_sort": 1 }, "usmca_eligible": true }
Request
Returns a list of all shipment objects.
In order to filter results, you must use the below path parameters. A maximum date range of 90 days is permitted. Provided dates should be ISO 8601 UTC dates (timezone offsets are currently not supported).
Optional path parameters:
object_created_gt- object(s) created greater than a provided date time
object_created_gte - object(s) created greater than or equal to a provided date time
object_created_lt - object(s) created less than a provided date time
object_created_lte - object(s) created less than or equal to a provided date time
Date format examples:
2017-01-01
2017-01-01T03:30:30 or 2017-01-01T03:30:30.5
2017-01-01T03:30:30Z
Example URL:
https://api.goshippo.com/shipments/?object_created_gte=2017-01-01T00:00:30&object_created_lt=2017-04-01T00:00:30
Security
APIKeyHeader
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/shipments
- cURL
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl https://api.goshippo.com/shipments/ \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"Response
application/json
{ "next": "baseurl?page=3&results=10", "previous": "baseurl?page=1&results=10", "results": [ { … } ] }
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