Versioning
The Chargebee API has two major versions: v1 and v2. This reference documents API v2 for the latest product catalog. For API v1, see the API v1 reference.
Sub-versions of v2
Breaking changes in the Product Catalog APIs resulted in two sub-versions of API v2: the latest product catalog and the legacy product catalog. Each has its own reference:
- Latest product catalog, for example the Items API.
- Legacy product catalog, for example the Plans API.
To find out which sub-version your site uses, check the product_catalog_version attribute of your site's configuration: v2 is the latest product catalog and v1 is the legacy product catalog.
See also
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/v2whereas 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
- Create customer API v2:
- 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 language selector at the top of the left navigation and read this section. In a narrow window, open the selector from the settings icon in the header.
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 language selector at the top of the left navigation and read this section. In a narrow window, open the selector from the settings icon in the header.
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.