You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).
You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).

Advanced features

The Chargebee API offers additional features such as custom HTTP request headers, custom fields, metadata. Moreover, the ability to set up multiple payment sources, and gateway accounts is also available. The sections below describe how to use these features.

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 is validated against active fraud detection filters, and used for EU tax validation, referral integration, and event reports. Email addresses and device information, even more ubiquitous, are used for identification. Chargebee supports the following custom HTTP request headers for providing such user details:

  • chargebee-request-origin-ip: Used to provide the IP address, of your customer/user, from where the request originated. For example,
  • chargebee-request-origin-user: Used to provide the email address of your customer/user. Use this when the email address has only ASCII characters. For example,
  • chargebee-request-origin-user-encoded: Used to provide the Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters (such as user.квіточка When this header is provided, the header chargebee-request-origin-user is ignored.
  • chargebee-request-origin-device: Used to provide a string indicating the device from which the request was made. For example, Android, Ubuntu, or iOS.


Providing user details with the email address containing only ASCII characters:

curl \
     -H chargebee-request-origin-ip:\
     -H chargebee-request-origin-device:Android\
     -u myapikey: \
     -d customer[email]="" \

Providing user details with the email address containing UTF-8 characters (here user.квіточка

curl https://{my-site} \ -H chargebee-request-origin-ip:\ -H chargebee-request-origin-user-encoded:dXNlci7QutCy0ZbRgtC+0YfQutCwQGV4YW1wbGUuY29t\ -H chargebee-request-origin-device:Android\ -u {my-api-key}: \ -d customer[email]="user.квіточка" \

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
curl \
     -H chargebee-event-actions:all-disabled \
     -u myapikey: \
     -d customer[email]="" \    

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

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 API. More on Custom Fields here.

Note: Custom Fields can only be created via the web interface, not via API.

Sample Request

curl https://{site} \
-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" } }

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

Chargebee supports configuring multiple gateway accounts for a gateway type (eg: you can configure multiple 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:

  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:


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

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.