API Overview

The ChurnCut API allows you to programmatically integrate retention features into your application.

Just getting started?

Check our Quickstart guide to integrate ChurnCut in minutes with step-by-step instructions.

Base URL

https://api.churncut.com/v1

Authentication

All requests require your API Key in the Authorization header:

Authorization: Bearer your-api-key

Note: Your API Key is different from your Secret Key. The API Key is used for server-to-server requests, while the Secret Key is used to generate HMAC tokens.

Response format

All responses use JSON with the following structure:

json

{
  "success": true,
  "data": { ... }
}

In case of error:

json

{
  "success": false,
  "error": {
    "code": "invalid_token",
    "message": "The HMAC token is invalid or has expired"
  }
}

Rate limiting

1000 requests per minute per API Key.

Response headers include rate limit information:

X-RateLimit-Limit: Total limit
X-RateLimit-Remaining: Remaining requests
X-RateLimit-Reset: Reset timestamp

Endpoints

Method	Endpoint	Description
GET	/customers	List customers with risk status
GET	/customers/:id	Get a specific customer
POST	/cancellation-flows	Start a cancellation flow
GET	/cancellation-flows/:id	Get flow status
GET	/analytics/churn	Churn metrics
GET	/analytics/retention	Retention metrics

SDKs

We offer official SDKs for the most popular languages:

Quick example

javascript

const response = await fetch('https://api.churncut.com/v1/customers', {
  headers: {
    'Authorization': 'Bearer your-api-key',
    'Content-Type': 'application/json'
  }
});

const { data } = await response.json();
console.log(data.customers);

Installation Endpoints