Best Practices

Recommended setup

Use a read-only API key

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.

Always set a start date

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.

Match entities to your Product Catalog version

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.

Data refresh and scheduling

Sync Subscriptions and Invoices more frequently than catalog data

Subscription statuses and invoice amounts change often. Plans, Items, and Addons rarely change — syncing them daily or weekly is sufficient rather than hourly.

Use separate data flows for billing vs. catalog data

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.

Performance optimization

Avoid syncing Events without a tight date filter

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.

Join in Coupler.io instead of your destination

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.

Common pitfalls

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.

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

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