Data Integrations
Data API
Access your data through our 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_your_key...",
"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_your_key...",
"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: 'dba-ea0be-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: 'dba...',
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_your_key...",
"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_your_key...",
"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_your_key...",
"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
}
}