Skip to main content

Version upgrades

We always recommend working with the latest version of the API to take advantage of new features, improvements and fixes. Using the latest version of the API is also faster as it avoids the processing of requests and responses by the versioning engine.

What is affected by an upgrade​

Upgrading your API version will affect:

  • API calls made without the Accept-Version header. The structure of objects in the requests and responses may change.
  • The structure of objects sent to webhook endpoints.
info

Calls made using the SDKs have the Accept-Version header built in. This includes the back-end SDKs as well as the JavaScript SDK.

If you are not using one of the SDKs to communicate with the API, we recommend that you add the Accept-Version header to your requests instead of relying on your default account setting. This approach will be less likely to cause problems in the future.

Upgrade process​

To see the version you are running and upgrade to the latest, visit the API Versions page.

Upgrading your API clients​

Follow these steps to safely upgrade your API integration:

  1. Check the changelog to understand which objects are changing
  2. Update the SDKs in a development environment and align your code with the new structures
  3. If you are not using the SDKs, update the Accept-Version header in your code
  4. Test your code with the new object structures using a test environment
  5. Create a rollback plan in case issues arise

Upgrading your webhooks​

Follow these steps to safely upgrade your webhook endpoints:

  1. Check the changelog to understand which objects are changing
  2. Update the webhook code to handle both the old and new versions of the object
  3. Change the version of the test webhook endpoint to the version you want to test
  4. Trigger the event in a test site and validate that your code works with the new object structures
  5. Document the changes for your team

Applying the upgrade​

Once you're confident that everything is working as expected, you can upgrade your pinned version from the API Versions page. This will update:

  • The version of any API requests made without the Accept-Version header
  • The version used in your webhook endpoints

Safety net: Rolling back​

Don't worry about making a mistake. You have the opportunity to roll back your API version for 120 hours (5 days) after you've upgraded your API version.

If you encounter issues after upgrading, you can:

  1. Go to the API Versions page
  2. Select your previous version
  3. Apply the rollback
  4. Fix any integration issues
  5. Try upgrading again when ready