API versions

This guide will help you understand Recharge's philosophy on versioning and the difference between the different versions. At this time, Recharge has no plans to deprecate any of our API versions.

View the full API reference for more information.

How versioning works

🚧

Note:

Your account is associated a default API Version. When you do not specify a version in the header the default version will be used.

Recharge is constantly working to improve our model to give developers the flexibility to implement solutions to answer increasingly complex business needs. Sometimes this will mean we need to introduce backward-incompatible changes. In those occasions we will need to introduce a new version of the API.

• Versions of the Recharge API are date-based in the YYYY-MM format, where a later date represents a newer API version.

• 2021-01 is the base version of the Recharge API. This version is a snapshot of the existing resources and endpoints that might already be familiar to you.

• Stores can access a specific version of the Recharge API by including the following header on API requests, with the value of their desired version: x-recharge-version. At this time, if you don’t include this header attribute, Recharge will default the API request to the 2021-01 version.

• A merchant may access one or many different versions of the API on a request-by-request basis. For example, a single caller may access version 2021-11 of the charges endpoint for a new integration while continuing to rely on 2021-01 charges for an existing integration.

Accessing Versions

You can access the different versions of the Recharge API by adding the x-recharge-version header and specifying a value. You will pass the same API token.

Example of GET for Subscriptions with version header:

curl https://api.rechargeapps.com/subscriptions -H 'X-Recharge-Version: 2021-01' -H 'X-Recharge-Access-Token: your_api_token'

curl https://api.rechargeapps.com/subscriptions -H 'X-Recharge-Version: 2021-11' -H 'X-Recharge-Access-Token: your_api_token'

FAQ

Do I have to upgrade to a new version?

At this time, you do not have to upgrade to new versions of the Recharge API. As Recharge will only introduce new features and make improvements to the latest version of the API, it is highly recommended that:

• Any new integrations you are building should use the latest version.
• Be opportunistic about upgrading to the latest version as part of any refactor work you might be doing in the near future.
• Subscribe to the Recharge changelog so that you can stay up to date with the latest improvements in the Recharge API.

Is 2021-11 compatible with Shopify Checkout?

Some endpoints are compatible, with the exception of a few endpoints and properties. See Recharge API and the Shopify Checkout Integration for details.