Chargebee

Last updated on Feb 05, 2025

Hevo uses the Chargebee v2 API endpoints to replicate your data into the desired Destination database or data warehouse. For this, you must provide Hevo with an API key to access your account’s data. Refer to the Data Model section for information on the objects that Hevo creates in your Destination.

Chargebee Sites

Chargebee uses a Site to maintain your account information such as your billing configurations, your product catalog, and so on. It assigns two sites to every account, and the information maintained in each of these sites is independent of the other. You can, however, transfer configurations between these sites. For example, you can transfer all your billing configurations from one site to the other.

The two types of sites in Chargebee are:

Test Site: The test site is a sandbox environment, and this is enabled when you set up your account’s domain and company name. Using this site, you can test Chargebee’s features such as billing configurations, creating plans, and customer subscriptions.

A test site’s name is your live site’s name with a -test suffix. For example, suppose your live site’s name is abccompany23, and the URL is abccompany23.chargebee.com. Then, your test site’s name becomes abccompany23-test, and the URL becomes abccompany23-test.chargebee.com.
Live Site: The live site is your production environment, and this is disabled when you sign up for Chargebee. You can activate your live site once you have finished testing your setup, and are ready to start billing your customers in real-time.

Read Understanding your Chargebee Dashboard to know about setting up your test site and enabling the live site.

Setup

Data Sync

Prerequisites

An active Chargebee account from which data is to be ingested exists.
A user with an Admin or Owner role in your Chargebee account. Read Users & Roles to know more about assigning different roles to a user.
The API key of your site with read-only access to your Chargebee account data is available to Hevo.
Your Chargebee site’s name is available to Hevo.
You are assigned the Team Administrator, Team Collaborator, or Pipeline Administrator role in Hevo to create the Pipeline.

Generating the API Key

Chargebee authenticates API requests from Hevo to access your account data with HTTP Basic authentication, where the username is your API key.

Notes:

You must log in as a user with the Admin or Owner role to perform these steps.
The API keys are different for your test site and your live site.

Perform the following steps to generate your API key:

Log in to your Chargebee account. If you have accounts in multiple regions with the same email address, use the region-specific URL to sign in.
In the left navigation pane, click the Settings ( ) icon, and click Configure Chargebee.
In the Configure Chargebee page, scroll to the API Keys and Webhooks section, and click API keys.
In the API Keys and Webhooks page, click + Add API Key.
In the Create an API Key dialog, do the following:
1. Select the API key type as Read-Only Key.
2. Select All, to allow Hevo to make read-only API calls, and click Create Key.
Copy the API key and save it securely like any other password. Use this key while configuring your Hevo Pipeline.

Configuring Chargebee as a Source

Perform the following steps to configure Chargebee as the Source in your Pipeline:

Click PIPELINES in the Navigation Bar.
Click + CREATE PIPELINE in the Pipelines List View.
In the Select Source Type page, select Chargebee.
In the Configure your Chargebee Source page, specify the following:
- Pipeline Name: A unique name for your Pipeline, not exceeding 255 characters.
- Domain Name: The name of your Chargebee site. Extract this from your Chargebee URL. For example, if the URL is https://abccompany23.chargebee.com, your domain name is abccompany23.
- Chargebee API Key: A secret value with read-only access to your Chargebee data via the v2 APIs.
  
  Note: The API key is specific to the domain name.
- Historical Sync Duration: The duration for which you want to ingest the existing data from the Source. Default duration: 3 Months.
  
  Note: If you select All Available Data, Hevo ingests all the data available in your Chargebee account since January 01, 1970.
Click TEST & CONTINUE.
Proceed to configuring the data ingestion and setting up the Destination.

Data Replication

For Teams Created	Default Ingestion Frequency	Minimum Ingestion Frequency	Maximum Ingestion Frequency	Custom Frequency Range (in Hrs)
Before Release 2.21	3 Hrs	15 Mins	24 Hrs	1-24
After Release 2.21	6 Hrs	30 Mins	24 Hrs	1-24

Note: The custom frequency must be set in hours as an integer value. For example, 1, 2, or 3 but not 1.5 or 1.75.

Historical Data: In the first run of the Pipeline, Hevo ingests the historical data for all the objects using the Recent Data First approach. The data is ingested on the basis of the historical sync duration selected at the time of creating the Pipeline and loaded to the Destination. Default duration: 3 Months.
Incremental Data: Once the historical load is complete, data is ingested as per the ingestion frequency in Full Load or Incremental mode, as applicable.

Schema and Primary Keys

Hevo uses the following schema to upload the records in the Destination:

Data Model

The following is the list of tables (objects) that are created at the Destination when you run the Pipeline:

Object	Description
Credit Notes	Contains the data related to any credit notes issued to a customer. A credit note is a document for the refund amount issued to the customers for reasons such as a product return, a canceled purchase, or an incorrect invoice amount, which can be used for future purchases.
Customers	Contains information about your customers.
Events	Contains information about the events triggered when a change takes place in your Chargebee site. For example, when a customer is created in your account, the `customer_created` event is recorded.
Invoices	Contains information about the sale of products and services offered by you. An invoice is a commercial document, and it enumerates all the charges, adjustments, payments, and discounts and taxes associated with the sale.
Orders	Contains information about the orders automatically generated for an invoice when it is paid.
Payment sources	Contains information about the payment sources associated with a customer.
Subscriptions	Contains information about the products or services your customer has signed up for, and the amount they are charged for their subscription.
Transactions	Contains information about the transaction events generated in your account every time Chargebee makes a payment-related operation on an invoice, such as a successful charge, failure, authorization, or refund.
Virtual bank accounts	Contains information about the unique account numbers generated by Chargebee for the bank accounts associated with your Chargebee account. You can share your virtual bank account number with a customer to receive payments.

Additional Information

Read the detailed Hevo documentation for the following related topics:

Source Considerations

Chargebee restricts API requests based on your Chargebee pricing plan, the site from which a request is made, and a limiting mechanism. The limit mechanism criteria are the number of requests made in a minute and the number of concurrent requests at an instance in time. If Hevo exceeds any of these criteria, data ingestion for your site is deferred until the limits are reset (approximately a minute).

Read API Rate Limits to know the limits for your plan, and configure a suitable ingestion frequency for your Pipeline.

Limitations

Hevo does not capture information for records deleted in the Source objects.
Hevo does not load an Event into the Destination table if its size exceeds 128 MB, which may lead to discrepancies between your Source and Destination data. To avoid such a scenario, ensure that each row in your Source objects contains less than 100 MB of data.

Revision History

Refer to the following table for the list of key updates made to this page:

Date	Release	Description of Change
Jan-07-2025	NA	Updated the Limitations section to add information on Event size.
Mar-05-2024	2.21	Updated the ingestion frequency table in the Data Replication section.
Sep-05-2022	NA	Updated section, Data Replication to reorganize the content for better understanding and coherence.
May-25-2022	1.89	New document.