Shippo API upgrade guide

What does the API version mean?

The Shippo API has multiple versions. A new version is created any time we make “breaking changes” to our API. These are changes to our API that could cause your integration to not work correctly anymore.

We use versions to significantly improve and develop new features in our API, without affecting our existing users' experience. Versions allow you to continue to use older versions of the API until you’re ready to update your system to the latest version.

Why should I upgrade?

We recommend staying up-to-date with the latest API version to take advantage of the latest improvements and features added to the Shippo API.

Which Shippo API version do I use today?

There are two ways to set the Shippo API version.

The first way to set the version of the Shippo API you use, is linked to your account and was set when you first created your Shippo account.

To see your current API version linked with your account, follow these steps.

  1. Log in to your Shippo Account
  2. In the left menu, click “Settings”
  3. Click “API”
  4. Find the “Versioning” section, your current API version is listed next to “Your current API Version:”


The second way that the Shippo API version is selected is within the code you use to integrate with the Shippo API. The API version specified in your code takes precedence over the version you have set in your Shippo account. If you do not specify a version in your code, the version set in your Shippo account is used.

If you’ve integrated with the Shippo API through one of our client libraries, refer to the library examples to check if your client library supports selecting your Shippo API version. For example, the Python library supports selecting your API version through the variable shippo.config.api_version.

If you’ve integrated with the Shippo API using cURL, your API version may be set using the a header. For example -H "Shippo-API-Version: YYYY-MM-DD”.


Before you upgrade

  1. Identify your current API version.
  2. In your own code identify the Shippo endpoints you currently use.
  3. Review our change log to see the changes to the endpoints that you use.
  4. For your current API version, review the appropriate upgrade guides to quickly identify which object fields have changed.
    • If you are upgrading from v20140211, use this guide .
    • If you are upgrading from v20161025, use this guide .
    • If you are upgrading from v20170329, use this guide .
    • If you are upgrading from v20170801, use this guide .

Upgrading a cURL integration

To upgrade safely, follow these steps. We recommend that you upgrade each API call one at a time.

  1. Identify an API call to the Shippo API.
  2. Change your authorization token to a test token . Using the test token means that you will not get charged and your live data will not be affected.
  3. Manually add or change the Shippo API version in your API calls using the header Shippo-API-Version , setting your API version to the latest 2018-02-08`.

For example:

	-H "Authorization: ShippoToken <API_Token>"\
    		-H "Shippo-API-Version: 2018-02-08"\
    		-d '{ ... }'
  1. Test the API call to confirm it is functioning as expected.
  2. Complete steps 1 - 3 for each API call.
  3. After you’ve tested each Shippo API call that your integration uses and you are confident it is functioning as expected, change your API token back to your live token and re-verify that they are functioning as expected. We recommend you keep the Shippo-API-Version in your API call as it is the preferred way to set your version.
  4. After your final test, upgrade your API version linked with your Shippo account.

Warning: You cannot reverse an upgrade.

  1. Follow the steps in Which Shippo API version I’m I using today? and click “Updates available”.


  1. Review the warnings and when ready, check the confirmation checkbox, and click “Upgrade”. The process will take a couple of minutes to complete. Reminder: Do not do this until you have completely validated that the latest version works for your integration.


Upgrading a client library integration

Traditionally, we have provided client libraries to help users integrate with the Shippo API. Soon, we will support our users in creating their own client libraries using our OpenAPI specification.