> 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/sales/churnkey/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 both entities together</strong></td><td>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.</td></tr><tr><td><strong>Join with your billing data</strong></td><td>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.</td></tr><tr><td><strong>Send to an AI destination for pattern analysis</strong></td><td>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.</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>Daily refresh is usually enough</strong></td><td>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.</td></tr><tr><td><strong>Run a successful manual sync first</strong></td><td>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.</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>Use Session aggregations for spreadsheet destinations</strong></td><td>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.</td></tr><tr><td><strong>Aggregate in Coupler.io before loading</strong></td><td>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.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
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.
{% endhint %}

{% columns %}
{% column %}

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

{% column %}

### 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
  {% 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/sales/churnkey/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.