Team

Cancel Flows

Quick Start Guide

Further Configuration

Custom Styling

Multi-Language Support

Email-Verified Cancel Flow

Pause Wall

Failed Payment Recovery

Data Integrations

Billing Providers

Payment Provider Overview

Support

Data API

Reach out to us at [email protected] to speak about getting API access for your company.

Authorization

Authorization is done with your data API key, which is distinct from the cancel flow API key. Once you have your key, you will pass it along with your application ID as request headers. You can find your API keys and App ID on Churnkey | Settings | Account.

HEADERS
{
  "x-ck-api-key": "data_yourkey...",
  "x-ck-app": "appIdHere",
  "content-type": "application/json"
}

List Sessions

This endpoint will return an array of sessions, optionally filtered. This is limited to returning 10,000 sessions per request.

GET "https://api.churnkey.co/v1/data/sessions"

HEADERS
{
  "x-ck-api-key": "data_yourkey...",
  "x-ck-app": "appIdHere",
  "content-type": "application/json"
}

Optionally, you can include the following filters as query params.

Filter	Example	Description
`startDate`	`2023-01-01`	Sessions that occurred after this date according to `new Date(startDate)`
`endDate`	`2024-01-01`	Sessions that occurred before this date according to `new Date(endDate)`
`customerId`	`cus_123789`	The exact customer ID.
`trial`	`true`	If customer was on a subscription trial at the time of session
`billingInterval`	`MONTH`	Customer subscription billing interval. Possible values are `WEEK`, `MONTH`, `YEAR`
`planId`	`billing_plan_id`	The exact billing plan ID.
`aborted`	`true`	If session was abandoned before completion
`canceled`	`true`	If customer canceled their subscription
`offerType`	`PAUSE`	Type of accepted offer if accepted. Possible values are `PAUSE`, `DISCOUNT`, `CONTACT`, `PLAN_CHANGE`, `REDIRECT`, `TRIAL_EXTENSION`
`saveType`	`ABANDON`	Type of accepted offer if accepted, or `ABANDON` if session was abandoned before completion. Possible values are `PAUSE`, `DISCOUNT`, `CONTACT`, `PLAN_CHANGE`, `REDIRECT`, `TRIAL_EXTENSION`, `ABANDON`
`couponId`	`coupon_abc12`	The ID of the coupon if the customer accepted a discount offer.
`pauseDuration`	`2`	How long the customer paused their subscription for if they accepted a pause offer.
`blueprintId`	`id-goes-here-7890`	ID of the version of the published cancel flow.
`abtest`	`guid-goes-here-7890`	ID of an ongoing or completed AB test.
`bounced`	`true`	By default, `bounced` is set to `false` and bounced sessions are excluded (see note below).

💡

A session gets marked as bounced if another more relevant session takes place within 24 hours of that initial session. For instance, if a customer pauses and then decides to cancel within 24 hours, that first session with the pause offer accepted will be marked as bounced.

Examples of List Session Requests

Returns sessions for the month of May 2023

GET "https://api.churnkey.co/v1/data/sessions?startDate=2023-05-01&endDate=2023-06-01"

Returns sessions where monthly customers accepted a discount

GET "https://api.churnkey.co/v1/data/sessions?offerType=DISCOUNT&billingInterval=MONTH"

Response Data Format

[
		{
        "_id": "63fffe3...",
        "org": "5fc5c5483b...",
        "blueprintId": "63ce7c2152...",
        "segmentId": "63ce7be8d0d...",
        "abtest": "63ce7c35e...",
        "customer": {
            "id": "cus_123",
            "email": "[email protected]",
            "created": "2022-12-24T03:24:59.000Z",
            "subscriptionId": "sub_1M...",
            "subscriptionStart": "2022-12-24T03:25:09.000Z",
            "subscriptionPeriodStart": "2023-02-24T03:25:09.000Z",
            "subscriptionPeriodEnd": "2023-03-24T03:25:09.000Z",
            "currency": "usd",
            "planId": "creator_monthly",
            "planPrice": 1299,
            "itemQuantity": 1,
            "billingInterval": "MONTH",
            "billingIntervalCount": 1
        },
        "acceptedOffer": {
            "guid": "dbaea0be-a20f-...",
            "offerType": "PAUSE",
            "pauseInterval": "MONTH",
            "pauseDuration": 3
        },
        "provider": "STRIPE",
        "aborted": false,
        "canceled": false,
        "surveyId": "929f...",
        "surveyChoiceId": "e32f1...",
        "surveyChoiceValue": "Missing Features",
        "feedback": "I want to be able to add animations to the video",
        "discountCooldownApplied": false,
        "customActionHandler": null,
        "presentedOffers": [
            {
                "guid": "1c85...",
                "accepted": false,
                "presentedAt": "2023-03-02T01:38:28.039Z",
                "declinedAt": "2023-03-02T01:38:35.462Z",
                "surveyOffer": false,
                "offerType": "PAUSE",
                "pauseConfig": {
                    "maxPauseLength": 2,
                    "pauseInterval": "MONTH"
                }
            },
            {
                "guid": "dbae...",
                "accepted": true,
                "presentedAt": "2023-03-02T01:38:41.931Z",
                "acceptedAt": "2023-03-02T01:38:55.903Z",
                "surveyOffer": true,
                "offerType": "DISCOUNT",
                "discountConfig": {
                    "couponId": "coup_id",
                }
            }
        ],
        "mode": "LIVE",
        "createdAt": "2023-03-02T01:38:56.005Z",
        "updatedAt": "2023-03-02T01:38:56.684Z",
        "recordingEndTime": "2023-03-02T01:38:56.032Z",
        "recordingStartTime": "2023-03-02T01:38:27.276Z"
    }
]

