Versioning

The Chargebee API has two major versions: v1 and v2. Use the toggle at the top of the page to switch between these versions.

Sub-versions of v2

Some breaking changes have been introduced in version 2 of our API, which has resulted in the creation of a newer sub-version. When viewing the documentation for v2, you can select the specific sub-version using the Product Catalog selector at the top of the page. The term "Product Catalog" is used because the changes introduced are primarily related to the Product Catalog APIs, such as Plans API.

To determine which sub-version applies to your site, log in to Chargebee and return to this site. You will then be prompted to switch to the appropriate documentation version for your site.

Checking the API version

There are three ways to know the API version you're using:

• Endpoint paths: The version of the API can be seen in the API endpoint path: For v2 the path begins with /api/v2 whereas for v1, it begins with /api/v1. For example:
  • Create customer API v2: https://{subdomain}.chargebee.com/api/v2/customers
  • Create customer API v1: https://{subdomain}.chargebee.com/api/v1/customers
• Webhooks: In webhook payloads, the API version can be found in the value of the attribute api_version. The schema of the payload is determined by the API version.
• Ruby client library: The API version used is configured in the source code of the library. You can find it assigned to the constant API_VERSION in the file /lib/chargebee/environment.rb. Moreover, if you know the version of the Ruby library, you can find the compatible API versions listed in the readme.

Backward compatible changes

Chargebee considers the following changes as backward compatible:

• Adding new API resources.
• Adding new attributes to existing API resources.
• Changing the order of attributes in existing API responses.
• Adding new endpoints.
• Adding new optional input parameters to existing endpoints.
• Adding new event types.