REST API — read-only v1

REST API reference

A standard JSON API over HTTPS. Use it to wire ChurnWin's churn data into any AI agent, internal tool, or automation that can make HTTP requests. All endpoints are read-only in v1.

Authentication

Pass your API key as a Bearer token on every request. Keys are created at Settings → Agent Access.

curl https://api.churnwin.com/api/v1/agent/metrics \
  -H "Authorization: Bearer cwk_live_YOUR_KEY_HERE"

Base URL: https://api.churnwin.com/api/v1/agent

OpenAPI spec: https://api.churnwin.com/openapi.json

All endpoints accept an optional business=<id> query parameter to scope results to a specific connected Stripe account. Retrieve account IDs from GET /businesses.

Endpoints

GET/metrics

Top-level churn metrics for a period: churn rate, MRR, retention, and subscriber counts.

Query parameters

periodstringOne of 30d | 90d | 6m | 12m (default: 30d)

businessstringStripe account ID to scope results

Example response

{
  "churn_rate": 4.2,
  "mrr": 45200,
  "retention_rate": 95.8,
  "active_subscribers": 1042,
  "churned_this_period": 44,
  "period": "30d"
}

GET/churn-trend

Daily churn volume over the requested window. Useful for plotting or spotting spikes.

Query parameters

periodstringOne of 30d | 90d | 6m | 12m (default: 30d)

businessstringStripe account ID to scope results

Example response

{
  "data": [
    { "date": "2026-05-23", "churned": 2 },
    { "date": "2026-05-24", "churned": 0 },
    { "date": "2026-05-25", "churned": 3 }
  ]
}

GET/churn-reasons

Aggregated cancellation reason breakdown with counts and percentages.

Query parameters

periodstringOne of 30d | 90d | 6m | 12m (default: 30d)

businessstringStripe account ID to scope results

Example response

{
  "reasons": [
    { "reason": "Too expensive", "count": 18, "pct": 40.9 },
    { "reason": "Missing features", "count": 11, "pct": 25.0 },
    { "reason": "Switching to competitor", "count": 7, "pct": 15.9 }
  ]
}

GET/at-risk

Subscribers ranked by AI risk score with key risk signals. Highest risk first.

Query parameters

limitintegerMax customers to return (default: 25)

min_risknumberFilter to customers above this risk score (0–100)

businessstringStripe account ID to scope results

Example response

{
  "customers": [
    {
      "id": "cus_ABC123",
      "email": "[email protected]",
      "risk_score": 87,
      "mrr": 99,
      "signals": ["No login in 30d", "Opened cancellation page"]
    }
  ]
}

GET/recent-churn

Most recently churned customers, newest first.

Query parameters

limitintegerMax customers to return (default: 25)

businessstringStripe account ID to scope results

Example response

{
  "customers": [
    {
      "id": "cus_XYZ789",
      "email": "[email protected]",
      "churned_at": "2026-06-20T09:14:00Z",
      "mrr_lost": 49,
      "plan": "Starter"
    }
  ]
}

GET/cancellation-feedback

Verbatim survey responses collected from churned customers.

Query parameters

limitintegerMax responses to return (default: 25)

businessstringStripe account ID to scope results

Example response

{
  "feedback": [
    {
      "customer_id": "cus_ABC123",
      "submitted_at": "2026-06-18T14:22:00Z",
      "reason": "Too expensive",
      "comment": "Love the product but our budget was cut."
    }
  ]
}

GET/action-plan

ChurnWin's AI-generated list of prioritised retention actions for your account.

Query parameters

businessstringStripe account ID to scope results

Example response

{
  "actions": [
    {
      "priority": 1,
      "title": "Add a pause-subscription option",
      "rationale": "23% of churned users cited needing a break, not cancellation.",
      "effort": "medium"
    }
  ]
}

GET/feedback-performance

Feedback survey send, open, and response rates over the given period.

Query parameters

businessstringStripe account ID to scope results

Example response

{
  "emails_sent": 88,
  "emails_opened": 52,
  "responses": 37,
  "open_rate": 59.1,
  "response_rate": 42.0
}

GET/customers

Full customer roster filterable by status, searchable by email or name.

Query parameters

pageintegerPage number (default: 1)

per_pageintegerResults per page (default: 25, max: 100)

statusstringFilter: active | churned | at_risk

searchstringEmail or name substring search

businessstringStripe account ID to scope results

Example response

{
  "customers": [
    {
      "id": "cus_ABC123",
      "email": "[email protected]",
      "status": "active",
      "plan": "Growth",
      "mrr": 99,
      "risk_score": 12
    }
  ],
  "total": 1042,
  "page": 1,
  "per_page": 25
}

GET/businesses

All Stripe accounts connected to your ChurnWin workspace.

Example response

{
  "businesses": [
    {
      "id": "biz_001",
      "name": "My SaaS",
      "stripe_account_id": "acct_123",
      "active_subscribers": 1042
    }
  ]
}

Errors

401Missing or invalid API key

403Key exists but lacks permission for this resource

404Resource not found

429Rate limit exceeded — back off and retry

500Internal error — contact [email protected]

Get your API key

Start free Go to Agent Access

Developer overview

The pitch, what data is available, who it's for

MCP setup guide

Connect Claude, Cursor, or Windsurf in 2 min