Chargebee
Use this page to set up the Chargebee source connector and find reference information.
Prerequisites
Before you set up the Chargebee source connector, you need:
- A Chargebee API key with read access. You can use either a full-access or read-only key.
- Your Chargebee site name. This is the subdomain in your Chargebee URL. For example, if your dashboard URL is
https://acme.chargebee.com, your site name isacme. - The Product Catalog version of your Chargebee site.
:::info Chargebee sites created after May 5, 2021 use Product Catalog 2.0 by default. Sites created before this date use Product Catalog 1.0. Check your version in the API Version section of the Chargebee API docs. :::
Set up Chargebee in Airbyte
- Log into your Airbyte Cloud account or go to the Airbyte Open Source dashboard.
- Click Sources, then click + New source.
- On the Set up the source page, select Chargebee from the Source type dropdown.
- Enter a name for the Chargebee connector.
- For Site, enter your Chargebee instance’s site prefix. For example, if your Chargebee URL is
https://acme.chargebee.com, enteracme. - For Start Date, enter the date in
YYYY-MM-DDTHH:mm:ssZformat. The connector only replicates data created or updated on or after this date. - For API Key, enter your Chargebee API key.
- For Product Catalog, select your Chargebee Product Catalog version. The connector defaults to Product Catalog 2.0.
- Optionally, adjust the Number of concurrent threads to control the worker threads used during syncs. The default is 5. Higher values can increase throughput, but also consume more of your Chargebee API rate limit.
- Click Set up source.
Supported sync modes
The Chargebee source connector supports these sync modes:
Supported streams
Most streams support every Chargebee site Product Catalog version, with a few version-specific exceptions.
| Stream | Product Catalog 1.0 | Product 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
In incremental sync mode, the Attached Items stream lists all parent Items during every sync. It makes one attached-items request for each item. However, it only fetches attached items whose updated_at changed since the previous sync. The first sync reads all attached items belonging to items updated on or after the start date.
Incremental sync has two limitations for this stream:
- Deleting an attached item in Chargebee doesn’t remove its destination record. A full refresh with overwrite replaces the stream’s data and removes the record.
- The connector doesn’t read an item last updated before the start date as a parent. If updated later, it only fetches attached items changed since the previous sync. Therefore, its older attached items are never synced. To prevent this, set an earlier start date or periodically run a full refresh for the stream.
:::
Limitations and troubleshooting
Rate limits
Under normal usage, the Chargebee connector shouldn’t encounter Chargebee API limitations. It automatically retries rate-limited requests using the Chargebee API’s Retry-After header. See Create an issue if rate-limited requests aren’t retried successfully.
Chargebee API rate limits vary by plan. Test sites are limited to 150 requests per minute, regardless of plan. See Chargebee’s API limits documentation for details.
Deleted resources
The Chargebee API may return HTTP 404 errors for references to deleted resources. These include subscriptions linked to removed plans or items. The connector skips the unavailable resource and continues 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 for a specific Product Catalog version. The connector skips streams that aren’t compatible with your site’s Product Catalog version. It then logs: “Stream is available only for Product Catalog 1.0” or the equivalent for Product Catalog 2.0.
Troubleshooting
- Find common Chargebee source connector issues on the Airbyte Forum.
IP allow list
If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.
Changelog
Expand to review
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 0.11.3 | 2026-11-11 | 90376 | Consolidate per-stream error handling into a single handler; retryable errors (including HTTP 429) now retry up to 10 times instead of 5 |
| 0.11.2 | 2026-11-10 | 91456 | Update dependencies |
| 0.11.1 | 2026-11-03 | 90509 | Update dependencies |
| 0.11.0 | 2026-10-30 | 89003 | Add incremental sync support to the attached_item stream |
| 0.10.53 | 2026-10-27 | 89839 | Update dependencies |
| 0.10.52 | 2026-10-20 | 89159 | Update dependencies |
| 0.10.51 | 2026-10-13 | 88525 | Update dependencies |
| 0.10.50 | 2026-10-06 | 87801 | Update dependencies |
| 0.10.49 | 2026-09-29 | 87111 | Update dependencies |
| 0.10.48 | 2026-09-22 | 86576 | Update dependencies |
| 0.10.47 | 2026-09-15 | 85980 | Update dependencies |
| 0.10.46 | 2026-09-08 | 85441 | Update dependencies |
| 0.10.45 | 2026-08-18 | 84510 | Update dependencies |
| 0.10.44 | 2026-08-11 | 83885 | Update dependencies |
| 0.10.43 | 2026-07-28 | 83194 | Update to CDK 7.23.8 (fixes AirbyteCustomCodeNotPermittedError for bundled custom components) and remove the temporary Cloud version override |
| 0.10.42 | 2026-07-28 | 1082 | Roll Cloud back to 0.10.40 — 0.10.41 is built on SDM 7.23.7, which breaks bundled custom components |
| 0.10.41 | 2026-07-28 | 82863 | Update dependencies |
| 0.10.40 | 2026-07-21 | 81761 | Update dependencies |
| 0.10.39 | 2026-06-30 | 81013 | Update dependencies |
| 0.10.38 | 2026-06-23 | 80404 | Update dependencies |
| 0.10.37 | 2026-06-16 | 78619 | Update dependencies |
| 0.10.36 | 2026-06-09 | 79604 | Clean up cancelled RC; revert source to previous stable |
| 0.10.36-rc.5 | 2026-05-27 | 78469 | Remove the local API budget limiter while keeping the default worker count at 5. |
| 0.10.36-rc.4 | 2026-05-26 | 78435 | Reduce default concurrent threads to 3 after rollout duration regressions at 5. |
| 0.10.36-rc.3 | 2026-05-22 | 78366 | Revert default_concurrency to 5, activate tier-aware HTTPAPIBudget, and document subscription_tier for GA rollout |
| 0.10.36-rc.2 | 2026-05-20 | 78300 | Raise default_concurrency to 6 after Phase 1 monitoring of 0.10.36-rc.1 showed no rate-limit signal and faster high-volume sync averages excluding a stable-precedent multi-attempt outlier |
| 0.10.36-rc.1 | 2026-05-18 | 74345 | Raise default_concurrency to 5 (Path B tuning calibrated to the Chargebee Starter tier, 150 req/min = 2.5 req/sec); bump num_workers minimum to 2 and default to 5; add subscription_tier spec field (enum starter/performance/enterprise, default starter); record original Starter and tier-aware HTTPAPIBudget shapes as YAML comments for activation in a follow-up GA RC; enable progressive rollout |
| 0.10.35 | 2026-04-28 | 77207 | Update dependencies |
| 0.10.34 | 2026-04-21 | 75795 | Update dependencies |
| 0.10.33 | 2026-04-13 | 76276 | Rename “concurrent workers” to “concurrent threads” in connector spec |
| 0.10.32 | 2026-03-26 | 75476 | Handle 404 errors in subscription stream to prevent sync failures when Chargebee returns not found for deleted resources |
| 0.10.31 | 2026-03-24 | 74459 | Update dependencies |
| 0.10.30 | 2026-03-03 | 74228 | Update dependencies |
| 0.10.29 | 2026-02-17 | 73452 | Update dependencies |
| 0.10.28 | 2026-02-10 | 72990 | Update dependencies |
| 0.10.27 | 2026-01-20 | 72117 | Update dependencies |
| 0.10.26 | 2026-01-14 | 71716 | Update dependencies |
| 0.10.25 | 2025-12-18 | 70665 | Update dependencies |
| 0.10.24 | 2025-11-25 | 69940 | Update dependencies |
| 0.10.23 | 2025-11-18 | 69621 | Update dependencies |
| 0.10.22 | 2025-10-29 | 68902 | Update dependencies |
| 0.10.21 | 2025-10-21 | 68546 | Update dependencies |
| 0.10.20 | 2025-10-14 | 68083 | Update dependencies |
| 0.10.19 | 2025-10-07 | 67181 | Update dependencies |
| 0.10.18 | 2025-09-30 | 65793 | Update dependencies |
| 0.10.17 | 2025-09-10 | 65996 | Update to CDK v7 |
| 0.10.16 | 2025-08-23 | 65294 | Update dependencies |
| 0.10.15 | 2025-08-09 | 64707 | Update dependencies |
| 0.10.14 | 2025-08-04 | 63936 | Fix missing data in subscriptions with scheduled changes stream |
| 0.10.13 | 2025-08-02 | 64333 | Update dependencies |
| 0.10.12 | 2025-07-26 | 64039 | Update dependencies |
| 0.10.11 | 2025-07-19 | 63538 | Update dependencies |
| 0.10.10 | 2025-07-12 | 63022 | Update dependencies |
| 0.10.9 | 2025-06-28 | 62369 | Update dependencies |
| 0.10.8 | 2025-06-21 | 61985 | Update dependencies |
| 0.10.7 | 2025-06-14 | 59347 | Update dependencies |
| 0.10.6 | 2025-04-26 | 58729 | Update dependencies |
| 0.10.5 | 2025-04-19 | 57648 | Update dependencies |
| 0.10.4 | 2025-04-05 | 57130 | Update dependencies |
| 0.10.3 | 2025-03-29 | 56138 | Update dependencies |
| 0.10.2 | 2025-03-17 | 55799 | Adding the new field discount_quantity to stream coupon |
| 0.10.1 | 2025-03-08 | 51760 | Update dependencies |
| 0.10.0 | 2025-02-20 | 54182 | Promoting release candidate 0.10.0-rc.1 to a main version. |
| 0.10.0-rc.1 | 2025-07-02 | 53220 | Replace custom IncrementalSingleSliceCursor component with low-code semi-incremental DatetimeBasedCursor |
| 0.9.0 | 2025-02-06 | 47243 | Migrate to Manifest-only |
| 0.8.0 | 2025-01-31 | 52685 | Update to latest CDK version |
| 0.7.3 | 2025-01-11 | 49038 | Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64 |
| 0.7.2 | 2024-11-20 | 48510 | Ensure no pagination issues on concurrent syncs |
| 0.7.1 | 2024-11-04 | 48133 | Fix error message pattern to handle Product 1.0 related errors |
| 0.7.0 | 2024-10-30 | 47978 | Upgrade the CDK and startup files to sync incremental streams concurrently |
| 0.6.18 | 2024-10-31 | 47099 | Update dependencies |
| 0.6.17 | 2024-10-28 | 47387 | Update CDK dependencies to yield parent records more frequently |
| 0.6.16 | 2024-10-12 | 46846 | Update dependencies |
| 0.6.15 | 2024-10-05 | 46478 | Update dependencies |
| 0.6.14 | 2024-10-03 | 46343 | Added incremental dependency for substreams with Incremental parent streams |
| 0.6.13 | 2024-10-01 | 46294 | Update CDK version to ^5, increased the maxSecondsBetweenMessages to 6 hours |
| 0.6.12 | 2024-09-28 | 46169 | Update dependencies |
| 0.6.11 | 2024-09-21 | 45805 | Update dependencies |
| 0.6.10 | 2024-09-14 | 45254 | Update dependencies |
| 0.6.9 | 2024-08-31 | 45028 | Update dependencies |
| 0.6.8 | 2024-08-24 | 44662 | Update dependencies |
| 0.6.7 | 2024-08-17 | 44265 | Update dependencies |
| 0.6.6 | 2024-08-10 | 43640 | Update dependencies |
| 0.6.5 | 2024-08-03 | 43081 | Update dependencies |
| 0.6.4 | 2024-07-27 | 42626 | Update dependencies |
| 0.6.3 | 2024-07-20 | 42296 | Update dependencies |
| 0.6.2 | 2024-07-13 | 41691 | Update dependencies |
| 0.6.1 | 2024-07-10 | 41113 | Update dependencies |
| 0.6.0 | 2024-07-10 | 39217 | Adds new stream subscription_with_scheduled_changes |
| 0.5.5 | 2024-07-06 | 40965 | Update dependencies |
| 0.5.4 | 2024-06-25 | 40332 | Update dependencies |
| 0.5.3 | 2024-06-23 | 40074 | Update dependencies |
| 0.5.2 | 2024-06-06 | 39217 | [autopull] Upgrade base image to v1.2.2 |
| 0.5.1 | 2024-04-24 | 36633 | Schema descriptions and CDK 0.80.0 |
| 0.5.0 | 2024-03-28 | 36518 | Updates CDK to ^0, updates IncrementalSingleSliceCursor |
| 0.4.2 | 2024-03-14 | 36037 | Adds fields: coupon_constraints to coupon stream, billing_month to customer stream, and error_detail to transaction stream schemas |
| 0.4.1 | 2024-03-13 | 35509 | Updates CDK version to latest (0.67.1), updates site_migration_detail record filtering |
| 0.4.0 | 2024-02-12 | 34053 | Add missing fields to and cleans up schemas, adds incremental support for gift, site_migration_detail, and unbilled_charge streams |
| 0.3.1 | 2024-02-12 | 35169 | Manage dependencies with Poetry |
| 0.3.0 | 2023-12-26 | 33696 | Add new stream, add fields to existing streams |
| 0.2.6 | 2023-12-19 | 32100 | Add new fields in streams |
| 0.2.5 | 2023-10-19 | 31599 | Base image migration: remove Dockerfile and use the python-connector-base image |
| 0.2.4 | 2023-08-01 | 28905 | Updated the connector to use latest CDK version |
| 0.2.3 | 2023-03-22 | 24370 | Ignore 404 errors for Contact stream |
| 0.2.2 | 2023-02-17 | 21688 | Migrate to CDK beta 0.29; fix schemas |
| 0.2.1 | 2023-02-17 | 23207 | Edited stream schemas to get rid of unnecessary enum |
| 0.2.0 | 2023-01-21 | 21688 | Migrate to YAML; add new streams |
| 0.1.16 | 2022-10-06 | 17661 | Make transaction stream to be consistent with S3 by using type transformer |
| 0.1.15 | 2022-09-28 | 17304 | Migrate to per-stream state |
| 0.1.14 | 2022-09-23 | 17056 | Add “custom fields” to the relevant Chargebee source data streams |
| 0.1.13 | 2022-08-18 | 15743 | Fix transaction exchange_rate field type |
| 0.1.12 | 2022-07-13 | 14672 | Fix transaction sort by |
| 0.1.11 | 2022-03-03 | 10827 | Fix Credit Note stream |
| 0.1.10 | 2022-03-02 | 10795 | Add support for Credit Note stream |
| 0.1.9 | 2022-0224 | 10312 | Add support for Transaction Stream |
| 0.1.8 | 2022-02-22 | 10366 | Fix broken coupon stream + add unit tests |
| 0.1.7 | 2022-02-14 | 10269 | Add support for Coupon stream |
| 0.1.6 | 2022-02-10 | 10143 | Add support for Event stream |
| 0.1.5 | 2021-12-23 | 8434 | Update fields in source-connectors specifications |
| 0.1.4 | 2021-09-27 | 6454 | Fix examples in spec file |
| 0.1.3 | 2021-08-17 | 5421 | Add support for “Product Catalog 2.0” specific streams: Items, Item prices and Attached Items |
| 0.1.2 | 2021-07-30 | 5067 | Prepare connector for publishing |
| 0.1.1 | 2021-07-07 | 4539 | Add entrypoint and bump version for connector |
| 0.1.0 | 2021-06-30 | 3410 | New Source: Chargebee |