> 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.md).

# Churnkey

Connect Churnkey to Google Sheets, BigQuery, or AI tools via Coupler.io to analyze churn prevention sessions and retention metrics.

Churnkey is a churn prevention platform that helps subscription businesses retain customers through personalized cancel flows, pause offers, and win-back campaigns. It tracks every customer interaction during the cancellation journey so you can understand why people leave — and what keeps them.

Connecting Churnkey to Coupler.io lets you move that retention data into the tools where you actually do analysis.

**Why connect Churnkey to Coupler.io?**

* Pull raw session data and aggregated metrics into Google Sheets, Excel, BigQuery, or Looker Studio without writing any code
* Send churn signals to AI tools like ChatGPT, Claude, or Gemini for automated retention analysis and recommendations
* Combine Churnkey data with CRM or billing sources using Join or Append transformations for a fuller picture of customer health
* Schedule automatic refreshes so your dashboards and reports always reflect the latest retention activity

**Prerequisites**

* A Churnkey account with at least one active cancel flow
* Your Churnkey API key (found in your Churnkey account settings under API/Developer options)

## Quick start

{% hint style="success" %}
Start with the **Session aggregations** entity if you want a high-level view of retention performance. Switch to **Sessions** when you need row-level detail on individual customer interactions.
{% endhint %}

{% stepper %}
{% step %}
**Create a new data flow in Coupler.io.** Log in to Coupler.io, click **Add data flow**, and select **Churnkey** as your source.
{% endstep %}

{% step %}
**Enter your Churnkey API key.** In the source settings, paste your API key into the designated field. You can find this key in Churnkey under your account or developer settings.
{% endstep %}

{% step %}
**Select an entity.** Choose either **Sessions** for individual interaction records or **Session aggregations** for summarized metrics. You can add more entities to the same data flow later.
{% endstep %}

{% step %}
**Choose a destination.** Pick where you want your data to land — Google Sheets, BigQuery, Excel, Looker Studio, or an AI destination like ChatGPT or Claude.
{% endstep %}

{% step %}
**Run the data flow.** Click **Run** to execute a manual sync. Once it completes successfully, your Churnkey data will appear in your chosen destination.
{% endstep %}
{% endstepper %}

## Available entities

| Entity               | Description                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------ |
| Sessions             | Individual churn prevention session records including engagement data, timing, and interaction details |
| Session aggregations | Summarized metrics rolled up across multiple sessions for trend and performance analysis               |

## Churnkey data overview

Churnkey gives you two main data entities in Coupler.io: raw session records and pre-aggregated session summaries. Together they cover the full spectrum from granular interaction logs to rolled-up retention metrics.

## Entities

| Entity               | What it contains                                                                                              | Best for                                                      |
| -------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Sessions             | One row per churn prevention session — customer ID, session outcome, timing, offers shown, engagement signals | Cohort analysis, individual customer review, funnel debugging |
| Session aggregations | Rolled-up counts and rates across sessions — saves, cancellations, deflection rates by time period or segment | Dashboards, KPI tracking, trend reporting                     |

## Sessions data

#### Session fields

| Field            | Type      | Description                                            |
| ---------------- | --------- | ------------------------------------------------------ |
| Session ID       | String    | Unique identifier for the session                      |
| Customer ID      | String    | Identifier linking back to your customer record        |
| Created at       | Timestamp | When the session was initiated                         |
| Outcome          | String    | Result of the session (e.g., saved, cancelled, paused) |
| Offer shown      | String    | Which retention offer was presented                    |
| Offer accepted   | Boolean   | Whether the customer accepted the offer                |
| Session duration | Number    | Time spent in the cancel flow (seconds)                |
| Cancel reason    | String    | Reason selected or submitted by the customer           |
| Revenue at risk  | Number    | MRR associated with the customer at session time       |

#### Session metadata

