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

See also

Upgrading to Product Catalog 2.0.

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.
Client library: The API version used is configured in the source code of each of our client libraries. If you would like to learn more, select a language in the "Library" dropdown above and read this section.

Client library: The API version is configured in the source code of each of our client libraries. If you would like to learn more, select a language in the "Library" dropdown above and read this section.

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.