API Changelog

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

To get updates on new features that are backwards compatible on any versions, sign up for our developers mailing list.

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 scenerios.

  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 recieve 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 master 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.