> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/ecommerce/chargebee/best-practices.md).

# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Use a read-only API key</strong></td><td>Create a dedicated read-only API key in Chargebee for Coupler.io. This limits exposure if credentials are ever compromised and keeps your integration permission-scoped.</td></tr><tr><td><strong>Always set a start date</strong></td><td>Chargebee accounts can accumulate years of data. Setting a start date prevents unnecessarily large first-run syncs and avoids hitting rate limits on high-volume entities like Events and Transactions.</td></tr><tr><td><strong>Match entities to your Product Catalog version</strong></td><td>If you're on Chargebee Product Catalog v2, use Items, Item prices, and Item families. Avoid mixing v1 (Plans, Addons) and v2 entities in the same analysis — the schemas differ.</td></tr></tbody></table>

## Data refresh and scheduling

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Sync Subscriptions and Invoices more frequently than catalog data</strong></td><td>Subscription statuses and invoice amounts change often. Plans, Items, and Addons rarely change — syncing them daily or weekly is sufficient rather than hourly.</td></tr><tr><td><strong>Use separate data flows for billing vs. catalog data</strong></td><td>Group transactional entities (Subscriptions, Invoices, Transactions) in one data flow and catalog entities (Plans, Items, Coupons) in another. This lets you set different refresh cadences for each group.</td></tr></tbody></table>

## Performance optimization

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Avoid syncing Events without a tight date filter</strong></td><td>The Events entity logs every action in Chargebee and can be very large. Only pull Events if you specifically need an audit trail, and always use a start date to bound the query.</td></tr><tr><td><strong>Join in Coupler.io instead of your destination</strong></td><td>Use Coupler.io's Join transformation to combine Subscriptions + Customers or Invoices + Credit notes before they land in your destination. This keeps your spreadsheet or BI tool cleaner and avoids manual VLOOKUP work.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
Dividing monetary fields by 100 is easy to forget. Chargebee stores all amounts in cents — if you're building revenue dashboards, apply the conversion at the destination or transformation layer, not ad hoc in individual charts.
{% endhint %}

{% columns %}
{% column %}
**Do**

* Set a start date on every data flow, especially for Events and Transactions
* Use the Join transformation to combine Subscriptions with Customer or Plan data
* Verify your API key permissions cover all entities you're trying to sync
* Use Product Catalog v2 entities (Items, Item prices) if your account has migrated
  {% endcolumn %}

{% column %}
**Don't**

* Sync the Events entity without a date filter — it will be slow and oversized
* Mix Product Catalog v1 and v2 entities in the same report
* Forget to convert Unix timestamps and cent-based amounts before building dashboards
* Use your Chargebee admin API key — create a scoped read-only key instead
  {% endcolumn %}
  {% endcolumns %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coupler.io/sources/category/ecommerce/chargebee/best-practices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.