API Overview

import chargebee
import json
chargebee.configure("{site_api_key}","{site}")
result = chargebee.Subscription.create_with_items("__test__8asz8Ru9WhHOJO",{
    "subscription_items" : [
        {
            "item_price_id" : "day-pass-USD",
            "unit_price" : 100
        },
        {
            "item_price_id" : "basic-USD",
            "billing_cycles" : 2,
            "quantity" : 1
        }]
    })
subscription = result.subscription
customer = result.customer
card = result.card
invoice = result.invoice
unbilled_charges = result.unbilled_charges

import chargebee
import json
chargebee.configure("{site_api_key}","{site}")
result = chargebee.Subscription.create_with_items("__test__8asz8Ru9WhHOJO",{
    "subscription_items" : [
        {
            "item_price_id" : "day-pass-USD",
            "unit_price" : 100
        },
        {
            "item_price_id" : "basic-USD",
            "billing_cycles" : 2,
            "quantity" : 1
        }]
    })
subscription = result.subscription
customer = result.customer
card = result.card
invoice = result.invoice
unbilled_charges = result.unbilled_charges

Sample Result [ JSON ]

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

• Accessing the constructed url in a browser will redirect it to the details page.
• The login page will be shown if the user has not yet logged-in into Chargebee's admin console.
• Not all resources will have the corresponding details page. To know if it is supported, please look at the cURL documentation under the retrieve operation for that resource.
• Do not store the redirected internal id based url as it may change.

Chargebee supports billing in 100+ currencies.

Take a look at the list of supported currencies here.

Currency and Quantity Units

Multi-decimal Pricing

When multi-decimal pricing is enabled in Chargebee, you can provide decimal values for prices and quantities. For prices, the amount is expressed in the major unit of the currency, which 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, which are currencies that do not have minor units (such as the Japanese Yen or JPY), decimal places are not allowed.

Backward compatibility

• For prices, price_in_decimal has been introduced for price and amount_in_decimal has been introduced for amount in the API.
• Similarly, for quantities, quantity_in_decimal for quantity and tiers[starting_unit_in_decimal] for tiers[starting_unit] have been introduced.

Rounding

Non-Multi-decimal Pricing

When multi-decimal pricing is not enabled for your site, or when you provide input via price parameters that do not have the in_decimal suffix, the unit used for currency depends on the type of currency:

• For currencies that are not zero-decimal, Chargebee supports amounts with up to two decimal places in the major unit of the currency. The major unit of a currency is that represented by its ISO 4217 code. This amount with 2 decimal places must be converted to an integer by multiplying it with 100. For example, $1.53 should be provided as 1.53 X 100 which is 150.
• For zero-decimal currencies (currencies that do not have minor units) -- since there is no decimal place allowed -- the amount must be provided in the major unit of the currency. For example, to specify an amount of JPY 15, set the amount as 15.

Multicurrency Support

With Multi-currency support, you will be able to process transactions in additional currencies apart from your site's Base currency.

Before enabling Multicurrency support, ensure that the currency_code input parameter is passed to the following methods, to avoid the cannot be blank error:

• Customer related methods
• Add Promotional credits to a customer
• Deduct Promotional credits from a customer
• Set Promotional credits for a customer
• Record an excess payment for a customer
• Invoice related method
• Create an invoice
• Product Catalog related methods
• Create an item price
• Create a coupon

What are business entities?

A Chargebee site can be divided into multiple business entities, each with its own configuration and data. By default, a site has only one business entity. Here are some use cases for which you can create multiple:

• You may be running your business under different regional units with different "invoice-from" addresses. This is usually done to manage taxation and bookkeeping. In such a case, you may create a business entity for each business unit.
• You may have multiple brands within your business, such as those acquired via mergers and acquisitions. You may create a business entity for each brand.

Creating multiple business entities lets you separate configuration and data for your business units or brands so that you can manage their billing and revenue operations independently.

Specifying the business entity

All API operations in Chargebee have site context. Context restrictions cannot be assigned to API keys. However, if your site has multiple business entities, you can specify the business entity context for an API call by passing a custom HTTP request header.

Terminology

This section defines some useful terms for describing how business entities work.

Linked business entity

Any resource is always associated with precisely one and only one business entity. We call it the linked business entity of the resource, or simply, the business entity of the resource.

Default business entity

When customer resource is created and no business entity is specified, it is linked to the business entity designated as the default business entity of the site. A site always has a default business entity. At first, it is the same as the first business entity of the site and can be changed once more business entities are created. Contact Support to change the default business entity.

Context of an operation

Any site has data in it. This includes all the various resources such as customers, subscriptions, invoices, comments, and so on. The "context" of an API operation is the subset of site data it has access to. An API operation can only read or write data within its context. By default, an API operation has "site context", which means it has access to the entire site's data. However, when a business entity is specified in an API operation, it has "business entity context", which means that the operation only has access to the data linked to the business entity.

