Shippo API release notes

We will be documenting all backwards-incompatible and backwards-compatible changes associated with each new API version here. Learn more about how Shippo API versioning works and upgrade to the latest.

Note

To learn about updates to Shippo Elements view the Shippo Elements release notes.

Version 2018-02-08

Oct 8 2024

We have added an automated email to inform you when your Pro Plan Free Trials start and expire.

Sep 12 2024

Minor: On Sep 16 at 00:00:00 CDT we will enable CeC NSA account holders whose USPS rates are based on Merchant Rate Cards (MRC) to charge Commercial Plus Pricing (CPP) rates. They will receive Rural Partner Rate Cards (PRC) for a limited list of destination zip codes.

Sep 11 2024

Minor: We've enabled Fedex Home Delivery® service level for Shippo's Fedex account.

Sep 9 2024

Patch: We've fixed an issue where certain address street2 formats were not printed on labels.

Aug 29 2024

Patch: We've fixed an issue where some UPS tracking histories contained premature delivered events.

Aug 15 2024

Patch: We have fixed an issue where tracking invoice item descriptions were incorrectly displaying "International address validation fee"

Aug 13 2024

Minor: We've removed Parcel and Yodel from our list of supported carriers.

Aug 7 2024

Patch: We have resolved an issue where logged-in users without a saved payment method could become stuck during partner-initiated OAuth authorization requests.

Aug 5 2024

Minor: We've updated the Shippo API to support parcel tracking for a large number of carriers previously unsupported. See our guide for details.

Jul 30 2024

Patch: We've removed a step in label purchase which prompted users to add a new payment method if they had unpaid invoices.

Jul 15 2024

Minor: We've removed Maergo from our list of supported carriers.

Jun 25 2024

Minor: We've added support for the Sendle drop off service.

Jun 24 2024

Patch: Previously, when you purchased a shipping label through Shippo, the tracking status for that shipment would start with UNKNOWN. We've updated our tracking life cycle to start with PRE_TRANSIT. Review our definitions of tracking events for more details.

Jun 14 2024

Minor: The carrier AxleHire has changed its name to Jitsu. We have updated our guides to reflect this new name. To support our existing customers already using this carrier, we will continue to use the axlehire token.

Jun 10 2024

Minor: As part of our continuing work to improve our SDKs, we've release a new C# SDK for the Shippo API.

May 10 2024

Minor: We've updated our UPS integration to include more label reference fields for ZPL II labels. See our carrier reference fields guide for more details.

Apr 30 2024

Minor: We've further increased the number of parcels you can send in a multi-piece shipment for UPS up to 200 parcels. Read our multi-piece shipping guide for more details.

Apr 29 2024

Patch: We've made updates our address validation process to improve how we classify the response. Now, the returned validation_results provide clearer text descriptions, helping you identify and correct any issues with an address.

Apr 24 2024

Minor: We've increased the number of parcels you can send in a multi-piece shipment for UPS. Read our multi-piece shipping guide for more details.

Apr 24 2024

Minor: We've release a new Javascript SDK for the Shippo API.

Apr 9 2024

Minor: In the future UPS will require users to use OAuth to authorize Shippo to perform some actions, like requesting rates or buying labels, on your behalf. To support this, we have created a new endpoint carriers/{carrier_account_id}/signin/initiate that directs a user to an OAuth flow. Review our Carrier authorization using OAuth guide for more details.

Apr 8 2024

Minor: We've updated the Shippo API to support our new policy for automatically refunding unused USPS labels. From now on, we will no longer automatically refund unused USPS labels. You must create a request to receive a refund for unused labels. See our Refunding labels guide for more information.

Apr 1 2024

Minor: We are updating our API SDKs. As part of this work, we've released a Python SDK for the Shippo API.

Mar 1 2024

Minor: Our shipping insurance provider, XCover, have updated their terms. For shipments originating from the US, XCover now has a 25% deductible for Jewelry/Watches, Antiques/Artwork, and Glassware/Ceramics. See our guide for details.

Feb 28 2024

Minor: We’ve add support for the carrier Veho.

Dec 8 2023

Minor: We've added support for A5 PDF labels for Australia Post shipments.

Aug 31 2023

Minor: We have added XCover as our new insurance provider. To add XCover insurance to your packages, follow our Shipping insurance guide.

