The Chargebee API offers additional features such as custom HTTP request headers, custom fields, metadata. Moreover, the ability to set up multiple business entities, payment sources, and gateway accounts is also available. The sections below describe how to use these features.
Multiple Business Entities is currently in early access. Contact eap@chargebee.com to join the Early Adopter Program and enable this feature.
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:
curl https://{site}.chargebee.com/api/v2/customers \ -H chargebee-business-entity-id:__dev__8at09TEfAyAk2\ -u {api-key}: \ -d customer[email]="sarah@acme.com"
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.
If the header and query string parameter are passed together in an API call, their values must be the same or an error is returned.
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, 202.170.207.70
.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, amara@acme.com
.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.квіточка@example.com
). 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 https://mysite.chargebee.com/api/v2/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" \
Providing user details with the email address containing UTF-8 characters (here user.квіточка@example.com
):
curl https://{my-site}.chargebee.com/api/v2/customers \
-H chargebee-request-origin-ip:202.170.207.70\
-H chargebee-request-origin-user-encoded:dXNlci7QutCy0ZbRgtC+0YfQutCwQGV4YW1wbGUuY29t\
-H chargebee-request-origin-device:Android\
-u {my-api-key}: \
-d customer[email]="user.квіточка@example.com" \
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/v2/customers \ -H chargebee-event-actions:all-disabled \ -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, 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.
curl https://{site}.chargebee.com/api/v2/customers \ -u {site_api_key}: \ -d first_name="John" \ -d last_name="Doe" \ -d email="john@test.com" \ -d "cf_gender"="sample"
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:
Metadata can be passed in both the "create" as well as "update" operations against the resource.
You can use custom fields instead of metadata to overcome the above limitations.
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:
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.
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:
Multiple Business Entities is currently in early access. Contact eap@chargebee.com to join the Early Adopter Program and enable this feature.
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:
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.
More information on business entities and the configuration options available.
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.
The table below explains how Chargebee responds to various API calls depending on whether the business entity ID is specified as part of the API call.
Some of the terminology used here defined in the next section.
Any operation that creates a |
|
|
Create a resource other than
|
|
|
Update/delete a resource |
|
|
List resources |
|
|
Retreive a resource |
|
This section defines some useful terms for describing how business entities work.
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.
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.
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.
Consider the List customers API. When you call the API without specifying a business entity, its context is that of the site and therefore returns customer resources for the entire site. However, when you specify a business entity, the context is only that of the business entity, and therefore the customer resources of only the selected business entity are returned.
Let's look at the Create checkout for a new subscription API. Say you're calling this API and providing the customer[id]
parameter. When no business entity is specified, the operation has site context and therefore looks up the ID among all the customer resources in the site. However, when a business entity is provided, the operation has business entity context and looks up the ID only among the customers linked to that business entity.
While creating an API resource other than a customer
, you specify a target resource under which it should be created. For example:
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
.subscription
, the target resource of a subscription
resource is always a customer
resource.quote
resource of type
change_subscription
, the target resource is a subscription
resource.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