API Overview

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.

• PHP
• Ruby
• Python
• Java
• .Net
• Node
• Go
• Typescript

Please do mail us at support@chargebee.com if you need any other language bindings.

Sample Snippets

The top language bar allows you to see samples in your preferred language.

Sample Apps

Checkout our collection of sample applications with tutorials on integrating with Chargebee.

Documentation

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.

Downloading/Installing Client libraries:

As we support multiple API versions now, we request you to

• Use the appropriate GitHub branches if you are building from source. The master branch will have the API V2 code, and chargebee-v1 branch will have the API V1 code.
• Use appropriate version specifiers, if you are installing/updating using package managers (composer, gem, pip, easy_install, maven, NuGet, npm, etc.).

Webhooks and API Versions:

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.

Which API version am I using?

Find out the version of the API you are using, with the following indicators:

• The Chargebee client lib release version: Release versions 1.x.x indicate that you're on V1 and 2.x.x indicate that you are on V2.
• The API end-points: They start with /api/v1 for V1 and /api/v2 for V2.

What changes does Chargebee consider to be "backwards-compatible"?

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.

What's changed in API V2 ?

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.

Refunds-related changes to Invoice and Transaction resources:

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 attribute linked_transactions[] , which listed both the payments and refunds applied to this invoice, is removed in V2. It is replaced by linked_payments[] attribute, which lists only the payments applied to this invoice.
• The linked_invoices[] attribute in V1, is no longer applicable for the transaction type 'refund' in V2. Instead, linked_credit_notes[] attribute is provided, which lists the Credit Notes to which this refund is attached.
• The operation List transactions for an invoice is removed in V2. It is replaced by the list operation List payments for an invoice, which lists only the payment transactions linked to the invoice.

Changes to Estimate Resource:

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:

• The attribute collect_now has been removed. The invoice_estimate returned by the 'Create Subscription' and 'Change Subscription' Estimates, will represent the estimate of the invoice that will get generated immediately.
• If no invoice gets generated during Estimate invocations ('Create Subscription Estimate', etc.), the invoice_estimate sub-resource will not be returned.
• The invoice_estimate returned by Estimate operations (such as 'Change Subscription Estimate') will include the existing customer balances - Promotional Credits, Refundable Credits, and Excess Payments - by default. This is not the default behavior in API V1.

Country input parameters - strict validation done:

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.

Invoice subtotal:

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.

Void and Delete Invoice operations:

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.

Attributes and operations that have been renamed/removed:

This section provides the complete listing of the attributes and operations that have been renamed/removed in API V2 for a more streamlined functionality:

Customer Resource:

Account Credits are now called Promotional Credits. We have renamed the related attributes and operations to reflect the same:

• Attribute account_credits is renamed to promotional_credits.
• Operation Add account credits is renamed to 'Add Promotional credits'.
• Operation Deduct account credits is renamed to 'Deduct Promotional credits'.
• Operation Set account credits is renamed to 'Set promotional credits'.

Invoice Resource:

• Operation Collect (which is used for closing a pending invoice) is renamed to 'Close'
• The following Invoice attributes are renamed:
  • end_date is renamed to date.
  • amount is renamed to total.
  • paid_on is renamed to paid_at.
  • next_retry is renamed to next_retry_at.
  • line_items[].tax is renamed to line_items[].tax_amount.
  • discounts[].type is renamed to discounts[].entity_type.
• The attribute start_date is removed.
• The attribute line_items[].type is removed (line_items[].entity_type captures all the required details in API V2).
• The attribute linked_transactions[] is removed. More details here

Transaction Resource:

• The attribute linked_invoices[].invoice_amount is renamed to linked_invoices[].invoice_total.
• The attribute linked_invoices[] is not applicable for 'refund' type in V2. More details here.
• The operation List transactions for an invoice is removed. More details here.
• The operation Record payment for an invoice is moved under Invoice resource in V2.

Estimate Resource:

Estimate resource is completely revamped in V2. More details here.

Event Resource:

The following event types are renamed in API V2:

• subscription_trial_ending is renamed to subscription_trial_end_reminder.
• subscription_cancelling is renamed to subscription_cancellation_reminder.
• invoice_created is renamed to pending_invoice_created.
• card_expiring is renamed to card_expiry_reminder.

Transitioning Webhooks from V1 to V2

As part of the upgradation process, you need to move your webhooks too, from V1 to V2.

To transition webhooks to API version V2:

1. Designate a different URL endpoint (different from that of your V1 based webhook URL) for processing the API V2 based events.
2. Follow these step during your deployment process:
   1. Just before starting the deployment, create a webhook for the new URL. Specify its API Version as 'V2'.
   2. Immediately remove the V1 based webhook.
   3. Deploy the API V2 client library in your webhook server(s). During this deployment time, few webhook notifications (till your webhook servers are completely up) may fail. However, Chargebee will do automatic retries, so the missed events will get processed once your webhook servers are up.

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

curl https://{site}.chargebee.com/api/v1/subscriptions/{subscription_id} \
    -u {site_api_key}:

curl -X POST https://{site}.chargebee.com/api/v1/exports/subscriptions \     -u {site_api_key}:

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.

Authentication in cURL

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.

• Storing keys: Do not store API keys in files that get checked into your application code repository. This is especially important if your repository is public. Review your code for any API keys before publishing.
• Delete keys that are no longer needed; this prevents misuse. Although 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.
• Limit the scope of keys by using different keys for different apps. This helps in the following ways:
  • Any given key acts as an identifier for the service that uses it.
  • When a key is compromised, you only have to change it for the affected app.
• Use an informative naming scheme for your keys: When choosing a name for the API key, use a consistent format such as <service name>-<key creation timestamp> (for example: core_app-09-12-2020).
• Use keys of the appropriate type: Avoid using full access keys when publishable or read-only keys are sufficient.
• Rotate API keys periodically: It is recommended that you change your API keys periodically just like passwords. This should be done especially when you notice any anomalies in API usage. Create a new key and replace all occurrences of the old key with the new one. Thereafter, delete the old key. We recommend changing keys at least once in 3 months.

• API keys can be viewed and created by users with admin access to Chargebee.
• When sharing keys with non-admins, do so using a medium that is secure, has appropriate access restrictions, and is destroyed after key sharing. Suggested options are: a secure cloud-based document sharing service or a password manager that allows sharing over a network.
• Do not share keys via emails or other plaintext communication.
• Keep a tab on the number of people who have admin access to Chargebee. Revoke said access for users who no longer need it, so that newer keys aren't available to them unnecessarily.
• When sharing keys with a third party for integrations, ask about their API request volumes so that your overall API rate quotas are not breached.

Chargebee follows the REST model of exposing resources as urls. For example, subscriptions are exposed as

Request

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

Response

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"

        curl  https://mysite.chargebee.com/api/v1/customers \
     -H chargebee-event-actions:all-disabled \
     -u myapikey: \
     -d customer[email]="john@user.com" \
    

 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" \

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"