Aug 18 2023

Minor: We've updated our API to improve the accuracy of the time in transit information for all domestic USPS shipping rates.

Jul 31 2023

Minor: FedEx have retired their Collect on Delivery (COD) service for FedEx Express and FedEx Ground COD service for shipments within and to the US from Canada. Now, when you create a shipment in the Shippo API and include the option for COD, the rates returned will not include rates from FedEx.

Jul 9 2023

Minor: We've added a new service level token to enable USPS Ground Advantage. To use USPS Ground Advantage, use the token usps_ground_advantage. See the full list of service tokens in our reference guide for more information.

Jun 15 2023

Minor: Hazardous materials or hazmat are items that can cause harm to people. When shipping with USPS, you must declare if your parcel contains hazmat items. To support our users compliance shipping hazmat items with USPS, we've added the dangerous_goods field to our shipments. See our hazmat guide for more details.

Mar 10 2023

Minor: In the Shipment Extras object, we've added new fields to support FedEx labels. Shipment Extras now includes the fields customer_reference, po_number, invoice_number, dept_number, and rma_number.

Apr 25 2023

Minor: We've added Platform Accounts to our API. Using a Platform Account, you can create and control Managed Shippo Accounts. Managed Shippo Accounts are headless accounts that are typically used by Marketplaces, e-commerce platforms, and third-party logistics. Using a Platform Account, you can make requests to the Shippo API on behalf of your Managed Accounts. Use Shippo Platform Accounts to create a shipping experience that is seamless to your end customers.

Dec 14 2022

Minor: You can now use QR codes for UPS. Generated QR codes can be brought to a carrier location to print labels for outbound and return shipments.

Dec 9 2022

Minor: We’ve added support for insuring DHL eCommerce packages using our insurance provider, Shipsurance.

Dec 7 2022

Patch: Previously, for Australia Post, some ZPL formatted labels were formatted incorrectly. We’ve fixed this formatting issue.

Nov 23 2022

Patch: For Australia Post, some customers received this error message "The carrier API timed out. Please try again. If this error persists please contact support.". We have resolved this issue.

Nov 17 2022

Minor: We’ve added the option to include the IOSS number for DPD UK using the API carrier request call.

Nov 16 2022

Minor: For the carrier APG, we’ve added support for the service level “APG eParcel Expedited".

Patch: Previously, for some DPD packages, the status field would not be updated when the package was delivered. This has now been fixed.

Nov 10 2022

Minor: FedEx has changed the names of it’s service Smartpost to Ground Economy. To support this we have added the service level token fedex_ground_economy. Any request made using the old token, fedex_smart_post, will be given the Ground Economy service level.

Minor: We have removed support for GLS DE and GLS FR.

Nov 8 2022

Minor: For the carrier LaserShip, we’ve added support for users to define the critical_pull_time HH:MM format in carrier account parameters.

Nov 2 2022

Patch: We’ve fixed an issue where the Orders endpoint was failing to update for batch entry.

Oct 25 2022

Minor: We’ve add support for the carrier Better Trucks.

Minor: For Evri, we’ve updated our tracking URL for Evri from the old Hermes UK URL.

Patch: We’ve improved our error code reporting for Lasership.

Oct 19 2022

Minor: For APG, we’ve added support additional service of Destroy for undeliverable packages.

Sep 28 2022

Patch: We fixed an issue with the carrier APG that required a “state” in the address object.

Minor: For Evri, we’ve added Puerto Rico (PR) and Virgin Islands US (VI) as destination countries for parcelshop drop off service level

Patch: We’ve added a fix that removes special characters in post codes for DPD UK.

Minor: We’ve added Shippo carrier accounts for Post IT and Mondial. You can now use these carriers with the Shippo account.

Sep 27 2022

Minor: We’ve added support for the carrier DPD DE.

Sep 21 2022

Patch: For the carrier Evri we’ve fixed the issue causing the error message "Content Values do not add up to Parcel Value".

Sep 15 2022

Minor: We’ve added Shippo carrier accounts for Chronopost. You can now use these carriers using the Shippo account.

Sep 13 2022

Minor: We’ve add the carrier UDS to our list of supported carriers.

Sep 9 2022