Aggregated Session Data

This endpoint will return an array of grouped session counts. Like the above session listing endpoint, this data can be filtered. Additionally, it can be aggregated by nested groups.

GET "https://api.churnkey.co/v1/data/session-aggregation"

HEADERS
{
  "x-ck-api-key": "data_yourkey...",
  "x-ck-app": "appIdHere",
  "content-type": "application/json"
}

In addition to the above filters, you can group the session aggregation by adding any of the following to the breakdown query param, separating each with a - e.g. ?breakdown=month-saveType

Filter	Description
`month`	Which month the session occurred in.
`trial`	If customer was on a subscription trial at the time of session
`billingInterval`	Customer subscription billing interval. Possible values are `WEEK`, `MONTH`, `YEAR`
`planId`	The exact billing plan ID.
`aborted`	If session was abandoned before completion
`canceled`	If customer canceled their subscription
`offerType`	Type of accepted offer if accepted. Possible values are `PAUSE`, `DISCOUNT`, `CONTACT`, `PLAN_CHANGE`, `REDIRECT`, `TRIAL_EXTENSION`
`saveType`	Type of accepted offer if accepted, or `ABANDON` if session was abandoned before completion. Possible values are `PAUSE`, `DISCOUNT`, `CONTACT`, `PLAN_CHANGE`, `REDIRECT`, `TRIAL_EXTENSION`, `ABANDON`
`couponId`	The ID of the coupon if the customer accepted a discount offer.
`pauseDuration`	How long the customer paused their subscription for if they accepted a pause offer.
`blueprintId`	ID of the version of the published cancel flow.
`abtest`	ID of an ongoing or completed AB test.

Examples of Aggregate Session Requests

A month-by-month breakdown of the different types of offers accepted since the start of 2023

GET "https://api.churnkey.co/v1/data/session-aggregation?startDate=2023-01-01&breakdown=month-offerType"

A month-by-month breakdown of the survey responses for monthly vs annual customers

GET "https://api.churnkey.co/v1/data/session-aggregation?startDate=2023-01-01&breakdown=month-surveyResponse-billingInterval"

Response Data Format

[
		{
        "count": 70,
        "month": "2023-02",
        "surveyResponse": "Doesn't Fit My Budget",
        "billingInterval": "MONTH"
    },
    {
        "count": 4,
        "month": "2023-03",
        "surveyResponse": "Missing Features",
        "billingInterval": "MONTH"
    },
    {
        "count": 4,
        "month": "2023-01",
        "surveyResponse": "Technical Issues",
        "billingInterval": "MONTH"
    },
    {
        "count": 12,
        "month": "2023-01",
        "surveyResponse": "Stopped Creating",
        "billingInterval": "YEAR"
    },
    {
        "count": 5,
        "month": "2023-01",
        "surveyResponse": "Missing Features",
        "billingInterval": "MONTH"
    },
		...
]

GDPR User Data Access

For data service requests for access

POST "https://api.churnkey.co/v1/data/dsr/access"

BODY
{
  "email": "[email protected]"
}

HEADERS
{
  "x-ck-api-key": "data_yourkey...",
  "x-ck-app": "appIdHere",
  "content-type": "application/json"
}

Response Data Format

{
    "customer": {
        "email": "[email protected]"
    },
    "counts": {
        "events": 5,
        "sessions": 5,
        "campaigns": 5,
        "invoices": 10,
        "failedPayments": 5,
        "subscriptions": 5,
        "charges": 5,
        "emails": 0 
    },
    "profile": {
        "events": [...],
        "sessions": [...]
        "invoices": [...],
        "campaigns": [...],
        "failedPayments": [...],
        "subscriptions": [...],
        "charges": [...],
        "emails": [...]
    }
}

GDPR User Data Delete Request

For data service requests for access

POST "https://api.churnkey.co/v1/data/dsr/delete"

BODY
{
  "email": "[email protected]"
}

HEADERS
{
  "x-ck-api-key": "data_yourkey...",
  "x-ck-app": "appIdHere",
  "content-type": "application/json"
}

Successful Response Data Format

{
    "customer": {
        "email": "[email protected]"
    },
    "deleted": true,
    "deletedCounts": {
        "events": 0,
        "sessions": 0,
        "campaigns": 0,
        "invoices": 0,
        "failedPayments": 0,
        "subscriptions": 0,
        "charges": 0,
        "emails": 0
    },
    "counts": {
        "events": 0,
        "sessions": 0,
        "campaigns": 0,
        "invoices": 0,
        "failedPayments": 0,
        "subscriptions": 0,
        "charges": 0,
        "emails": 0
    }
}

Rejected Response Data Format

{
    "customer": {
        "email": "[email protected]"
    },
    "deleted": false,
    "reasonForRejection": "Profile exceeds limit for API deletion. Please contact [email protected].",
    "counts": {
        "events": 50000,
        "sessions": 0,
        "campaigns": 0,
        "invoices": 0,
        "failedPayments": 0,
        "subscriptions": 0,
        "charges": 0,
        "emails": 0
    }
}

On this page