Chargebee provides HTTP based API which follows the essence of REST*. The HTTP protocol's rules are followed thereby enabling simple HTTP client tools like "curl" to be used.
The following client libraries provide a "easy to use" wrapper around the raw HTTP based API.
Please do mail us at support@chargebee.com if you need any other language bindings.
The top language bar allows you to see samples in your preferred language.
Want us to generate ready-to-test snippets?
Login to Chargebee and open the API docs from there and you'll find ready-to-test sample codes based on your Chargebee test site's api key and data.Checkout our collection of sample applications with tutorials on integrating with Chargebee.
Refer to our documentation for a detailed definition & description of all the components in Chargebee.
Chargebee now supports two API versions - V1 and V2. V2 version has been released to accommodate certain backwards-incompatible changes that we wanted to make over V1 for a more streamlined functionality.
All further developments will happen in V2. However we will continue to support V1 in order to avoid breaking your code.
As we support multiple API versions now, we request you to
With multiple versions of API being supported, the property Api Version has been added to Webhooks, which decides the structure of the event content sent to the webhooks.
Find out the version of the API you are using, with the following indicators:
As all of our future development will happen in API V2, the latest version of Chargebee API, you might want to upgrade to V2 to benefit from the new functionality.
The changes made in V2 that are not V1-compatible, are listed in this section. You may want to change your existing code appropriately as part of the upgradation process.
In API V1, refunds were directly linked to Invoices. In V2, refunds are not directly linked to Invoices; instead they are linked to Credit Notes, which in turn are linked to their respective invoices.
The Estimate resource has been revamped in V2: in V1 it had both subscription and invoice related attributes without any segregation at the top level. Whereas in V2, all the subscription related attributes are grouped under subscription_estimate sub-resource and all the invoice related attributes are grouped under invoice_estimate sub-resource. Additionally, the following changes have been made:
For the 'country' input parameters - card[billing_country], billing_address[country], shipping_address[country], address[country] - in the operations like 'Create Subscription' etc, the 2-letter ISO 3166 alpha-2 code is expected. But in V1, for few sites, we were allowing values in other formats too (like full country names). In V2, only the 2-letter ISO 3166 codes are allowed. For other formats, error will be thrown.
In API V1 the sub_total attribute is the sum of all the line items and discounts. Whereas in V2, this is sum of line items and item-level discount amounts alone. So in V2, document-level discounts are not part of the sub_total.
With V2, when an invoice is voided/deleted, and 'Prorated credits' have been applied to the invoice, they will be reclaimed and added back to the subscription.
This section provides the complete listing of the attributes and operations that have been renamed/removed in API V2 for a more streamlined functionality:
Account Credits are now called Promotional Credits. We have renamed the related attributes and operations to reflect the same:
Estimate resource is completely revamped in V2. More details here.
The following event types are renamed in API V2:
As part of the upgradation process, you need to move your webhooks too, from V1 to V2.
Note: If you have configured webhooks for third party apps/plug-ins such as Zapier, WordPress, Salesforce, etc., you might want to check with the app/plug-in developer before transitioning to V2.
To transition webhooks to API version V2:
If you require assistance for transitioning your webhooks to API version V2, reach out to support@chargebee.com.
You can use cURL to test Chargebee API from a CLI. When you pass input parameters to the API using -d
or --data-urlencode
options, the HTTP POST
method is used:
curl https://{site}.chargebee.com/api/v1/subscriptions/{subscription_id}/change_term_end -u {site_api_key}:\ -d term_ends_at=1601490600
GET
method by default:
curl https://{site}.chargebee.com/api/v1/subscriptions/{subscription_id} \ -u {site_api_key}:
POST
request without providing any input parameters, use the -X POST
option:
curl -X POST https://{site}.chargebee.com/api/v1/exports/subscriptions \ -u {site_api_key}:
GET
requests with parameters, you must use the -G
option:
curl -X POST https://{site}.chargebee.com/api/v1/v2/orders \ -G \ -u {site_api_key}:\ --data-urlencode limit=3 \ --data-urlencode status[is]="queued"
Chargebee uses HTTP BASIC Auth for authenticating the API calls. The user name is your "API key" and the password is empty. The API key could be got from 'Your API Keys' page under integration tab in the web client console.
Note: The API keys are different for your test site and your live site.
For curl you could specify the API key using the -u option
curl {api url} -u {api key}:
Since the password is not present, nothing is specified after the colon(:)
API keys are unique strings used for both authenticating and identifying an application communicating with Chargebee. This section describes the best practices that developers can follow to secure Chargebee API keys.
GET
requests do not generate any events, you can check API key usage for POST
requests by fetching all events with source
set to api
. Among the events returned, filter the API key name found in the event.user
attribute.
<service name>-<key creation timestamp>
(for example: core_app-09-12-2020
).
Chargebee follows the REST model of exposing resources as urls. For example, subscriptions are exposed as
The HTTP method (like GET,POST) determines the operation type on the resource. Query parameters allow you to provide additional options to the GET requests. POST parameters provide the data to write operations like creation, modification of resource(s).
By default curl uses GET method. Use -X option to specify a specific HTTP method to use. For passing parameters, use -d option. ( Note: cURL automatically uses to POST method if any parameter is sent via -d option ).
The response is in JSON format. Currently Chargebee does not support any other response format.
# creates a subscription with customer information and billing details. curl https://{site}.chargebee.com/api/v1/subscriptions \ -u {site_api_key}:\ -d plan_id="no_trial" \ -d customer[first_name]="John" \ -d customer[last_name]="Doe" \ -d customer[email]="john@user.com" \ -d billing_address[first_name]="John" \ -d billing_address[last_name]="Doe" \ -d billing_address[line1]="PO Box 9999" \ -d billing_address[city]="Walnut" \ -d billing_address[state]="California" \ -d billing_address[zip]="91789" \ -d billing_address[country]="US" \ -d customer[auto_collection]="off"
# creates a subscription with customer information and billing details. curl https://{site}.chargebee.com/api/v1/subscriptions \ -u {site_api_key}:\ -d plan_id="no_trial" \ -d customer[first_name]="John" \ -d customer[last_name]="Doe" \ -d customer[email]="john@user.com" \ -d billing_address[first_name]="John" \ -d billing_address[last_name]="Doe" \ -d billing_address[line1]="PO Box 9999" \ -d billing_address[city]="Walnut" \ -d billing_address[state]="California" \ -d billing_address[zip]="91789" \ -d billing_address[country]="US" \ -d customer[auto_collection]="off"
Some of the resources have a corresponding details page in the Chargebee's admin console. In some cases you might want to construct the admin console url for easy access from your app (or from exported xls sheets). As the admin console urls are based on internal ids you need to construct the url in the below given format.
Here is an example of a constructed url for a subscription with id 123xyz
Chargebee supports billing in 100+ currencies.
Take a look at the list of supported currencies here.
When multi-decimal pricing is enabled in Chargebee, you can provide decimal values for prices and quantities. However, to maintain backward compatibility in the API, decimal prices and quantities are provided and returned via separate parameters and attributes respectively. For prices, use the price_in_decimal
or amount_in_decimal
parameters/attributes instead of price
or amount
in the API. Similarly, for quantities, use quantity_in_decimal
instead of quantity
and use tiers[starting_unit_in_decimal]
instead of tiers[starting_unit]
and so on.
The amount is expressed in the major unit of the currency. The major unit of the currency is the unit of the currency as represented by its ISO 4217 code. For example, $1.6782 should be provided as 1.6782
.
The maximum number of decimal places supported can be configured in the admin console. For zero-decimal currencies--currencies that do not have minor units, such as the Japanese Yen (JPY)--decimal places are not allowed.
Multiple decimal places only apply for pricing in Chargebee. At the invoice line item-level, the amount
is rounded off to two decimal places in the major unit of the currency. The rounding logic used is ROUND_HALF_EVEN
. For example, if the quantity
is 0.0765 and unit_amount
is $10.674, the line item amount
of (0.0765 x $10.674) = $0.816561 is rounded off to $0.82.
When multi-decimal pricing is not enabled for your site, the units used for currency amounts depends on the type of currency:
150
.
15
.
With our Multicurrency support, you will be able to process transactions in additional currencies apart from your site's Base currency.
Once Multicurrency support is enabled, the API methods listed below will throw an error as currency_code
is required for these methods to work and the same is not supported in the V1 version.
So upgrade to our latest version (V2) to be able to pass currency_code
input parameter to these methods in Multicurrency mode.
Chargebee supports configuring multiple gateway accounts for a gateway type (eg: you can configure multiple Authorize.net accounts to process multiple currencies).
If you have multiple gateway accounts for a gateway type, the API methods listed below will throw an error as gateway_account_id is required for these methods to work and the same is not supported in the V1 version. So upgrade to our latest version (V2) to be able to pass gateway_account_id input parameter to these methods.
The list of API methods affected if multiple accounts of a gateway type are configured:Chargebee supports multiple payment methods/sources for a customer. So a customer can have a Card and a Paypal Account linked to them, or they can have multiple cards. Moreover, you can mark one of them as Primary and one as Backup payment source.
The purpose of a Backup payment source is that if a charge made via the Primary payment source fails, then the backup payment source will be automatically used for processing the transaction.
Updating a payment source:
An optional parameter, payment_source_id, is available in the following APIs:
If you want to attach a particular payment source to a specific subscription, then pass the parameter in the following APIs:
Pass this parameter in the following APIs to collect the payment using a specific payment source:
Notes:
Chargebee restricts API requests when you exceed the limits entitled for your plan. The limiting mechanism is employed considering two criteria:
When the upper limit is breached on either of the above criteria, an HTTP 429
error response is returned for subsequent requests. As a result, no more requests are served until the limit resets (in approximately a minute).
If you need a temporary increase in API rate limit, you can contact Support to avail it. Further, if you breach the limit frequently, we suggest you move to a higher plan (see table below) to accommodate the volume of requests.
Listed below are the API rate limits for each Chargebee plan:
PLAN | REQUESTS PER MINUTE LIMIT | CONCURRENT REQUESTS LIMIT | ||
Live site | Test site | Live site | Test site | |
Launch | 150 | 150 | Up to 150 simultaneous requests, of which GET requests should not exceed 50 and POST requests should not exceed 100. | Up to 100 simultaneous requests, of which the GET and POST requests must not exceed 50 each. |
Grow | 200 | |||
Scale | 300 | |||
Enterprise | 500 |
HTTP status codes are used to indicate success or failure of an API call. The body of the response contains the details of the error in JSON format.
Given below is a sample error that is returned for the Create a subscription API call when the plan_id
is invalid. The returned HTTP status code is 404
.
{
"message":"Plan is not present",
"type":"invalid_request"
"api_error_code":"resource_not_found",
"param":"plan_id"
}
The standard http status codes used are
2XX
The response code in this range implies the API call has succeeded.3XX
This range is not used currently.4XX
response codes indicate failure due to wrong input (i.e, client) side. As the usable list of http codes in the 4xx range is limited we predominantly use the 400
( BAD REQUEST ) error code for client-side errors. 5XX
response codes indicate API request was valid but failed due to issues on the Chargebee server.payment
, invalid_request
and operation_failed
. The client libraries throw a corresponding exception for easy error handling.
plan_id
is invalid, then param
is set to plan_id
. For "multivalued" parameters, the index is part of the parameter name. For example, in the same API call, if the id
for the second addon is wrongly passed, then param
is set to addons[id][1]
.
customer_id
is a URL path parameter. If that value is invalid, then an error of type
= resource_not_found
is thrown without the param
attribute.
Note: There may be additional deprecated attributes (like error_code
) which are present to support older versions of the libraries.
API calls fail at the first error encountered by Chargebee while validating them. To enhance user experience, we recommend that you validate an API call thoroughly to avoid multiple failed attempts from your users, each time for a different error.
There are cases where you have to depend on Chargebee's validation for handling errors like coupon code validation or VAT validations. In such cases, check the specific param
and api_error_code
combination to show a proper error message to your users.
If you receive an HTTP 429 Too Many Requests
error response to an API call, it means that the API requests for your Chargebee site have exceeded acceptable limits. Chargebee may also send a Retry-After
header indicating the time duration to wait before sending a new request. Follow these best practices:
Retry-After
header, wait for the number of seconds indicated before retrying. See Also: API Rate Limits.
The following are the list of codes grouped based on type.
Note: 'New' codes might get added (though additions are very rare). If you are handling for specific codes also ensure that there is a default block for handling unknown(/new) error codes.
These errors may occur when trying to store the payment method details(such as card, paypal, ACH etc) or when trying to collect a payment. These errors should be handled and appropriate message should be shown to the user.
The type attribute in the error response is sent as payment.
The following errors are caused due to invalid request. In most cases the errors should occur only during the development phase. The type attribute in the error response is sent as invalid_request.
These errors are returned when the request was valid but the requested operation could not be completed. These errors should occur very rarely. You generally need not handle them specifically other than showing a generic error message to your users. The type attribute in the error response is sent as operation_failed.
Most of these errors occur due to improper API environment setup in your server or changes to the site's configuration. The type attribute is not sent in the error response.
Sometimes you would want to disable emails or webhooks for the events that are generated for a particular api call. Typically you would need this when you are migrating customers from your system to Chargebee via api. One option would be to disable all the emails(/webhooks) for all events during the import process. But then you would still want to send emails for new customers who are signing up.
Chargebee supports custom http headers on each api request that allow you to control the actions that are triggered on the events generated by that particular api call.
curl https://mysite.chargebee.com/api/v1/customers \ -H chargebee-event-actions:all-disabled \ -u myapikey: \ -d customer[email]="john@user.com" \
Passing user details like IP address, email address and Device information from your website to Chargebee is always useful. IP address information is routed to the payment gateway (where it will be validated against active fraud detection filters), used for EU tax validation, referral integration and event reports. Email addresses and Device information, even more ubiquitous, are used for identification. Chargebee supports http headers to send user details.
Use the following headers to send user details across:
curl https://mysite.chargebee.com/api/v1/customers \ -H chargebee-request-origin-ip:192.168.1.2\ -H chargebee-request-origin-user:user@example.com\ -H chargebee-request-origin-device:Android\ -u myapikey: \ -d customer[email]="john@user.com" \
Chargebee gives you the option of creating custom fields to track additional information about Customers and their Subscriptions. You can create custom fields for customers, subscriptions, plans, and addons. Once the custom fields are created, they can be added to the hosted checkout pages and invoices. They can be accessed through the web interface, and via the API. More on Custom Fields here.
curl https://{site}.chargebee.com/api/v1/subscriptions \ -u {site_api_key}: \ -d plan_id="basic" \ -d "cf_notes"="sample" \ -d "customer[cf_gender]"="sample"
If you would want to store additional/custom data at a resource's level, you can make use of Meta Data.
For example, if you're a data service provider and would want to store certain features of a particular plan such as "Usage Limit", "Speed within limit", etc., you can have it stored in the Meta data of the Plan.
Meta Data can be passed during the Add/Update operations, for the following resources:
Meta Data can only be stored in the JSON format. You can also use nested JSON objects.
Considering the same example as above, if you'd want to store the additional features of a particular data plan here's how the JSON would look:
{
"features":{
"usage-limit":"5GB",
"speed-within-quota":"2MBbps",
"post-usage-quota":"512kbps"
}
}
Tutorials and use case guides for developers can be found here.