| Field            | Type   | Description                           |
| ---------------- | ------ | ------------------------------------- |
| Plan name        | String | Subscription plan the customer was on |
| Billing interval | String | Monthly, annual, etc.                 |
| Country          | String | Customer's billing country            |
| Source           | String | How the session was triggered         |

## Session aggregations data

#### Aggregation metrics

| Field           | Type   | Description                                            |
| --------------- | ------ | ------------------------------------------------------ |
| Total sessions  | Number | Count of all sessions in the period                    |
| Saves           | Number | Sessions that resulted in a retained customer          |
| Cancellations   | Number | Sessions that ended in cancellation                    |
| Save rate       | Number | Percentage of sessions resulting in a save             |
| Revenue saved   | Number | MRR recovered through successful saves                 |
| Deflection rate | Number | Rate at which customers were deflected from cancelling |

#### Aggregation dimensions

| Field         | Type   | Description                           |
| ------------- | ------ | ------------------------------------- |
| Period        | Date   | Time bucket for the aggregation       |
| Plan name     | String | Grouped by subscription plan          |
| Cancel reason | String | Grouped by stated cancellation reason |
| Offer type    | String | Grouped by the offer presented        |

## Common metric combinations

* **Save rate by cancel reason** — identify which objections are hardest to overcome
* **Revenue saved by plan** — prioritize retention efforts on high-value segments
* **Session volume vs. save rate over time** — spot whether your cancel flow performance is improving
* **Offer acceptance rate by offer type** — determine which offers actually work

## Use cases by role

{% tabs %}
{% tab title="Retention teams" %}

* Track weekly save rates and revenue recovered without manually exporting from Churnkey
* Compare offer performance to refine which discounts or pauses to show first
* Build a Looker Studio dashboard that updates automatically each day
  {% endtab %}

{% tab title="Finance teams" %}

* Pull revenue-at-risk and revenue-saved data into spreadsheets for MRR reconciliation
* Join Churnkey session data with billing records in BigQuery for a complete churn impact report
* Use Aggregate transformation in Coupler.io to roll up saves by billing period
  {% endtab %}

{% tab title="Product teams" %}

* Analyze cancel reasons by plan to inform roadmap prioritization
* Send session outcome data to ChatGPT or Claude for automated pattern detection and recommendations
* Append data from multiple Churnkey environments (test and production) to compare behavior
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* Session aggregations are pre-computed by Churnkey — they are not the same as applying Coupler.io's Aggregate transformation to the Sessions entity, though you can use both approaches
* The Sessions entity can grow large for high-traffic cancel flows; consider using Coupler.io's Aggregate transformation to summarize before loading into spreadsheet destinations
* Revenue fields reflect MRR at the time of the session and are not updated retroactively if a customer's plan changes later
* Cancel reasons depend on what options you've configured in your Churnkey cancel flow — custom reasons will appear as-is

## Churnkey common issues

### Connection issues

<details>

<summary>My API key is rejected during setup</summary>

Double-check that you copied the full API key from Churnkey with no leading or trailing spaces. Churnkey API keys are typically found under account or developer settings — make sure you're using a key with read access, not a restricted or webhook-only key. If you recently rotated your key, the old one will no longer work and you'll need to paste the new one into your Coupler.io data flow settings.

</details>

<details>

<summary>The data flow connects but returns no data</summary>

This usually means the API key is valid but the associated account has no sessions recorded yet, or the key belongs to a sandbox/test environment with no activity. Confirm that your Churnkey account has at least one completed session. If you're using a test environment key, switch to your production key.

</details>

### Missing data

<details>

<summary>Some sessions are missing from the output</summary>

Churnkey only surfaces completed sessions through its API — sessions that were abandoned mid-flow or are still in progress may not appear. If you're seeing a gap for a specific date range, check whether those sessions were completed in Churnkey's own dashboard before assuming the data is missing from Coupler.io.

</details>

<details>

<summary>Session aggregations show different numbers than the Churnkey dashboard</summary>

