# 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 %}