Minor: We’ve added support for our Canadian users to access the Shippo UPS account. This means that Shippo customers in Canada can benefit from the great rates we’ve negotiated with UPS.

Sep 8 2022

Minor: We now support test mode for the carrier Swyft.

Sep 1 2022

Minor: Previously we supported Evri only for domestic shipments. Now, we support Evri deliveries to European and the rest of the world from the UK.

Minor: We now support test mode for the carrier UDS.

Jun 21 2022

Minor: The carrier Poste Italiane is now supported in the Shippo API.

Jun 20 2022

Minor: We’ve added the carriers APG and Correos to our list of supported carriers.

May 13 2022

Minor: The carrier Chronopost is now supported in the Shippo API.

May 10 2022

Minor: Shippo’s customs now support Merchant Tax ID/VAT for international shipments.

May 7th 2022

Minor: Shippo’s customs now support the EORI number for shipments to/from the EU & UK.

Mar 2nd 2022

Minor: The carrier Colissimo is now part of list of supported carriers.

Jan 14th 2022

Minor: We’ve added X Delivery to list of supported carriers

Dec 14th 2021

Minor: You can now use the carrier DPD UK in the Shippo API

July 28th 2021

Minor: We’ve added Royal Mail to our list of supported carriers.

Jul 15th 2022

Minor: Our Customs Declaration object now includes the field is_vat_collected. You can use this field to indicate whether the shipment’s destination VAT has been collected. This is required for some destinations.

Jun 16th 2022

Patch: We’ve fixed a bug to ensure only valid service levels are returned when getting shipping rates.

Dec 10th 2021

Minor: Previously, when calling our list parcels endpoint, you might have received a very long list of results. To help, we’ve added pagination to help control the results you see.

Aug 17 2021

Minor: We’ve added extended_token and parent_servicelevel fields to our Rates object. These fields give you clearer insight into specific service levels quoted in a Rate. Some service levels, like those for UPS, are grouped, and are represented by a generic token. For example, the token ups_expedited represents service levels including ups_expedited_ca and ups_expedited_eu. In this example, parent_servicelevel would return ups_expedited. Extended_token could return one of ups_expedited_ca and ups_expedited_eu.

May 10 2021

Minor: The carrier GLS US is now supported in our API.

Apr 9 2021

Minor: In customs declarations, you can now add a tax identification number and Employer Identification Number. These are required for some international shipment.

Sep 10 2020

Minor: To aid international shipments, we’ve added some new customs fields. In our customs declarations, we’ve added the fields to support B13A. We’ve also added fields in our customs items to support ECCN.

Aug 7 2020

Minor: We’ve added support for the carrier PCF to our API.

July 30 2020

Minor: We’ve added a field for qr codes to the Transaction object. If supported by the carrier, the qr_code_url will contain a link to a QR code image.

Apr 4 2020

Minor: We’ve added the carrier OrangeDS to our list of supported carriers.

Feb 24 2020

Minor: You can use the carrier LSO to ship packages using our API.

May 10 2019

Minor: The Shipment object now includes the field alternate_address_to that you can use to set an alternate delivery address.

Apr 24 2019

Minor: The Customs Declaration object now includes a duty_payor field. Using this field you can define who is paying for the duties of international shipments. This is required by some carriers.

Dec 19th 2018

Minor: We’ve added support for the carrier CDL to our API.

Oct 19 2018

Minor: We’ve added AxleHire to our list of supported carriers.

Sept 5 2018

Minor: We’ve added a new validation_status field ot our Orders endpoint. Now, when you retrieve an Order, you will get an validation_status parameter to show if the created Order object is pending, valid, or invalid.

Aug 28 2018

Minor: We’ve added an error field to our Orders endpoint. Now, when you retrieve an Order, you will get an “error” parameter that includes any error messages associated with your Order object.

Apr 13 2018

Minor: For security reasons, the account_id and parameters fields will be censored in the response objects for Carrier Accounts.

Mar 19 2018

Minor: We’ve added Globegistics to our list of supported carriers.

Feb 15 2018

Minor: We’ve added support for the carrier CouriersPlease to our API.

Jan 22 2018

Minor: You can use the carrier Sendle to ship packages using our API.

8 Feb 2018

Minor: PRE_TRANSIT will be added to the list of possible values in status.