Churnkey's dashboard may apply its own default filters (date range, plan type, etc.) that don't match what Coupler.io pulls. The API returns aggregations without those UI-level filters applied. Compare the raw totals by pulling the Sessions entity and aggregating manually to verify which view is correct for your use case.

</details>

### Permission errors

<details>

<summary>I get a 403 or "unauthorized" error</summary>

This means the API key doesn't have sufficient permissions. Some Churnkey plans restrict API access to certain tiers. Verify that your account plan includes API access and that the key you're using hasn't been revoked. Contact Churnkey support if you believe API access should be enabled on your plan.

</details>

### Data discrepancies

<details>

<summary>Revenue saved figures don't match my billing system</summary>

Churnkey records the MRR at the time the session occurs. If a customer subsequently upgraded, downgraded, or churned anyway after a grace period, Churnkey's revenue figure won't reflect that change. For reconciled revenue data, join Churnkey session records with your billing source (e.g., Stripe or Chargebee) in Coupler.io using the Join transformation.

</details>

### Rate limits

<details>

<summary>My data flow fails with a rate limit error</summary>

Churnkey's API has rate limits that apply per key. If you're running multiple data flows using the same API key simultaneously, you may hit these limits. Try staggering your data flow schedules or reducing the refresh frequency. If the problem persists, reach out to Churnkey to ask about rate limit thresholds for your plan.

</details>

## Churnkey FAQ

<details>

<summary>What's the difference between Sessions and Session aggregations?</summary>

Sessions gives you one row per individual churn prevention interaction — every time a customer went through your cancel flow. Session aggregations are pre-computed summaries that roll up counts, save rates, and revenue figures across those sessions. Use Sessions for detailed analysis or customer-level investigation; use Session aggregations for dashboards and trend reporting.

</details>

<details>

<summary>Can I pull data from multiple Churnkey accounts into one destination?</summary>

Yes. Add each Churnkey account as a separate source in your data flow using its own API key, then use Coupler.io's Append transformation to combine the data into a single table. This is useful if you manage separate Churnkey workspaces for different products or brands.

</details>

<details>

<summary>How far back does Churnkey's API return data?</summary>

Churnkey's API returns historical session data from when your account was created. There's no hard cutoff documented for the API, but very large historical pulls may be slower. If you're doing a first-time sync of a long-running account, expect the initial run to take longer than subsequent refreshes.

</details>

<details>

<summary>Can I use Churnkey data with AI tools through Coupler.io?</summary>

Yes. Coupler.io supports AI destinations including ChatGPT, Claude, Gemini, Cursor, Perplexity, and OpenClaw. You can route Churnkey session data — especially cancel reasons and outcomes — directly to these tools for automated analysis, summaries, or retention strategy recommendations.

</details>

<details>

<summary>Why do my session counts in Coupler.io differ from the Churnkey dashboard?</summary>

The Churnkey dashboard often applies default date filters and may exclude incomplete or test sessions. The API used by Coupler.io may return a broader dataset. Check what filters are active in your Churnkey dashboard and compare against the raw session data to identify the difference. See the [Common Issues](#churnkey-common-issues) page for more detail.

</details>

<details>

<summary>Is Churnkey data available in real time?</summary>

Coupler.io syncs on demand or on a schedule — it's not a streaming connection. For most retention reporting use cases, a daily or hourly scheduled refresh is more than sufficient. You can always trigger a manual run if you need the latest data immediately.

</details>

<details>

<summary>Where do I find my Churnkey API key?</summary>

Log in to Churnkey and navigate to your account or developer settings. The API key is usually listed there under an "API" or "Integrations" section. Copy the full key and paste it into the source settings when setting up your Coupler.io data flow.

</details>

{% hint style="info" %}
For a full list of available fields and metric definitions, see the [Data Overview](#churnkey-data-overview) page. For connection errors or missing data, visit [Common Issues](#churnkey-common-issues).
{% endhint %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/sales/churnkey.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.