Product Catalog
    Library

API Overview

Chargebee provides an HTTP-based API that follows the essence of REST. The HTTP rules followed allow simple HTTP clients like cURL to be used as well. The history of changes made to the API is tracked in the API Changelog.

The following client libraries provide a wrapper around the raw HTTP-based API:

Let us know at support@chargebee.com if you need any other language bindings.

SAMPLE SNIPPETS

The language bar on top allows you to change the code samples in this documentation to your preferred language. The samples provided are ready-to-test as they are generated using your test site's API key and data.

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.

API Versions

This documentation is for version 2 of the Chargebee API. The Product Catalog module of Chargebee API allows you to model your products, services, coupons, and discounts in Chargebee. Under APIv2, the module has undergone a major revision and so it has two versions: Product Catalog 1.0 and 2.0. This documentation is for the latter version. When browsing the documentation for APIv2, ensure that you're viewing it for the Product Catalog version of your Chargebee site.

To know the Product Catalog version of your Chargebee site, follow the steps below:

  1. Click LOGIN on the top right corner.
  2. Log into Chargebee with your account credentials. You are then redirected back to this documentation.
  3. Click on your name on the top right corner. A list of all Chargebee sites you have access to is displayed. The Product Catalog version is displayed under each site's domain name.

DOWNLOADING/INSTALLING CLIENT LIBRARIES

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

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

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:

  • Chargebee client library release version: Release versions of the form 2.x.x indicates APIv2 while 1.x.x indicates APIv1.
  • The API endpoints: The paths begin with /api/v2 for APIv2 and /api/v1 for APIv1.

WHAT CHANGES DOES CHARGEBEE CONSIDER TO BE "BACKWARDS-COMPATIBLE"?

  • Adding new API resources.
  • Adding new attributes to existing API responses.
  • Changing the order of attributes in existing API responses.
  • Adding new API methods for a resource.
  • Adding new 'optional' input params to existing API methods.
  • Adding new attributes to existing API responses.
  • Making an input parameter as 'required' in API methods.
  • Adding new event types.

Python Client Library

s

Installing Python Library

The library can be installed as
pip install 'chargebee>=2,<3'
or
easy_install --upgrade 'chargebee>=2,<3'

Source Code

The source code for the client library is available as a public repository at github. The code is provided with MIT license. So in case you need any modifications please feel free to do so. If you think it would be useful for other users please do let us know.

Library version

Newer versions of client library are released whenever there are new additions to the API. The version numbering format is major-version.minor-version(s). All minor releases are backward compatible. Please check the change notes for more details.
The latest version details for API V2 are:
Version: 2.9.0
Released On: 2021-08-16

Authentication

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 Python

Use the Environment class to configure your site and your API key. It is a global configuration and can be setup as part of your server initialization

chargebee.configure("{site_api_key}","{site}")

Need to support multiple sites?

In some cases you may need to support multiple sites from the same server. You could pass on both the site name and the api key at each request level.

API Keys: Best Practices

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.
Sharing keys: Suggested below are guidelines around sharing API keys with people:
  • 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.

Resources

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

https://{site}.chargebee.com/api/v2/subscriptions


The Python client library provide a corresponding class representation of the resource. For example, subscriptions are represented by 

chargebee.Subscription

Request

All operations specific to that resource are exposed as class methods in the corresponding resource class. The methods accepts the input params as hash. You could also pass the environment configuration specific to that request as an additional parameter.

Response

The response is in JSON format. Currently Chargebee does not support any other response format. The Result class wraps the response sent by the server. It has methods that allow you to fetch the specific resource from the result. The ListResult class is used to wrap list responses.

Sample Codes 
# creates a subscription with customer information and billing details.

import chargebee
import json
chargebee.configure("{site_api_key}","{site}")
result = chargebee.Subscription.create({
    "plan_id" : "no_trial",
    "auto_collection" : "off",
    "billing_address" : {
        "first_name" : "John",
        "last_name" : "Doe",
        "line1" : "PO Box 9999",
        "city" : "Walnut",
        "state" : "California",
        "zip" : "91789",
        "country" : "US"
        },
    "customer" : {
        "first_name" : "John",
        "last_name" : "Doe",
        "email" : "john@user.com"
        }
    })
