Chargebee
This page contains the setup guide and reference information for the Chargebee source connector.
Prerequisites
To set up the Chargebee source connector, you will need a valid Chargebee API key and the Product Catalog version of the Chargebee site you are syncing data from.
All Chargebee sites created from May 5, 2021 onward will have Product Catalog 2.0 enabled by default. Sites created prior to this date will use Product Catalog 1.0.
Set up the Chargebee connector in Airbyte
- Log into your Airbyte Cloud account or navigate to the Airbyte Open Source dashboard.
- Click Sources and then click + New source.
- On the Set up the source page, select Chargebee from the Source type dropdown.
- Enter the name for the Chargebee connector.
- For Site, enter the site prefix for your Chargebee instance.
- For Start Date, enter the date in YYYY-MM-DDTHH:mm:ssZ format. The data added on and after this date will be replicated.
- For API Key, enter the Chargebee API key.
- For Product Catalog, enter the Chargebee Product Catalog version.
- 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.
| Stream | Product Catalog 1.0 | Product Catalog 2.0 |
|---|---|---|
| Addons | ✔ | |
| Attached Items | ✔ | |
| Contacts | ✔ | ✔ |
| Coupons | ✔ | ✔ |
| Credit Notes | ✔ | ✔ |
| Customers | ✔ | ✔ |
| Events | ✔ | ✔ |
| Gifts | ✔ | ✔ |
| Hosted Pages | ✔ | ✔ |
| Invoices | ✔ | ✔ |
| Items | ✔ | |
| Item Prices | ✔ | |
| Orders | ✔ | ✔ |
| Payment Sources | ✔ | ✔ |
| Plans | ✔ | |
| Promotional Credits | ✔ | ✔ |
| Quotes | ✔ | ✔ |
| Quote Line Groups | ✔ | ✔ |
| Subscriptions | ✔ | ✔ |
| Transactions | ✔ | ✔ |
| Unbilled Charges | ✔ | ✔ |
| Virtual Bank Accounts | ✔ | ✔ |
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.
Performance considerations
The Chargebee connector should not run into Chargebee API limitations under normal usage. Create an issue if you encounter any rate limit issues that are not automatically retried successfully.
Build instructions
Build your own connector image
This connector is built using our dynamic built process.
The base image used to build it is defined within the metadata.yaml file under the connectorBuildOptions.
The build logic is defined using Dagger here.
It does not rely on a Dockerfile.
If you would like to patch our connector and build your own a simple approach would be:
- Create your own Dockerfile based on the latest version of the connector image.
FROM airbyte/source-chargebee:latest
COPY . ./airbyte/integration_code
RUN pip install ./airbyte/integration_code
# The entrypoint and default env vars are already set in the base image
# ENV AIRBYTE_ENTRYPOINT "python /airbyte/integration_code/main.py"
# ENTRYPOINT ["python", "/airbyte/integration_code/main.py"]
Please use this as an example. This is not optimized.
- Build your image:
docker build -t airbyte/source-chargebee:dev .
# Running the spec command against your patched connector
docker run airbyte/source-chargebee:dev spec
Customizing our build process
When contributing on our connector you might need to customize the build process to add a system dependency or set an env var.
You can customize our build process by adding a build_customization.py module to your connector.
This module should contain a pre_connector_install and post_connector_install async function that will mutate the base image and the connector container respectively.
It will be imported at runtime by our build process and the functions will be called if they exist.
Here is an example of a build_customization.py module:
from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
# Feel free to check the dagger documentation for more information on the Container object and its methods.
# https://dagger-io.readthedocs.io/en/sdk-python-v0.6.4/
from dagger import Container
async def pre_connector_install(base_image_container: Container) -> Container:
return await base_image_container.with_env_variable("MY_PRE_BUILD_ENV_VAR", "my_pre_build_env_var_value")
async def post_connector_install(connector_container: Container) -> Container:
return await connector_container.with_env_variable("MY_POST_BUILD_ENV_VAR", "my_post_build_env_var_value")
Changelog
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 0.2.5 | 2023-10-13 | 31377 | Use our base image and remove Dockerfile |
| 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 |