Minor: PRE_TRANSIT will be added to the list of possible values in status and tracking_status for track_updated and transaction_updated events, respectively.

Version 2017-08-01

Webhooks

Shippo-API-Version will be included in the headers of all webhook responses to indicate the api version being used.

New events have been added to our webhooks:

  • transaction_updated  -- will be triggered when a transaction in your account is updated, and will provide the updated transaction.
  • transaction_created  -- will be triggered when a transaction in your account is created, and will provide the updated transaction.

A new fields have been added in the body of the webhook payload:

  • event_type  will have one of the following values:  transaction_created ,  transaction_updated ,  track_updated ,  batch_created , or  batch_updated .

Please see our Webhooks tutorials for examples of using these new fields and events.

All Endpoints

The count field has been removed. If making a GET request to any endpoint without an object_id specified in the URI (i.e. /transactions, /shipments, /addresses) you will no longer see the count field in the body of the response.

Rates

In rate objects, the days field has been renamed to estimated_days to make it clear that this is an estimate.

Transactions

The tracking_history field has been deprecated from the Transactions object. The Transactions object will still have the most recent tracking_status on it, but to get a full tracking history, you would need to subscribe awebhook to the tracking_update event or query the Tracks endpoint.

Version 2017-03-29

Major Update: Refactored and Deprecated Fields

In this API version, we've cleaned up many stale attributes across various endpoints in the API to make them more intuitive and true to operational use cases. Please explore the following to see if any changes will affect your implementation.

The changes to our Shipments endpoint for returns now makes it possible to create return labels without having to reference a previous transaction.

Changes have been made to the following endpoints: Addresses, Shipments, Rates, Transactions, Batches, and Refunds. For more detailed information, please see the full API references.

Addresses

Request:

  • Deprecated:
    • object_purpose

Response:

  • Deprecated:
    • ip
    • object_purpose
    • object_state
    • object_source
  • Added:
    • is_complete  --- boolean used to indicate if an address is fully entered, making it possible to use for purchasing a label.
    • validation_results  --- object that contains information regarding if an address had been validated or not. Also contains any messages generated during validation. Children keys are  is_valid (boolean) and  messages (array).
  • Updated:
    • messages  has been moved into new  validation_results  field.

Shipments

Request:

  • Deprecated:
    • object_purpose
  • Updated:
    • submission_date  is now  shipment_date
    • return_of  is now  is_return , also has been changed to a boolean and is no longer a top-level key and has been moved into extra field. This will flag a shipment to be created as a scan-based label.
    • object_status  is now  status
    • insurance_amount  is now  amount , moved into newly added insurance  field inside  extra object.
    • insurance_currency  is now  currency , moved into newly added  insurance  field inside  extra  object.
    • insurance_provider  is now  provider , moved into newly added  insurance  field.
    • insurance_content  is now  content , moved into newly added  insurance  field.
    • reference_1  &  reference_2  moved to  extra  field.
    • parcel  is now  parcels  and has been changed to an array.
  • Added:
    • insurance , an object within the  extra  object with previous top level and  extra  level insurance fields as keys of the  insurance  object.

Response:

  • Deprecated:
    • object_state
    • submission_type
    • object_purpose
    • rates_url
  • Updated:
    • rates_list  is now  rates
    • submission_date  is now  shipment_date
    • return_of  is now  is_return , also has been changed to a boolean and is no longer a top-level key and has been moved into the  extra  field. This will set the shipment as a return shipment, which makes the label scan-based. See our docs on  Returns  for more information.
    • object_status  is now  status
    • insurance_amount  is now  amount , moved into newly added insurance  field.
    • insurance_currency  is now  currency , moved into newly added  insurance  field.
    • insurance_content  is now  content , moved into newly added  insurance  field.
    • insurance_provider  is now  provider , moved into newly added  insurance  field.
    • reference_1  &  reference_2  moved to  extra  field.
    • address_to , address_from ,  address_return , and  parcel  are now expanded to include full address or parcel information, in addition to their  object_id .
    • parcel  is now  parcels  and has been changed to an array.
  • Added:
    • insurance , an object within the  extra  object with previous insurance fields as keys of the  insurance  object.

Rates

