Chargebee

Chargebee is a subscription management software that takes care of your billing requirements. It helps you launch and automate your subscription business with its invoicing, payment recovery, pricing management, and other solutions.

Chargebee hosts your account data in data centers located in the AU, EU, or the US region. However, Hevo can fetch your Chargebee data from any of these data centers, irrespective of the region in which your Hevo account is created.

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.


Prerequisites

  • An active account in Chargebee.

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


Configuring Chargebee as a Source

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

  1. Click PIPELINES in the Asset Palette.

  2. Click + CREATE in the Pipelines List View.

  3. In the Select Source Type page, select Chargebee.

  4. In the Configure your Chargebee Source page, specify the following:

    Configure your Chargebee Source

    • 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 the existing data in the Source must be ingested. Default value: 3 Months.

      Note: If you select All Available Data, Hevo fetches all the data created since January 01, 1970 for your account.

  5. Click TEST & CONTINUE.

  6. Proceed to configuring the data ingestion and setting up the Destination.


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.

Note: The API keys are different for your test site and your live site.

Perform the following steps to generate your API key:

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

  2. In the left navigation pane, click the Settings ( ) icon, and click Configure Chargebee.

    Configure Chargebee

  3. In the Configure Chargebee page, scroll to the API Keys and Webhooks section, and click API keys.

    API Keys and Webhooks

  4. In the API Keys and Webhooks page, click + Add API Key.

    Add API Key

  5. In the Create an API Key dialog, do the following:

    1. Select the API key type as Read-Only Key.

      Read-Only Key Type

    2. Select All, to allow Hevo to make read-only API calls, and click Create Key.

      Create API Key

  6. Copy the key, and save it in a secure location like any other password.

    Created API Key


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.


Data Replication

Default Pipeline Frequency Minimum Pipeline Frequency Maximum Pipeline Frequency Custom Frequency Range (Hrs)
3 Hrs 15 Mins 24 Hrs 1-24

Note: The custom frequency must be set in hours, as an integer value. For example, 1, 2, 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, all new and updated records are synchronized with your Destination as per the ingestion frequency.


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.

Limitations

  • Hevo does not capture information for records deleted in the Source objects.



Revision History

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

Date Release Description of Change
Sep-05-2022 NA Updated section, Data Replication to reorganize the content for better understanding and coherence.
May-25-2022 1.89 New document.
Last updated on 13 Sep 2022

Tell us what went wrong