Use this API to integrate with the Shippo service
/
Retrieve a carrier accoun...
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
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.
parametersAccount parameters (object) or FedEx account parameters (object) or UPS account parameters (object)required
One of:
An array of additional parameters for the account, such as e.g. password or token. Please check our carrier accounts guide for the parameters per carrier. To protect account information, this field will be masked in any API response. In the case of masked fields, they should be handled carefully.
Fields also must consider:
- Not providing a fields in parameters will not result in a change to any configured value
- Providing a value in a masked field with ****** (exactly 6 asterisks) will not change the configured value
- Providing field with null will clear the configured value
- Providing field with any other value will change the configured value and may affect the behavior of the account.
- https://api.goshippo.com/carrier_accounts
- cURL
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl --location --request POST 'https://api.goshippo.com/carrier_accounts/' \
--header 'Authorization: ShippoToken {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"account_id": "string",
"active": true,
"carrier": "ups",
"metadata": "UPS Account",
"parameters": {
"billing_address_city": "San Francisco",
"billing_address_country_iso2": "US",
"billing_address_state": "CA",
"billing_address_street1": "731 Market St",
"billing_address_street2": "STE 200",
"billing_address_zip": "94103",
"company": "Shippo",
"email": "hippo@shippo.com",
"full_name": "Thorn Hall",
"phone": "1112223333",
"pickup_address_city": "San Francisco",
"pickup_address_country_iso2": "US",
"pickup_address_same_as_billing_address": false,
"pickup_address_state": "CA",
"pickup_address_street1": "731 Market St",
"pickup_address_street2": "STE 200",
"pickup_address_zip": "94103",
"ups_agreements": true
},
"test": false
}'Bodyapplication/json
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.
Example: "****"
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.
Carrier token, see Carriers
Please check the carrier accounts tutorial page for all supported carriers.
Example: "usps"
parametersAccount parameters (object) or FedEx account parameters (object) or UPS account parameters (object)
One of:
An array of additional parameters for the account, such as e.g. password or token. Please check our carrier accounts guide for the parameters per carrier. To protect account information, this field will be masked in any API response. In the case of masked fields, they should be handled carefully.
Fields also must consider:
- Not providing a fields in parameters will not result in a change to any configured value
- Providing a value in a masked field with ****** (exactly 6 asterisks) will not change the configured value
- Providing field with null will clear the configured value
- Providing field with any other value will change the configured value and may affect the behavior of the account.
Unique identifier of the carrier account object.
Example: "6aa34d5f6865448fbb1ee93636e98999"
Username of the user who created the carrier account object.
Example: "bob+22@gmail.com"
Response
application/json
{ "account_id": "****", "active": true, "carrier": "usps", "parameters": {}, "carrier_name": "USPS", "is_shippo_account": false, "metadata": "string", "object_id": "6aa34d5f6865448fbb1ee93636e98999", "object_owner": "bob+22@gmail.com", "service_levels": [ { … } ], "test": false }
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/carrier_accounts/{CarrierAccountId}
- cURL
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl https://api.goshippo.com/carrier_accounts/b741b99f95e841639b54272834bc478c \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"Bodyapplication/json
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.
Example: "****"
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.
Carrier token, see Carriers
Please check the carrier accounts tutorial page for all supported carriers.
Example: "usps"
parametersAccount parameters (object) or FedEx account parameters (object) or UPS account parameters (object)
One of:
An array of additional parameters for the account, such as e.g. password or token. Please check our carrier accounts guide for the parameters per carrier. To protect account information, this field will be masked in any API response. In the case of masked fields, they should be handled carefully.
Fields also must consider:
- Not providing a fields in parameters will not result in a change to any configured value
- Providing a value in a masked field with ****** (exactly 6 asterisks) will not change the configured value
- Providing field with null will clear the configured value
- Providing field with any other value will change the configured value and may affect the behavior of the account.
Unique identifier of the carrier account object.
Example: "6aa34d5f6865448fbb1ee93636e98999"
Username of the user who created the carrier account object.
Example: "bob+22@gmail.com"
Response
application/json
{ "account_id": "****", "active": true, "carrier": "usps", "parameters": {}, "carrier_name": "USPS", "is_shippo_account": false, "metadata": "string", "object_id": "6aa34d5f6865448fbb1ee93636e98999", "object_owner": "bob+22@gmail.com", "service_levels": [ { … } ], "test": false }
Request
Updates an existing carrier account object. The account_id and carrier can't be updated. This is because they form the unique identifier together.
Security
APIKeyHeader
Headers
Bodyapplication/jsonOptional string used to pick a non-default API version to use. See our API version guide.
Example: 2018-02-08
Examples.
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.
Example: "****"
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.
Carrier token, see Carriers
Please check the carrier accounts tutorial page for all supported carriers.
Example: "usps"
parametersAccount parameters (object) or FedEx account parameters (object) or UPS account parameters (object)
One of:
An array of additional parameters for the account, such as e.g. password or token. Please check our carrier accounts guide for the parameters per carrier. To protect account information, this field will be masked in any API response. In the case of masked fields, they should be handled carefully.
Fields also must consider:
- Not providing a fields in parameters will not result in a change to any configured value
- Providing a value in a masked field with ****** (exactly 6 asterisks) will not change the configured value
- Providing field with null will clear the configured value
- Providing field with any other value will change the configured value and may affect the behavior of the account.
- https://api.goshippo.com/carrier_accounts/{CarrierAccountId}
- cURL
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl https://api.goshippo.com/carrier_accounts/b741b99f95e841639b54272834bc478c/ \
-X PUT \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396" \
-d parameters='{
"meter": "123987"
}'Bodyapplication/json
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.
Example: "****"
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.
Carrier token, see Carriers
Please check the carrier accounts tutorial page for all supported carriers.
Example: "usps"
parametersAccount parameters (object) or FedEx account parameters (object) or UPS account parameters (object)
One of:
An array of additional parameters for the account, such as e.g. password or token. Please check our carrier accounts guide for the parameters per carrier. To protect account information, this field will be masked in any API response. In the case of masked fields, they should be handled carefully.
Fields also must consider:
- Not providing a fields in parameters will not result in a change to any configured value
- Providing a value in a masked field with ****** (exactly 6 asterisks) will not change the configured value
- Providing field with null will clear the configured value
- Providing field with any other value will change the configured value and may affect the behavior of the account.
Unique identifier of the carrier account object.
Example: "6aa34d5f6865448fbb1ee93636e98999"
Username of the user who created the carrier account object.
Example: "bob+22@gmail.com"
Response
application/json
{ "account_id": "****", "active": true, "carrier": "usps", "parameters": {}, "carrier_name": "USPS", "is_shippo_account": false, "metadata": "string", "object_id": "6aa34d5f6865448fbb1ee93636e98999", "object_owner": "bob+22@gmail.com", "service_levels": [ { … } ], "test": false }
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