LostChurn Docs

This guide gets you from zero to your first API call in under 5 minutes. You'll authenticate, check the API status, list payments, trigger a retry, and pull recovery analytics.

Prerequisites

Before you start, you'll need:

A LostChurn account (sign up here)
An API key from your dashboard (Settings > API Keys)
A connected payment processor (see Quick Setup)

Authentication

All API requests require a Bearer token in the Authorization header. API keys use the lc_live_ prefix for production and lc_test_ for sandbox.

Authorization: Bearer lc_live_sk_abc123...

Keep your API keys secret. Never expose them in client-side code, public repositories, or browser requests. Rotate keys immediately if compromised via Settings > API Keys > Rotate.

Check API Status

Verify your credentials and confirm the API is reachable:

curl -X GET https://app.lostchurn.com/api/v1/status \
  -H "Authorization: Bearer lc_live_sk_abc123"

Response:

{
  "status": "ok",
  "version": "1.0.0",
  "merchant_id": "merch_abc123",
  "environment": "live"
}

List Payments

Retrieve failed payments that LostChurn is tracking. Results are paginated with a default page size of 25.

cURL

curl -X GET "https://app.lostchurn.com/api/v1/payments?status=failed&limit=10" \
  -H "Authorization: Bearer lc_live_sk_abc123"

Node.js

const response = await fetch(
  "https://app.lostchurn.com/api/v1/payments?status=failed&limit=10",
  {
    headers: {
      Authorization: "Bearer lc_live_sk_abc123",
    },
  }
);

const { data, pagination } = await response.json();
console.log(`Found ${pagination.total} failed payments`);

Python

import requests

response = requests.get(
    "https://app.lostchurn.com/api/v1/payments",
    params={"status": "failed", "limit": 10},
    headers={"Authorization": "Bearer lc_live_sk_abc123"},
)

data = response.json()
print(f"Found {data['pagination']['total']} failed payments")

Response:

{
  "data": [
    {
      "id": "pay_abc123",
      "amount": 4999,
      "currency": "usd",
      "status": "failed",
      "decline_code": "insufficient_funds",
      "customer_id": "cus_xyz789",
      "created_at": "2026-03-15T10:30:00Z",
      "retry_count": 2,
      "next_retry_at": "2026-03-16T14:00:00Z"
    }
  ],
  "pagination": {
    "total": 47,
    "page": 1,
    "limit": 10,
    "has_more": true
  }
}

Trigger a Retry

Manually trigger a payment retry for a specific failed payment:

curl -X POST https://app.lostchurn.com/api/v1/payments/pay_abc123/retry \
  -H "Authorization: Bearer lc_live_sk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"reason": "manual_retry"}'

Response:

{
  "id": "retry_def456",
  "payment_id": "pay_abc123",
  "status": "scheduled",
  "scheduled_at": "2026-03-15T11:00:00Z",
  "reason": "manual_retry"
}

LostChurn's ML engine determines the optimal retry time. If you trigger a manual retry, it will still be scheduled at the next predicted-best window unless you pass "immediate": true.

Get Recovery Analytics

Pull aggregate recovery performance metrics:

curl -X GET "https://app.lostchurn.com/api/v1/analytics/recovery?period=30d" \
  -H "Authorization: Bearer lc_live_sk_abc123"

Response:

{
  "period": "30d",
  "total_failed": 312,
  "total_recovered": 247,
  "recovery_rate": 0.792,
  "revenue_recovered": 156430,
  "currency": "usd",
  "avg_recovery_time_hours": 18.3
}

Error Handling

The API uses standard HTTP status codes. Here are the most common errors:

Status Code	Meaning	What to Do
401 Unauthorized	Missing or invalid API key	Check your `Authorization` header and key prefix (`lc_live_` vs `lc_test_`)
403 Forbidden	Key lacks required permissions	Verify the key's scopes in Settings > API Keys
404 Not Found	Resource doesn't exist	Check the ID in your request path
429 Too Many Requests	Rate limit exceeded	Back off and retry. Limits: 100 req/min (Engine), 500 req/min (Recovery), 1,000 req/min (Command)
500 Internal Error	Server-side issue	Retry with exponential backoff. Contact support if persistent

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1710502800

Next Steps

Set up Webhook Events to receive real-time recovery notifications
Explore the Campaigns API to automate customer outreach
Try Sandbox Mode to test your integration with sample data
Review Key Concepts for a deeper understanding of recovery workflows

API Quickstart

Prerequisites

Authentication

Check API Status

List Payments

cURL

Node.js

Python

Trigger a Retry

Get Recovery Analytics

Error Handling

Next Steps

On this page