subscription = result.subscription
customer = result.customer
card = result.card
invoice = result.invoice
unbilled_charges = result.unbilled_charges
copy

Sample Result [ JSON ]


Admin Console Details Page

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.

https://{site}.chargebee.com/admin-console/<resource>/<id>

Here is an example of a constructed url for a subscription with id 123xyz

https://{site}.chargebee.com/admin-console/subscriptions/123xyz

Note:
  • 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.

Currencies

Chargebee supports billing in 100+ currencies. PC 2.0

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
To maintain backward compatibility in the API, the legacy price and quantity attribute/parameter behavior has not been altered. New attributes/parameters have been introduced for them as their decimal equivalents. For example:
  • 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
While multiple decimal places are supported for prices and quantities in Chargebee, at the invoice line item-level, the amount is always rounded off 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. 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 is (0.0765 x $10.674) = $0.816561 and is rounded off to $0.82.
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:

Multiple Gateway Accounts

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:

Caution

Passing gateway, card[gateway], payment_method[gateway] parameters would result in an error in this case since those parameters only resolve the gateway and not the specific account for that gateway.

  • Customer-related requests
  • Subscription-related requests
  • Card-related requests
  • Hosted Page-related requests

    • Multiple Payment Sources

    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:

    Notes:

    • The first payment source created for a customer will be automatically marked as the Primary payment source for the customer.
    • The Payment Source provided in the hosted pages by a customer always replaces the Primary payment source for the customer. If a payment source does not exist, it creates a new payment source and marks it as Primary.

    API Rate Limits

    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.

    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 

    Error Handling

    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.

    { "message":"Plan is not present", "type":"invalid_request" "api_error_code":"resource_not_found", "param":"item_id" }

    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

    The following attributes are returned as part of the error content. The python library exposes these as attributes in APIError
    message
    A descriptive information about the error. This is for developer(/merchant) consumption and should not be used for showing errors to your customers.
    type
    An optional attribute which groups errors based on the error handling routine that is required. The types are payment, invalid_request and operation_failed. The client libraries throw a corresponding exception for easy error handling.
    api_error_code
    A more specific code allowing you to handle the specific errors.
    param
    An optional attribute which is provided if the error is due to a specific parameter. The parameter name is the same as that seen in this documentation when the language chosen is cURL.
    Note: For the same API, 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.

    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.

    APIError
    This is the root exception class for all the api related errors. It contains all the attributes of the error. Error such as authentication failure are thrown as this exception.
    Extends: Exception
    PaymentError
    All payment related errors including payment method detail validation (such as card number validation) and verification.
    Extends: APIError
    InvalidRequestError
    All errors due to invalid request.
    Extends: APIError
    OperationFailedError
    Thrown if the request parameters were right but the requested operation could not be completed. The reasons might be the api request limit was exceeded or could be due to an issue in ChargeBee side. These should occur very rarely and mostly be of temporary nature.
    Extends: APIError

    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

    Error Codes List

    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.

    Payment Errors

    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.

    Code
    Description
    payment_processing_failed
    Returned when the payment collection fails.
    HTTP Code: 400, Sample message: Subscription cannot be created as the payment collection failed. Gateway Error: Card declined.
    payment_method_verification_failed
    Returned when validation or verification fails for the provided payment method. For example if the payment method is card, this will include all card parameter validation errors and also verification failures from the gateway.
    HTTP Code: 400, Sample message: Problem while adding the card. Error message : AVS check failed.
    payment_method_not_present
    Returned when the request requires payment collection but the 'payment method' details (such as card) is not present for the customer. This error will not occur if auto-collection is disabled for the customer.
    HTTP Code: 400, Sample message: Card is not present when reactivating the subscription
    payment_gateway_currency_incompatible
    Returned when the payment gateway configured is incompatible with the transactional currency. This error will not occur if auto-collection is disabled for the customer.
    HTTP Code: 400, Sample message: The configured gateway account [ PAYPAL_EXPRESS_CHECKOUT ] does not support transactions in INR.
    payment_intent_invalid
    Returned when validation or verification fails for provided payment intent.For example if payment intent which is passed is in not consumable state.
    HTTP Code: 400, Sample message: Problem while processing payment intent. Probable Reason: Invalid state
    payment_intent_invalid_amount
    Returned when processing amount is different from payment intent amountFor example if payment intent which is passed has authorized 10$ and if the charges initiated is for 12$.
    HTTP Code: 400, Sample message: Problem while processing payment intent . Probable Reason: amount mismatch

    Invalid Request Errors

    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.

    Code
    Description
    resource_not_found
    Returned when any of resource(s) referred in the request is not found.
    HTTP Code: 404, Sample message: 82sa2Sqa5 not found
    resource_limit_exhausted
    Returned when any limit constraint is violated by the request. For example this error is thrown when the coupon provided has already expired or its maximum redemption count has been reached.
    HTTP Code: 400, Sample message: Coupon has expired
    param_wrong_value
    Returned when the value does not meet the required specification for the parameter. For example, wrong email format. It is strongly recommended to do the validation at your end before calling Chargebee's API (other than specific cases like VAT number validation).
    HTTP Code: 400, Sample message: invalid email format
    duplicate_entry
    Returned when the request provides a duplicate value for an attribute that is specified as unique for that site. For example in 'create subscription api' if you are passing the subscription id then this error will be thrown if a subscription exists in site with the same id.
    HTTP Code: 400, Sample message: The value Hy5r4129u is already present.
    db_connection_failure
    Returned when db connection fails.
    HTTP Code: 503, Sample message: Sorry, unable to complete the operation due to db communication failure. Please try after some time
    invalid_state_for_request
    Returned when the requested operation is not allowed for current state of the resource. This error will occur if the state of the resource has not been checked for the validity of the request. For example this error is returned when we try to schedule subscription changes at 'end of term' for canceled subscriptions.
    HTTP Code: 409, Sample message: Only pending invoices can be closed.
    http_method_not_supported
    Returned when the 'http method', specified in the request, is not allowed for this URL. It should not occur if you are using one of the standard client library.
    HTTP Code: 405, Sample message: Sorry,the http method GET is not supported for this URL.
    invalid_request
    Returned when the request has incompatible values or does not match the API specification. As it is a generic error, handling this error is recommended only in combination with param attribute.
    HTTP Code: 400, Sample message: The plan's billing period and addon's billing period are incompatible.
    resource_limit_exceeded

    HTTP Code: 400, Sample message:

    Operation Failure Errors

    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.

    Code
    Description
    internal_error
    Returned when the request parameters were right but the operation couldn't be completed due to a bug in Chargebee side.
    HTTP Code: 500, Sample message: Sorry,Something went wrong when trying to process the request.
    internal_temporary_error
    Returned when temporary occured in Chargebee side. The request can be re-tried, with exponential backoff in case of repeat failures.
    HTTP Code: 503, Sample message: Sorry,A temporary error occured when trying to process the request.
    request_blocked
    Returned when request is blocked for your site. The blocking could be only for a specific set of operation(s) . The reason would be provided as part of the message. You would have to contact support for additional details.
    HTTP Code: 403, Sample message: Sorry, The request is blocked
    api_request_limit_exceeded
    Returned when requests have been blocked temporarily due to request count exceeding acceptable limits.
    HTTP Code: 429, Sample message: Sorry, access has been blocked temporarily due to request count exceeding acceptable limits. Please try after some time.
    site_not_ready
    Returned when your site is temporarily unavailable due to a scheduled maintenance.
    HTTP Code: 503, Sample message: Site is not ready. Please retry the request after sometime.
    site_read_only_mode
    Returned when your site is temporarily unavailable for write operations due to a scheduled maintenance.
    HTTP Code: 503, Sample message: Site is in read only mode. Please retry the request after sometime.

    Other API errors

    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.

    Code
    Description
    api_authentication_failed
    Returned when authentication failed for the request. The possible reasons could be the api key is invalid or authentication header is not present in the request or the header's format is invalid.
    HTTP Code: 401, Sample message: Sorry, authentication failed. Invalid API Key.
    api_authorization_failed
    Returned when the API key does not have sufficient privileges to perform the particular operation.
    HTTP Code: 403, Sample message: Sorry, authorization failed. The key does not have the required permissions
    site_not_found
    Returned when the site is not found.
    HTTP Code: 404, Sample message: Sorry, we couldn't find the site acme
    configuration_incompatible
    Returned when the request is not compatible with the configuration for the site or the configuration is incomplete.
    HTTP Code: 400, Sample message: Return URL for the hosted page not configured.

    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"})

    Note: Reminder mails (such as card expiry) and other scheduled events cannot be disabled using this option

    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"
     })

    Webhook IP Addresses

    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:

    3.209.65.25 3.215.11.205 3.228.118.137 3.229.12.56 3.230.149.90 3.231.198.174 3.231.48.173 3.233.249.52 18.210.240.138 18.232.249.243 34.195.242.184 34.206.183.55 35.168.199.245 52.203.173.152 52.205.125.34 52.45.227.101 54.158.181.196 54.163.233.122 54.166.107.32 54.84.202.184

    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:

    18.159.27.9 18.159.5.237 3.126.22.116 3.124.98.200 18.158.188.144 18.197.55.93 18.158.1.51 18.159.186.201 18.159.83.75 3.121.1.124 52.28.49.9 52.58.215.160

    View the above list in Google Sheets

    Custom Fields

    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.

    Meta Data

    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:

    • Subscriptions
    • Customers
    • Items
    • Item prices
    • Coupons

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

    Note:
    • Meta Data is completely for your reference and will not be visible to customers in the hosted pages. If you'd like to include fields other than the default ones in the hosted pages, you could use Custom Fields.
    • Meta data will not be a filter criteria, or a part of the exports. For this purpose, Custom Fields can be used if necessary.

    Pagination and Filtering

    Chargebee supports bulk fetching of resources via 'List' API methods. (List invoices, List subscriptions etc..) The sections that follow explain how you can use the Filtering and Pagination options on these 'list' API methods.

    Pagination

    Pagination can be controlled by following parameters:
    • limit: This limits the number of resources to be returned in the response. The value ranges from 1 to 100 and defaults to 10.
    • offset: If not specified, the first set of resources (number of resources limited by the limit parameter) will be returned. If more resources are present, a 'next offset' parameter is returned in the result. To fetch the next set (page) of resources, use this offset parameter. It's value should be the next_offset attribute returned in your previous list api invocation.

    Incremental Syncing of resources

    For purposes such as data warehousing, you may need to sync data periodically from Chargebee. We recommend using the list APIs for the various resources you want to sync. (For example, List customers or List subscriptions.) Use the updated_at filter and the sort_by parameter set to updated_at asc when calling the API. Given below is a more detailed algorithm:

    Initial Sync
    1. Initialize end_time = sync start time.
    2. Call the list API with the following parameters (the returned data will be paginated, so do this till the page size is 0):
      • updated_at set to before end_time.
      • sort_by set to updated_at asc.
      • offset set to the value of next_offset from the previous API call.
    3. For every resource fetched above: If the resource_version of received resource > resource_version of same resource cached or stored on your side, update the resource on your side with the received version. If the condition is not true, then ignore the received resource.
    All Subsequent Syncs
    1. Initialize last_sync_time = previously stored end_time minus 5 minutes. (During the previous sync, updates may have happened concurrently while the resources were being fetched. The negative 5 minutes is to ensure that any such resources missed during the last sync, are fetched this time.)
    2. Set end_time= current time.
    3. Call the list API with the following parameters (the returned data will be paginated, so do this till the page size is 0):
      • updated_at set to after last_sync_time.
      • updated_at set to before end_time.
      • sort_by param set to updated_at asc.
      • offset set to the value of next_offset from the previous API call.
    4. For every resource fetched above: If the resource_version of received resource > resource_version of same resource cached or stored on your side, update the resource on your side with the received version. If the condition is not true, then ignore the received resource.
    Note: If you need to be notified of events immediately, use webhooks. This is useful for instance, when you must provision services as soon as a subscription has been created.

    FETCHING DELETED RESOURCES

    Normally when you fetch resources using our List APIs the deleted resources will not be included. However, if you specify the 'include_deleted' param as 'true', the deleted resources will also be included as part of the response. The 'deleted' attribute can be used to identify the deleted resources in the response.

    Sorting

    In the List methods, the sort_by parameter is provided for sorting the result in the desired order. Both the attribute (created_at, etc.) based on which sorting needs to be done, and the order of sorting (ascending or descending) can be specified.
    Example: "sort_by[asc]" : "[created_at]". Sorts by created_at attribute in the ascending (earliest first) order.

    Filtering

    In the List methods, filtering of resources can be performed using filter parameters. Please refer to the corresponding method's documentation for the complete list of supported filter parameters. The following types of filter parameters are supported now:
    • string
    • enumerated string
    • number
    • timestamp
    • boolean
    The operators supported for a filter parameter is based on the filter parameter type, as explained below:
    Filter operators:
    • is: Returns the resource, if the filter attribute's value matches the specified value.
      Supported filter types: string, enumerated string, number, boolean
      Example
      • string type: "email[is]" : "john@acme.com"
      • enumerated string type: "status[is]" : "paid"
      • number type: "price[is]" : "1499"
      • boolean type: "taxable[is]" : "true"

    • is_not: Returns the resource, if the filter attribute's value doesn't match the specified value.
      Supported filter types: string, enumerated string, number
      Example
      • string type: "plan_id[is_not]" : "basic"
      • enumerated string type: "status[is_not]" : "paid"
      • number type: "amount_unused[is_not]" : "0"

    • in: Returns the resource, if the filter attribute's value matches any one of the specified values.
      Supported filter types: string, enumerated string
      Example
      • string type: "plan_id[in]" : "[basic,pro]"
      • enumerated string type: "status[in]" : "[payment_due,not_paid]"

    • not_in: Returns the resource, if the filter attribute's value doesn't match any of the specified values.
      Supported filter types: string, enumerated string
      Example
      • string type: "plan_id[not_in]" : "[basic,pro]"
      • enumerated string type: "status[not_in]" : "[payment_due,not_paid]"

    • is_present: If the specified value is 'true', returns the resource that has it's filter attribute value set (i.e. not null), and if the specified value is 'false', returns the resource that does not have it's filter attribute value not set (i.e. null).
      Supported filter types: string, enumerated string, number, timestamp, boolean
      Example: "email[is_present]" : "false" (This will return customer resources, whose email attribute is not set).
    • starts_with: Returns the resource, if the filter attribute's value starts with the specified value.
      Supported filter types: string
      Example: "company[starts_with]" : "A"
    • gt: Returns the resource, if the filter attribute's value is greater than the specified value.
      Supported filter types: number
      Example: "price[gt]" : "1000"
    • gte: Returns the resource, if the filter attribute's value is greater than or equal to the specified value.
      Supported filter types: number
      Example: "price[gte]" : "1499"
    • lt: Returns the resource, if the filter attribute's value is lesser than the specified value.
      Supported filter types: number
      Example: "price[lt]" : "1000"
    • lte: Returns the resource, if the filter attribute's value is lesser than or equal to the specified value.
      Supported filter types: number
      Example: "price[lte]" : "1499"
    • between: Takes in two values as input. Returns the resource, if the filter attribute's value falls within the specified range (the range is inclusive).
      Supported filter types: number, timestamp
      Example
      • string type: "price[between]" : "[1499,4999]"
      • timestamp type: "created_at[between]" : "[1454371200,1454371200]"

    • on: Returns the resource, if the filter attribute's value is equal to the date part of the specified timestamp input.
      Supported filter types: timestamp
      Example: "created_at[on]" : "1456147530"

      Note: Only the date part of the specified timestamp input will be considered. So in the above example, even though the specified timestamp value evaluates to 2016-02-22 13:25:30 UTC, the resource created on 2016-02-22 will be returned.


    • before: Returns the resource, if the filter attribute's value is lesser than the specified timestamp value.
      Supported filter types: timestamp
      Example: "created_at[before]" : "1456147530"
    • after: Returns the resource, if the filter attribute's value is greater than the specified timestamp value.
      Supported filter types: timestamp
      Example: "created_at[after]" : "1456147530"

    Use Case Guides

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