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 the Shippo API Portal
2. In the left menu, under "API Configuration", click “Developer keys”
3. Find the “API Version” section, your current API version is listed next to “Current 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.

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

Upgrade

Before you upgrade

1. Identify your current API version.
2. In your own code identify the Shippo endpoints you currently use.
3. Review our changelog 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:

curl https://api.goshippo.com/shipments/\
	-H "Authorization: ShippoToken <API_Token>"\
    		-H "Shippo-API-Version: 2018-02-08"\
    		-d '{ ... }'

4. Test the API call to confirm it is functioning as expected.
5. Complete steps 1 - 3 for each API call.
6. 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.
7. After your final test, upgrade your API version linked with your Shippo account.

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

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

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.

Client library upgrade by selecting API version

If your client library does support the option to set the API version, follow these steps.

1. 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.
2. Manually add or change the Shippo API version in your script. For example, in Python, use this command.
   Copy

   Copied

   shippo.config.api_version = "2018-02-08"

3. Test your integration to confirm it is functioning as expected.
4. After you’ve tested your integration and you are confident it is functioning as expected, change your API token back to your live token and re-verify that it is functioning as expected.
5. After your final test, upgrade your API version linked with your Shippo account. Follow the steps 7,8, and 9 .

Client library upgrade using Shippo account API version

If your client library does not support the option for selecting the Shippo API version, the API version you use is set in your Shippo account. To upgrade, follow these steps.

1. 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.
2. Upgrade, following steps 7,8, and 9 .
3. Test your integration to confirm it is functioning as expected.
4. After you’ve tested your integration 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.