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

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

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

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.

Sample Request

curl https://{site}.chargebee.com/api/v2/subscriptions \
-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:

• Subscriptions
• Customers
• Plans
• Addons
• 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:

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 customer
• Import subscription for customer
• 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

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.

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.