Target resource

While creating an API resource other than a customer, you specify a target resource under which it should be created. For example:

• While creating an invoice resource for a one-time charge, you must specify either the customer or the subscription resource to which it belongs. The customer or subscription resource, in this case, is the target resource of the invoice.
• While creating a subscription, the target resource of a subscription resource is always a customer resource.
• While creating a quote resource of type change_subscription, the target resource is a subscription resource.

Chargebee supports configuring multiple gateway accounts for a gateway type. For example, you can configure multiple Authorize.net accounts to process different currencies.

The default Gateway account to use for each currency can be configured using Smart Routing. However, you can override the selected gateway for each transaction in Chargebee. To do this pass the gateway_account_id parameter when calling the following APIs:

• Create a customer
• Update payment method for a customer

• Create a subscription
• Update a subscription
• Import a subscription

• Update card for a customer
• Switch gateway

• Checkout new subscription
• Checkout existing subscription
• Update payment method

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:

1. To update the Primary payment source for a customer:
• Use any of the create payment source APIs with 'replace_primary_payment_source' set to 'true'. This will update the payment source and make it the Primary payment source for the customer.
2. To update alternate payment sources:
• Delete the payment source that you want to update
• Create a payment source for the customer using any of the create payment source APIs

An optional parameter, payment_source_id, is available in the following APIs:

• Subscription APIs

If you want to attach a particular payment source to a specific subscription, then pass the parameter in the following APIs:

• Create subscription for items
• Import subscription for items
• Override Billing Profile
• Invoice APIs

Pass this parameter in the following APIs to collect the payment using a specific payment source:

• Create an invoice
• Create invoice for charge
• Create invoice for addon
• Collect payment for an invoice

Chargebee restricts API requests when you exceed the limits entitled for your plan. The limiting mechanism is employed considering two criteria:

• Requests per minute - Number of requests in the past 60 seconds.
• Concurrent requests - Number of requests at an instance of time.

• Test sites: ~750 API calls per every 5 minutes
• Live sites: ~150 API calls per site per minute

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). For more details about error 429, refer to api_request_limit_exceeded in Error Codes List.

Please note that a cooling period is set for both test and live sites:

• For test sites: five minutes from the time error 429 is thrown
• For live sites: one minute from the time error 429 is thrown

If you need a temporary rate limit increase, contact Chargebee Support to have it increased. Furthermore, if you exceed your limit frequently, you should consider upgrading to a higher plan (see table below) in order to accomodate the increase of your API request volume.

Listed below are the API rate limits for each Chargebee plan:

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. The client library wraps the JSON response in an instance of APIError and throws the exception.

Note: Please use latest client library ( greater than 1.3.5 version) to make use of the upgraded error response. It enables simpler error handling. See the change notes for more details.

Sample error response:

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.

Http Status Codes

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.

Error Attributes

Note: There may be additional deprecated attributes (like error_code) which are present to support older versions of the libraries.

Exception Classes

The client library throws specific exceptions based on the "type" attribute. You could have common error handling routines based on the exception type. For more specific error handling use the "api_error_code" attribute in the exception.

Error handling recommendations

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.

Handling API Throttling

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:

• If you see the Retry-After header, wait for the number of seconds indicated before retrying.
• Use an exponential backoff algorithm when making further requests.
• To prevent all your request threads/processes from retrying simultaneously (thundering herd problem), add some randomized jitter to the backoff algorithm to spread the requests out.

See Also: API Rate Limits.

Below is a sample pseudo code for handling errors in 'create subscription' api call. Let's assume that you are getting the card details along with coupon code from the user.

    
try:
    # chargebee.Subscription.create code
    # ...
    pass
except chargebee.PaymentError,ex:
    # First check for card parameters entered by the user.
    # We recommend you to validate the input at the client side itself to catch simple mistakes.
    if "card[number]" == ex.param:
      # Ask your user to recheck the card number. A better way is to use 
      # Stripe's https://github.com/stripe/jquery.payment for validating it in the client side itself.   
      pass

    #elif <other card params> == ex.param:
      # Similarly check for other card parameters entered by the user.
      # ....

    else:
      # Verfication or processing failures.
      # Provide a standard message to your user to recheck his card details or provide a different card.
      # Like  'Sorry,there was a problem when processing your card, please check the details and try again'.
      pass
except chargebee.InvalidRequestError,ex:
    # For coupons you could decide to provide specific messages by using 
    # the 'api_error_code' attribute in the ex.
    if "coupon" == ex.param:
      if "resource_not_found" == ex.api_error_code:
        # Inform user to recheck his coupon code.
        pass
      elif "resource_limit_exhausted" == ex.api_error_code:
        # Inform user that the coupon code has expired.
        pass
      elif  "invalid_request" == ex.api_error_code:
        # Inform user that the coupon code is not applicable for his plan(/addons).
        pass
      else:
        # Inform user to recheck his coupon code.
        pass
    else:
      # Since you would have validated all other parameters on your side itself, 
      # this could probably be a bug in your code. Provide a generic message to your users.
      pass    
