Churn Events

Churn events represent customer cancellations and failed payments. Each event triggers AI-powered recovery workflows.

Event Status Lifecycle

Every churn event moves through a defined lifecycle:

new → processing → variants_generated → email_sent → recovered / lost

Status	Description
`new`	Event received, waiting to be processed
`processing`	AI is analyzing the event and customer data
`variants_generated`	9 recovery email variants have been generated
`email_sent`	A recovery email has been sent to the customer
`recovered`	Customer reactivated or payment succeeded
`lost`	Recovery window expired without reactivation

Create a Churn Event

Create a new churn event manually (alternative to webhooks).

POST /projects/:slug/churn-events

Request Body

customer_email

string

required

Customer’s email address.

customer_name

string

Customer’s display name.

event_type

string

required

Type of churn: cancellation or payment_failed.

cancel_reason

string

Free-text reason for cancellation. Drives AI strategy selection.

mrr

integer

Monthly recurring revenue in cents.

currency

string

ISO 4217 currency code. Defaults to usd.

plan_name

string

Subscription plan name.

tenure_days

integer

Days the customer has been subscribed.

Example Request

curl -X POST https://api.windbackai.com/api/v1/projects/my-project/churn-events \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "jane@example.com",
    "customer_name": "Jane Smith",
    "event_type": "cancellation",
    "cancel_reason": "Too expensive for our team",
    "mrr": 4999,
    "currency": "usd",
    "plan_name": "Team Pro",
    "tenure_days": 180
  }'

Example Response

{
  "data": {
    "id": "evt_abc123",
    "project_id": "prj_xyz",
    "customer_email": "jane@example.com",
    "customer_name": "Jane Smith",
    "event_type": "cancellation",
    "cancel_reason": "Too expensive for our team",
    "status": "new",
    "mrr": 4999,
    "currency": "usd",
    "plan_name": "Team Pro",
    "tenure_days": 180,
    "provider": "api",
    "created_at": "2025-12-01T10:00:00Z",
    "updated_at": "2025-12-01T10:00:00Z"
  }
}

List Churn Events

Retrieve a paginated list of churn events for a project.

GET /projects/:slug/churn-events

Query Parameters

page

integer

default:"1"

Page number.

per_page

integer

default:"20"

Items per page (max 100).

status

string

Filter by status: new, processing, variants_generated, email_sent, recovered, lost.

event_type

string

Filter by type: cancellation or payment_failed.

Example Request

curl "https://api.windbackai.com/api/v1/projects/my-project/churn-events?status=new&page=1&per_page=10" \
  -H "X-API-Key: sk_live_abc123..."

Example Response

{
  "data": [
    {
      "id": "evt_abc123",
      "customer_email": "jane@example.com",
      "event_type": "cancellation",
      "status": "new",
      "mrr": 4999,
      "created_at": "2025-12-01T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 10,
    "total": 42
  }
}

Get a Churn Event

Retrieve a single churn event by ID.

GET /projects/:slug/churn-events/:id

Example Request

curl https://api.windbackai.com/api/v1/projects/my-project/churn-events/evt_abc123 \
  -H "X-API-Key: sk_live_abc123..."

Example Response

{
  "data": {
    "id": "evt_abc123",
    "project_id": "prj_xyz",
    "customer_email": "jane@example.com",
    "customer_name": "Jane Smith",
    "event_type": "cancellation",
    "cancel_reason": "Too expensive for our team",
    "status": "variants_generated",
    "mrr": 4999,
    "currency": "usd",
    "plan_name": "Team Pro",
    "tenure_days": 180,
    "provider": "stripe",
    "variants": [
      {
        "id": "var_001",
        "strategy": "value_recap",
        "subject": "Jane, here's what you'll miss",
        "body": "Hi Jane, ...",
        "status": "draft"
      }
    ],
    "created_at": "2025-12-01T10:00:00Z",
    "updated_at": "2025-12-01T10:05:00Z"
  }
}

Mark as Recovered

Mark a churn event as recovered when the customer reactivates.

POST /projects/:slug/churn-events/:id/recovered

Example Request

curl -X POST https://api.windbackai.com/api/v1/projects/my-project/churn-events/evt_abc123/recovered \
  -H "X-API-Key: sk_live_abc123..."

Example Response

{
  "data": {
    "id": "evt_abc123",
    "status": "recovered",
    "recovered_at": "2025-12-05T14:30:00Z"
  }
}

Stripe and Razorpay integrations automatically mark events as recovered when a payment_succeeded or payment.captured event is received.

Update Cancel Reason

Update the cancel reason on an existing churn event. Useful when the reason is collected after the event is created.

PATCH /projects/:slug/churn-events/:id/cancel-reason

Request Body

cancel_reason

string

required

The updated cancel reason.

Example Request

curl -X PATCH https://api.windbackai.com/api/v1/projects/my-project/churn-events/evt_abc123/cancel-reason \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"cancel_reason": "Switching to a competitor with better integrations"}'

Example Response

{
  "data": {
    "id": "evt_abc123",
    "cancel_reason": "Switching to a competitor with better integrations",
    "updated_at": "2025-12-01T11:00:00Z"
  }
}

​Churn Events

​Event Status Lifecycle

​Create a Churn Event

​Request Body

​Example Request

​Example Response

​List Churn Events

​Query Parameters

​Example Request

​Example Response

​Get a Churn Event

​Example Request

​Example Response

​Mark as Recovered

​Example Request

​Example Response

​Update Cancel Reason

​Request Body

​Example Request

​Example Response

Churn Events

Event Status Lifecycle

Create a Churn Event

Request Body

Example Request

Example Response

List Churn Events

Query Parameters

Example Request

Example Response

Get a Churn Event

Example Request

Example Response

Mark as Recovered

Example Request

Example Response

Update Cancel Reason

Request Body

Example Request

Example Response