Best Practices

Recommended setup

Use both entities together

Add Sessions and Session aggregations as separate sources in the same data flow. Aggregations are fast for dashboards; raw sessions let you drill into individual cases when a metric looks off.

Join with your billing data

Churnkey sessions include a customer ID you can use to join with Stripe, Chargebee, or your CRM. Use Coupler.io's Join transformation to enrich session records with plan history or LTV data.

Send to an AI destination for pattern analysis

Load cancel reasons and session outcomes into ChatGPT, Claude, or Gemini to automatically surface patterns in why customers leave — especially useful when your cancel reason list grows long.

Data refresh and scheduling

Daily refresh is usually enough

Churn prevention sessions don't require real-time sync for most reporting use cases. A daily refresh keeps dashboards current without putting unnecessary load on the API.

Run a successful manual sync first

Before setting a schedule, confirm your data flow completes without errors. This catches API key issues or empty dataset problems before they affect automated runs.

Performance optimization

Use Session aggregations for spreadsheet destinations

If your cancel flow handles high volume, the Sessions entity can return thousands of rows. For Google Sheets or Excel destinations, prefer Session aggregations to keep the file manageable and formulas fast.

Aggregate in Coupler.io before loading

Use Coupler.io's Aggregate transformation on the Sessions entity to group by cancel reason or offer type before loading into your destination. This reduces row count and makes downstream analysis simpler.

Common pitfalls

Don't treat Churnkey's session aggregations as a substitute for reconciled revenue data. These figures reflect MRR at the moment of the session and won't update if a customer's billing situation changes afterward.

Do

• Use the Sessions entity when you need to investigate individual customer outcomes
• Rotate your API key in Churnkey and update it in Coupler.io at the same time to avoid broken syncs
• Combine Churnkey data with billing sources to get a complete view of churn impact

Don't

• Run simultaneous data flows on the same API key — this can trigger rate limit errors
• Rely solely on session aggregations for finance reporting without cross-checking against your billing platform
• Ignore the cancel reason field — it's one of the most actionable dimensions Churnkey provides