Skip to main content

Chargebee

This page contains the setup guide and reference information for the Chargebee source connector.

Prerequisites​

To set up the Chargebee source connector, you need:

  • A Chargebee API key with read access. A full-access key or a read-only key both work.
  • Your Chargebee site name, which is the subdomain in your Chargebee URL. For example, if your dashboard URL is https://acme.chargebee.com, your site name is acme.
  • The Product Catalog version of your Chargebee site.
info

All Chargebee sites created after May 5, 2021 use Product Catalog 2.0 by default. Sites created before this date use Product Catalog 1.0. You can check your version in the Chargebee API docs under the API Version section.

Set up the Chargebee connector in Calabi Connect​

  1. Log into your Calabi Connect account or navigate to the Calabi Connect dashboard.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Chargebee from the Source type dropdown.
  4. Enter the name for the Chargebee connector.
  5. For Site, enter the site prefix for your Chargebee instance. For example, if your Chargebee URL is https://acme.chargebee.com, enter acme.
  6. For Start Date, enter the date in YYYY-MM-DDTHH:mm:ssZ format. Only data created or updated on or after this date is replicated.
  7. For API Key, enter your Chargebee API key.
  8. For Product Catalog, select your Chargebee Product Catalog version. The connector defaults to Product Catalog 2.0.
  9. Optionally, adjust the Number of concurrent threads to control how many worker threads the connector uses during syncs. The default is 3. Higher values increase throughput but consume more of your Chargebee API rate limit.
  10. Click Set up source.

Supported sync modes​

The Chargebee source connector supports the following sync modes:

Supported streams​

Most streams are supported regardless of your Chargebee site's Product Catalog version, with a few version-specific exceptions.

StreamProduct Catalog 1.0Product Catalog 2.0
Addons✔
Attached Items✔
Comments✔✔
Contacts✔✔
Coupons✔✔
Credit Notes✔✔
Customers✔✔
Differential Prices✔✔
Events✔✔
Gifts✔✔
Hosted Pages✔✔
Invoices✔✔
Items✔
Item Prices✔
Item Families✔
Orders✔✔
Payment Sources✔✔
Plans✔
Promotional Credits✔✔
Quotes✔✔
Quote Line Groups✔✔
Site Migration Details✔✔
Subscriptions✔✔
Subscriptions With Scheduled Changes✔✔
Transactions✔✔
Unbilled Charges✔✔
Virtual Bank Accounts✔✔
note

When using incremental sync mode, the Attached Items stream behaves differently than the other streams. Whereas other incremental streams read and output only new records, the Attached Items stream reads all records but only outputs new records, making it more demanding on your Chargebee API quota. Each sync incurs API calls equal to the total number of attached items in your Chargebee instance divided by 100, regardless of the actual number of Attached Items changed or synced.

Limitations & Troubleshooting​

Rate limiting​

The Chargebee connector should not run into Chargebee API limitations under normal usage. The connector automatically retries rate-limited requests using the Retry-After header provided by the Chargebee API. Create an issue if you encounter any rate limit issues that are not automatically retried successfully.

Chargebee API rate limits vary by plan. See Chargebee's API limits documentation for details.

Deleted resources​

The Chargebee API may return HTTP 404 errors when the connector encounters references to deleted resources, such as subscriptions linked to removed plans or items. The connector handles these errors gracefully by skipping the unavailable resource and continuing the sync. This applies to the Contacts, Subscriptions, Subscriptions With Scheduled Changes, and Quote Line Groups streams.

Product Catalog version mismatch​

Some streams are only available on a specific Product Catalog version. If you attempt to sync a stream that is not compatible with your site's Product Catalog version, the connector skips the stream and logs a message: "Stream is available only for Product Catalog 1.0" or the equivalent for Product Catalog 2.0.

Troubleshooting​

  • Check out common troubleshooting issues for the Chargebee source connector on our Calabi Connect Forum.