except chargebee.OperationFailedError,ex:
    # Indicates that the request parameters were right but the request couldn't be completed.
    # The reasons might be "api_request_limit_exceeded" or could be due to an issue in ChargeBee side.
    # These should occur very rarely and mostly be of temporary nature. 
    # You could ask your user to retry after some time.
    pass    
except chargebee.APIError,ex:
   # Handle the other ChargeBee API errors. Mostly would be setup related 
   # Errors such as authentication failure.
   # You could ask users contact your support.
   pass    
except (httplib.HTTPException, socket.error) as ex:
   # Handle IO exceptions such as connection timeout, request timeout etc.
   # You could give a generic message to the customer retry after some time.
   pass
except Exception, ex: 
   # These are unhandled exceptions (Could be due to a bug in your code or very rarely in client library).
   # You could ask users contact your support.
   pass

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. These errors are thrown as PaymentError.

The following errors are caused due to invalid request. In most cases the errors should occur only during the development phase. These errors are thrown as InvalidRequestError.

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. These errors are thrown as OperationFailedError.

Most of these errors occur due to improper API environment setup in your server or changes to the site's configuration. These errors are thrown as APIError.

Specifying business entity

If your site has multiple business entities, you can pass the chargebee-business-entity-id: <business-entity-id> custom HTTP header to specify the business entity for which Chargebee should perform the operation. Here <business-entity-id> is the unique identifier of a business entity.

The following sample shows how to create a customer within a business entity:

        import chargebee
import json
chargebee.configure("{api-key}", "{site}")
result = chargebee.Customer.create({
    "email" : "sarah@acme.com"
    },None,{
    "chargebee-business-entity-id" : "__dev__8at09TEfAyAk2"
    })
customer = result.customer
card = result.card
    

Alternative to passing the header

As an alternative to passing the request header, for some create operations, you can specify the business_entity_id using a query string parameter. See the create customer endpoint for example.

Providing user details

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:

• For the IP address of the customer where the request originated - chargebee-request-origin-ip; where an example is 192.168.1.2.
• For details of the customer - chargebee-request-origin-user; where an example is user@example.com.
• For the device from which the customer has made the request - chargebee-request-origin-device; where an example is Android.

 result = chargebee.Subscription.create_for_customer(cust_id, {"plan_id" : "basic",}, None,
     {"chargebee-request-origin-ip" : "192.168.1.2",
      "chargebee-request-origin-user" => "user@example.com",
      "chargebee-request-origin-device" => "Android"
     })

Disabling webhooks and emails

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.

• To skip all actions to be done on the events pass the header chargebee-event-actions with value all-disabled
• To skip only emails pass the header chargebee-event-email with value all-disabled
• Similarly to skip only webhooks pass chargebee-event-webhook with value all-disabled

        result = chargebee.Subscription.create_for_customer(cust_id, {"plan_id" : "basic",}, None,
     {"chargebee-event-email" : "all-disabled"})
    

Chargebee sends webhook events from specific IP addresses. If you receive webhooks, you may need to configure your integration to ensure that you only receive such notifications from the IP addresses listed below.

Notifications for Updates
Any changes to our IP addresses are notified via the API Changelog. Alternatively, if you use a Google account, you can turn on notifications for the Google Sheets version of these lists.

United States (US) Region

Webhooks for Chargebee sites hosted in the US region originate from the following IP addresses:

View the above list in Google Sheets

European Union (EU) Region

Webhooks for Chargebee sites hosted in the EU region originate from the following IP addresses:

View the above list in Google Sheets

Australia (AU) Region

Webhooks for Chargebee sites hosted in the AU region originate from the following IP addresses:

View the above list in Google Sheets

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, item families, and items. 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 API. More on Custom Fields here.

Sample Request

result = chargebee.Customer.create({
    first_name : "john",
    last_name : "Doe",
    email : "john@test.com",
    "cf_gender" : "sample",
})
customer = result.customer.__str__()
print json.loads(customer)["cf_gender"]

Some resources in Chargebee support an attribute called metadata or meta_data that can be used to store additional information for the resource. The data can be stored in JSON format. The following resources support this:

• Subscriptions
• Customers
• Items
• Item prices
• Coupons

Metadata can be passed in both the "create" as well as "update" operations against the resource.

Limitations of metadata

• Metadata information is not surfaced on any customer-facing artifacts such as hosted pages or invoices.
• When using the "list" APIs, you cannot filter resources based on information stored within metadata.
• Metadata is not returned by the Export APIs.

Tutorials and use case guides for developers can be found here.