API versions

The Shippo API uses versioning to roll out backwards-incompatible changes over time.

About versioning

The API version will control the API and webhook behaviors, such as parameters accepted in requests, and response properties. Your account is automatically set to the latest version when you sign up for Shippo.

A new version of the API is released when backwards-incompatible changes are made to the API. To avoid breaking your code, we will never force you to upgrade until you're ready.

We will be releasing backwards-compatible changes without introducing new versions. Your code will be able to handle these changes no matter what version it's on.

Examples of backwards-compatible changes:

• Adding new API endpoints
• Adding new optional response attributes to an existing resource
• Adding new optional request attributes

Release notes and communication

Backwards-incompatible changes will be documented in the release as part of every version release. Documentation will provide in-depth explanations of the changes.

Upgrade your API version

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

To see your current version and upgrade to the latest, visit the Developer keys menu on the Shippo Developer portal.

Versioning of the Shippo API will be released as dates, displayed as: YYYY-MM-DD.

You can set the version in each API call using the header parameter Shippo-API-Version. If you do not set the Shippo-API-Version, the Shippo API will use your default API version.

Test before upgrading

To test your code under a different API version before committing the change, you can set the API version on a specific request by setting a header with the version you are testing. The version will be set for subsequent requests until it's changed back.

Users can only upgrade their API to the latest version. Once you've upgraded your API version, you cannot roll back to an earlier version. Please make sure to test thoroughly before doing so.

curl https://api.goshippo.com/shipments/\
    -H "Authorization: ShippoToken <API_Token>"\
    -H "Shippo-API-Version: YYYY-MM-DD"\
    -d '{ ... }'
# now this API request uses the API version "YYYY-MM-DD"

require 'shippo'
# Setup your API token
shippo.api_key = '<API_Token>' 
shippo.api_version = 'YYYY-MM-DD'
# now all subsequent requests use the API version "YYYY-MM-DD"

import shippo
shippo_sdk = shippo.Shippo(api_key_header="<API_Token>", shippo_api_version='YYYY-MM-DD')
# now all api requests will use the API version "YYYY-MM-DD"

require_once('lib/Shippo.php');
Shippo::setApiKey("<API_Token>");
Shippo::setApiVersion("YYYY-MM-DD");
# now all subsequent requests use the API version "YYYY-MM-DD"

const shippo = new Shippo({apiKeyHeader: '<API_TOKEN>', shippoApiVersion: 'YYYY-MM-DD'});
// now all subsequent requests use the API version "YYYY-MM-DD"

import com.shippo.Shippo;
Shippo.setApiKey(<API_Token>);
Shippo.setApiVersion("YYYY-MM-DD");
# now all subsequent requests use the API version "YYYY-MM-DD"

using Shippo;
ShippoSDK sdk = new ShippoSDK(
    apiKeyHeader: "<API_Token>",
    shippoApiVersion: "YYYY-MM-DD"
);
// now all subsequent requests use the API version "YYYY-MM-DD"