API Overview

Chargebee provides HTTP based API which follows the essence of REST*. The HTTP protocol's rules are followed thereby enabling simple HTTP client tools like "curl" to be used.

The following client libraries provide a "easy to use" wrapper around the raw HTTP based API.

• PHP
• Ruby
• Python
• Java
• .Net
• Node
• Go
• Typescript

Please do mail us at support@chargebee.com if you need any other language bindings.

Sample Snippets

The top language bar allows you to see samples in your preferred language.

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.

Chargebee now supports two API versions - V1 and V2. V2 version has been released to accommodate certain backwards-incompatible changes that we wanted to make over V1 for a more streamlined functionality.

All further developments will happen in V2. However we will continue to support V1 in order to avoid breaking your code.

Downloading/Installing Client libraries:

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

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

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:

• The Chargebee client lib release version: Release versions 1.x.x indicate that you're on V1 and 2.x.x indicate that you are on V2.
• The API end-points: They start with /api/v1 for V1 and /api/v2 for V2.

What changes does Chargebee consider to be "backwards-compatible"?

As all of our future development will happen in API V2, the latest version of Chargebee API, you might want to upgrade to V2 to benefit from the new functionality.

What's changed in API V2 ?

The changes made in V2 that are not V1-compatible, are listed in this section. You may want to change your existing code appropriately as part of the upgradation process.

Refunds-related changes to Invoice and Transaction resources:

In API V1, refunds were directly linked to Invoices. In V2, refunds are not directly linked to Invoices; instead they are linked to Credit Notes, which in turn are linked to their respective invoices.

• The attribute linked_transactions[] , which listed both the payments and refunds applied to this invoice, is removed in V2. It is replaced by linked_payments[] attribute, which lists only the payments applied to this invoice.
• The linked_invoices[] attribute in V1, is no longer applicable for the transaction type 'refund' in V2. Instead, linked_credit_notes[] attribute is provided, which lists the Credit Notes to which this refund is attached.
• The operation List transactions for an invoice is removed in V2. It is replaced by the list operation List payments for an invoice, which lists only the payment transactions linked to the invoice.

Changes to Estimate Resource:

The Estimate resource has been revamped in V2: in V1 it had both subscription and invoice related attributes without any segregation at the top level. Whereas in V2, all the subscription related attributes are grouped under subscription_estimate sub-resource and all the invoice related attributes are grouped under invoice_estimate sub-resource. Additionally, the following changes have been made:

• The attribute collect_now has been removed. The invoice_estimate returned by the 'Create Subscription' and 'Change Subscription' Estimates, will represent the estimate of the invoice that will get generated immediately.
• If no invoice gets generated during Estimate invocations ('Create Subscription Estimate', etc.), the invoice_estimate sub-resource will not be returned.
• The invoice_estimate returned by Estimate operations (such as 'Change Subscription Estimate') will include the existing customer balances - Promotional Credits, Refundable Credits, and Excess Payments - by default. This is not the default behavior in API V1.

Country input parameters - strict validation done:

For the 'country' input parameters - card[billing_country], billing_address[country], shipping_address[country], address[country] - in the operations like 'Create Subscription' etc, the 2-letter ISO 3166 alpha-2 code is expected. But in V1, for few sites, we were allowing values in other formats too (like full country names). In V2, only the 2-letter ISO 3166 codes are allowed. For other formats, error will be thrown.

Invoice subtotal:

In API V1 the sub_total attribute is the sum of all the line items and discounts. Whereas in V2, this is sum of line items and item-level discount amounts alone. So in V2, document-level discounts are not part of the sub_total.

Void and Delete Invoice operations:

With V2, when an invoice is voided/deleted, and 'Prorated credits' have been applied to the invoice, they will be reclaimed and added back to the subscription.

Attributes and operations that have been renamed/removed:

This section provides the complete listing of the attributes and operations that have been renamed/removed in API V2 for a more streamlined functionality:

Customer Resource:

Account Credits are now called Promotional Credits. We have renamed the related attributes and operations to reflect the same:

• Attribute account_credits is renamed to promotional_credits.
• Operation Add account credits is renamed to 'Add Promotional credits'.
• Operation Deduct account credits is renamed to 'Deduct Promotional credits'.
• Operation Set account credits is renamed to 'Set promotional credits'.

Invoice Resource:

• Operation Collect (which is used for closing a pending invoice) is renamed to 'Close'
• The following Invoice attributes are renamed:
  • end_date is renamed to date.
  • amount is renamed to total.
  • paid_on is renamed to paid_at.
  • next_retry is renamed to next_retry_at.
  • line_items[].tax is renamed to line_items[].tax_amount.
  • discounts[].type is renamed to discounts[].entity_type.
• The attribute start_date is removed.
• The attribute line_items[].type is removed (line_items[].entity_type captures all the required details in API V2).
• The attribute linked_transactions[] is removed. More details here