Request:

  • Deprecated:
    • GET on /rates/ will no longer return a list of rates. GET on /rates/{object_id} will still work as indicated.

Response:

  • Deprecated:
    • object_state
    • object_purpose
    • object_updated
    • trackable
    • delivery_attempts
    • rates_url
  • Updated:
    • servicelevel_name ,  servicelevel_token , and  servicelevel_terms  have been renamed to  name ,  token , and  terms (respectively) and moved into the newly created  servicelevel field.
  • Added:
    • servicelevel , object that contains renamed fields:  name ,  token , and  terms (previously  servicelevel_name ,  servicelevel_token , and  servicelevel_terms )

Transactions

Response:

  • Deprecated:
    • customs_note
    • submission_note
  • Updated:
    • object_state  is now  status
    • rate  field is expanded with full rate details for insta-label calls.

Manifest

Request:

  • Updated:
    • submission_date  is now  shipment_date

Response:

  • Updated:
    • submission_date  is now  shipment_date

Batches

Response:

  • Updated:
    • object_status  is now  status

Refunds

Response:

  • Updated:
    • object_status  is now  status

Parcel

Request:

  • Updated:
    • reference_1  and  reference_2  can be added in the  extra  field of Parcel for multi-parcel shipments. See  Multi-Piece Shipments  for more information.

Version 2016-10-25

Major Update: New Test Token used to set Shippo to test mode.

You will now be able use all Shippo API functionalities from end-to-end in test mode by authenticating requests with a Test Token. Previously, to test out Shippo, you had to set carrier accounts to test mode. Now all users will have have two different tokens: one for test mode and one for live mode.

See our detailed documentation on Test Mode.

For users continuing to use API version 2014-02-11

You will have the option of using the Test Token while remaining on the older version of the Shippo API.

  • Test Token can be used for test mode without affecting your existing implementation. See our  Test Mode documentation  to learn more about functionalities.
  • Functionalities of your existing Private Auth Token will remain the same -- now renamed as "Live Token".
  • All tokens will now begin with  "shippo_live_"  or  "shippo_test_" . This will not affect any existing implementation with old tokens, however we recommend using the new format going forward.

For users upgrading to API version 2016-10-25

Using the Test Token and Live Token will affect how your test and live data are returned and displayed.

Test and Live Data

  • When using the Test Token, you will only be able to create and request test data sets such as addresses, rates, and carriers etc. No live data can be requested or returned.
  • When using the Live Token, you will only be able to create and request live data. No test data can be requested or returned.
  • Shipment object will now return 3 variables for  test
    • True -- All Rates returned in Shipment were tests
    • False -- All Rates returned in Shipment were live
    • None -- Rates returned in Shipment were both tests and live

The following are some common scenarios.

  1. If you create a Shipment with Live Token using an Address object created with a Test Token, you will receive a 404 response (not found). Vice versa is also true. If you retrieve an object_id created in live mode with a Test Token, you will receive a 403 (bad request) response.
  2. If you request a list of Transaction objects, or Shipment objects with the Test Token, only test Transactions or Shipments will be returned. Vice versa is also true, when making requests in live mode.

Carrier account configuration

When you upgrade to the latest version, the test attribute of the carrier object will become read-only.

  • User-owned carrier accounts (where you have plugged in your own carrier credentials) that have been set to  test: true  at the time of upgrade will only appear and work when request with a Test Token.
  • User-owned carrier accounts (where you have plugged in your own carrier credentials) that have been set to  test: false  at the time of upgrade will only appear and work when request with a Live Token.
  • Shippo-owned carrier accounts  (see carrier capabilities for full list)  object_ids will appear and be functional when requested with a Test Token or a Live Token.

We recommend setting all carrier accounts to test: false (including on your dashboard) before upgrading so that existing carrier accounts are set to live mode. This will help with minimizing changes necessary for the upgrade.

"test" attribute

Certain objects will now be returning a new "test" attribute.

  • Transaction object will no longer return the "was_test" attribute, instead it will return "test".
  • Address, Parcel, Refund, Customs Declaration, and Customs Items objects will now return a new "test" attribute.
  • Possible values for "test":
    • True -- the object was created in test mode
    • False -- the object was created in live mode
  • Other objects (such as Carrier Accounts and Rates) will keep returning "test" if they did in past.