API Version
Product Catalog
Library

Advanced features

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.

Early Access

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"    

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.

Note

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.

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

Examples

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

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  https://mysite.chargebee.com/api/v2/customers \
     -H chargebee-event-actions:all-disabled \
     -u myapikey: \
     -d customer[email]="john@user.com" \    

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

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

Sample Request

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"

Metadata

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.

Limitations of metadata

  • Metadata has a character limit of 65,535.
  • 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.
Tip

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:

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

    Multiple Business Entities is currently in early access. Contact eap@chargebee.com to join the Early Adopter Program and enable this feature.

    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.

    See also

    More information on business entities and the configuration options available.

    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.

    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.

    Note

    Some of the terminology used here defined in the next section.

    Operation/Type of operation

    Behavior

    Examples

    Any operation that creates a customer resource

    • If business_entity_id is provided, the customer resource is created and linked to it.

    • If business_entity_id is not provided, the customer resource is created under the default business entity of the site.

    Create a resource other than customer

     

    • If business_entity_id is provided, and it is the same as that linked to the target resource: the resource is created and linked to the business entity provided.

    • If business_entity_id is provided, and it is not the same as that linked to the target resource, a 404 Not Found response is sent because the resource cannot be found in the context of the business entity specified.

    • If business_entity_id is not provided, the resource is created and linked to the business entity of the target resource.

    Update/delete a resource

    • If business_entity_id is provided, and it is the same as that linked to the resource, the operation proceeds successfully.

    • If business_entity_id is provided, and it is not the same as that linked to the resource, a 404 Not Found response is sent because the resource cannot be found in the context of the business entity specified.

    • If business_entity_id is not provided, the operation proceeds successfully.

    List resources

    • If business_entity_id is provided, then only those resources linked to the business entity are returned since the context of the operation is now restricted to the business entity specified.

    • If business_entity_id is not provided, then all resources in the site are returned.

    Retreive a resource

    • If business_entity_id is provided, and it is the same as that linked to the resource, the resource is retrieved successfully.

    • If business_entity_id is provided, and it is not the same as that linked to the resource, a 404 Not Found response is sent because the resource cannot be found in the context of the business entity specified.

    • If business_entity_id is not provided, the resource is retrieved successfully.

    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.

    Example

    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.

    Target resource

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

    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.