Transaction Resource:

• The attribute linked_invoices[].invoice_amount is renamed to linked_invoices[].invoice_total.
• The attribute linked_invoices[] is not applicable for 'refund' type in V2. More details here.
• The operation List transactions for an invoice is removed. More details here.
• The operation Record payment for an invoice is moved under Invoice resource in V2.

Estimate Resource:

Estimate resource is completely revamped in V2. More details here.

Event Resource:

The following event types are renamed in API V2:

• subscription_trial_ending is renamed to subscription_trial_end_reminder.
• subscription_cancelling is renamed to subscription_cancellation_reminder.
• invoice_created is renamed to pending_invoice_created.
• card_expiring is renamed to card_expiry_reminder.

Transitioning Webhooks from V1 to V2

As part of the upgradation process, you need to move your webhooks too, from V1 to V2.

To transition webhooks to API version V2:

1. Designate a different URL endpoint (different from that of your V1 based webhook URL) for processing the API V2 based events.
2. Follow these step during your deployment process:
   1. Just before starting the deployment, create a webhook for the new URL. Specify its API Version as 'V2'.
   2. Immediately remove the V1 based webhook.
   3. Deploy the API V2 client library in your webhook server(s). During this deployment time, few webhook notifications (till your webhook servers are completely up) may fail. However, Chargebee will do automatic retries, so the missed events will get processed once your webhook servers are up.

If you require assistance for transitioning your webhooks to API version V2, reach out to support@chargebee.com.

You can use cURL to test Chargebee API from a CLI. When you pass input parameters to the API using -d or --data-urlencode options, the HTTP POST method is used:

curl https://{site}.chargebee.com/api/v1/subscriptions/{subscription_id}/change_term_end
    -u {site_api_key}:\
    -d term_ends_at=1601490600

curl https://{site}.chargebee.com/api/v1/subscriptions/{subscription_id} \
    -u {site_api_key}:

curl -X POST https://{site}.chargebee.com/api/v1/exports/subscriptions \     -u {site_api_key}:

curl -X POST https://{site}.chargebee.com/api/v1/v2/orders \
    -G  \
    -u {site_api_key}:\
    --data-urlencode limit=3 \
    --data-urlencode status[is]="queued"

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 cURL

For curl you could specify the API key using the -u option

curl {api url} -u {api key}:

Since the password is not present, nothing is specified after the colon(:)

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/v1/subscriptions

  Request

  The HTTP method (like GET,POST) determines the operation type on the resource. Query parameters allow you to provide additional options to the GET requests. POST parameters provide the data to write operations like creation, modification of resource(s).

  By default curl uses GET method. Use -X option to specify a specific HTTP method to use. For passing parameters, use -d option. ( Note: cURL automatically uses to POST method if any parameter is sent via -d option ).

  Response

  The response is in JSON format. Currently Chargebee does not support any other response format.

  Sample Request

  # creates a subscription with customer information and billing details.
  curl  https://{site}.chargebee.com/api/v1/subscriptions \
       -u {site_api_key}:\
       -d plan_id="no_trial" \
       -d customer[first_name]="John" \
       -d customer[last_name]="Doe" \
       -d customer[email]="john@user.com" \
       -d billing_address[first_name]="John" \
       -d billing_address[last_name]="Doe" \
       -d billing_address[line1]="PO Box 9999" \
       -d billing_address[city]="Walnut" \
       -d billing_address[state]="California" \
       -d billing_address[zip]="91789" \
       -d billing_address[country]="US" \
       -d customer[auto_collection]="off"

  copy

  # creates a subscription with customer information and billing details.
  curl  https://{site}.chargebee.com/api/v1/subscriptions \
       -u {site_api_key}:\
       -d plan_id="no_trial" \
       -d customer[first_name]="John" \
       -d customer[last_name]="Doe" \
       -d customer[email]="john@user.com" \
       -d billing_address[first_name]="John" \
       -d billing_address[last_name]="Doe" \
       -d billing_address[line1]="PO Box 9999" \
       -d billing_address[city]="Walnut" \
       -d billing_address[state]="California" \
       -d billing_address[zip]="91789" \
       -d billing_address[country]="US" \
       -d customer[auto_collection]="off"

  Sample Response [ JSON ]

  Show more...

  { "customer": { "account_credits": 0, "allow_direct_debit": false, "auto_collection": "off", "billing_address": { "city": "Walnut", "country": "US", "first_name": "John", "last_name": "Doe", "line1": "PO Box 9999", "object": "billing_address", "state": "California", "state_code": "CA", "zip": "91789" }, "card_status": "no_card", "created_at": 1517506669, "email": "john@user.com", "excess_payments": 0, "first_name": "John", "id": "__test__5SK0bLNFRFuBv6r6j", "last_name": "Doe", "object": "customer", "refundable_credits": 0, "taxability": "taxable" }, "invoice": { "amount": 895, "amount_adjusted": 0, "amount_due": 895, "amount_paid": 0, "billing_address": { "city": "Walnut", "country": "US", "first_name": "John", "last_name": "Doe", "line1": "PO Box 9999", "object": "billing_address", "state": "California", "state_code": "CA", "zip": "91789" }, "credits_applied": 0, "currency_code": "USD", "customer_id": "__test__5SK0bLNFRFuBv6r6j", "end_date": 1517506669, "first_invoice": true, "id": "__demo_inv__7", "line_items": [ { "amount": 895, "date_from": 1517506669, "date_to": 1519925869, "description": "No Trial", "entity_id": "no_trial", "entity_type": "plan", "is_taxed": false, "object": "line_item", "quantity": 1, "tax": 0, "type": "charge", "unit_amount": 895 }, {..} ], "linked_orders": [], "linked_transactions": [], "object": "invoice", "price_type": "tax_exclusive", "recurring": true, "start_date": 1517506669, "status": "payment_due", "sub_total": 895, "subscription_id": "__test__5SK0bLNFRFuBv6r6j", "tax": 0 }, "subscription": { "activated_at": 1517506669, "created_at": 1517506669, "current_term_end": 1519925869, "current_term_start": 1517506669, "due_invoices_count": 1, "due_since": 1517506669, "has_scheduled_changes": false, "id": "__test__5SK0bLNFRFuBv6r6j", "object": "subscription", "plan_id": "no_trial", "plan_quantity": 1, "started_at": 1517506669, "status": "active", "total_dues": 895 } }

  
  

  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.

  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. However, to maintain backward compatibility in the API, decimal prices and quantities are provided and returned via separate parameters and attributes respectively. For prices, use the price_in_decimal or amount_in_decimal parameters/attributes instead of price or amount in the API. Similarly, for quantities, use quantity_in_decimal instead of quantity and use tiers[starting_unit_in_decimal] instead of tiers[starting_unit] and so on.

  The amount is expressed in the major unit of the currency. The major unit of the currency 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--currencies that do not have minor units, such as the Japanese Yen (JPY)--decimal places are not allowed.

  Rounding

  Multiple decimal places only apply for pricing in Chargebee. At the invoice line item-level, the amount is rounded off to two decimal places in the major unit of the currency. 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 of (0.0765 x $10.674) = $0.816561 is rounded off to $0.82.

  Bi-decimal Pricing

  When multi-decimal pricing is not enabled for your site, the units used for currency amounts 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. 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 our Multicurrency support, you will be able to process transactions in additional currencies apart from your site's Base currency.

  
  

  Once Multicurrency support is enabled, the API methods listed below will throw an error as currency_code 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 currency_code input parameter to these methods in Multicurrency mode.

  The list of API methods affected if Multicurrency support is enabled:

  • Customer related methods
  • Add account credits to a customer
  • Deduct account credits from a customer
  • Set account credits for a customer
  • Invoice related methods
  • Create an invoice
  • Create invoice for charge
  • Product Configuration related methods
  • Create a plan
  • Update a plan
  • Create an addon
  • Update an addon
  • Create a coupon

  Multiple Gateway Accounts

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

  • Customer related methods
  • Create a customer
  • Update payment method for a customer
  • Card related methods
  • Update card for a customer
  • Switch gateway
  • Subscription related methods
  • Create a subscription
  • Update a subscription
  • Hosted page related methods
  • Checkout new subscription
  • Checkout existing subscription
  • Update payment method

  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:

  • 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

  Notes:

  1. If you are using the older version of our API (V1), you need to upgrade to our latest version (V2) to be able to use Payment Source API.
  2. The first payment source created for a customer will be automatically marked as the Primary payment source for the customer.
  3. 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.

  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":"plan_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.

  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.
  For example, in the Create a subscription for a customer API call, if plan_id is invalid, then param is set to plan_id. For "multivalued" parameters, the index is part of the parameter name. For example, in the same API call, if the id for the second addon is wrongly passed, then param is set to addons[id][1].
  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.

  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.

  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. The type attribute in the error response is sent as payment.
  

  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. The type attribute in the error response is sent as invalid_request.

  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. The type attribute in the error response is sent as operation_failed.

  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

  
  HTTP Code: 503, Sample message: Site is not ready. Please retry the request after sometime.

  site_read_only_mode

  
  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. The type attribute is not sent in the error response.

  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

          curl  https://mysite.chargebee.com/api/v1/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

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

  
  

  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.

  Sample Request

  curl https://{site}.chargebee.com/api/v1/subscriptions \
  -u {site_api_key}: \
  -d plan_id="basic" \
  -d "cf_notes"="sample" \
  -d "customer[cf_gender]"="sample"

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

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

  Use Case Guides

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