API Overview

The LostChurn API is a RESTful JSON API for managing payment recovery programmatically. Use it to query recovery status, trigger retries, manage campaigns, and pull analytics data.

Base URL

All API requests use the following base URL:

https://api.lostchurn.com/v1

All requests must be made over HTTPS. Plain HTTP requests are rejected.

Authentication

Every request must include an API key in the Authorization header using the Bearer token format:

curl https://api.lostchurn.com/v1/payments \
  -H "Authorization: Bearer lc_live_your_api_key"

API keys are created in the LostChurn dashboard under Settings > API Keys. See Authentication for details on key types, scopes, and rotation.

Request Format

• Content-Type: application/json for all request bodies
• Accept: application/json (default)
• Method: Standard HTTP methods (GET, POST, PUT, DELETE)
• Query parameters: Used for filtering and pagination on GET endpoints

Example Request

curl -X POST https://api.lostchurn.com/v1/payments/pay_abc123/retry \
  -H "Authorization: Bearer lc_live_your_api_key" \
  -H "Content-Type: application/json"

Response Format

All responses return JSON with a consistent structure.

Success Response

{
  "data": {
    "id": "pay_abc123",
    "status": "recovered",
    "amount": 4999,
    "currency": "usd"
  }
}

List Response

List endpoints return paginated results with metadata:

{
  "data": [
    { "id": "pay_abc123", "status": "recovered" },
    { "id": "pay_def456", "status": "pending" }
  ],
  "pagination": {
    "total": 142,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

Error Response

{
  "error": {
    "code": "invalid_request",
    "message": "The 'status' parameter must be one of: pending, recovered, terminal.",
    "param": "status",
    "request_id": "req_1234567890"
  }
}

Pagination

List endpoints support cursor-based pagination using the following query parameters:

Rate Limits

API requests are rate-limited per API key:

Rate limit status is included in every response via headers:

When the rate limit is exceeded, the API returns a 429 Too Many Requests response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 32 seconds.",
    "retry_after": 32
  }
}

HTTP Status Codes

Error Codes

Idempotency

For POST requests that create or modify resources, you can include an Idempotency-Key header to ensure the request is processed exactly once:

curl -X POST https://api.lostchurn.com/v1/payments/pay_abc123/retry \
  -H "Authorization: Bearer lc_live_your_api_key" \
  -H "Idempotency-Key: unique-request-id-12345"

Idempotency keys are valid for 24 hours. Repeating a request with the same key within that window returns the original response without re-executing the operation.

Versioning

The API is versioned in the URL path (/v1). Breaking changes result in a new version. Non-breaking changes (new fields, new endpoints) are added to the current version without a version bump.

OpenAPI Specification

A machine-readable OpenAPI 3.1 spec is available for code generation and tooling:

https://app.lostchurn.com/openapi.yaml

Use it with tools like Swagger UI, Redoc, or SDK generators (openapi-typescript-codegen, openapi-python-client).

Stripe App Integration

LostChurn is available on the Stripe App Marketplace. Install the app to see recovery intelligence directly in your Stripe Dashboard -- on payment detail and customer detail pages. The app uses the same REST API documented here.

Next Steps

• Authentication -- API key management and scopes
• Webhooks -- outbound webhook events from LostChurn
• Payments -- query and retry failed payments
• Customers -- customer profiles and GDPR erasure
• Campaigns -- recovery campaign management
• Cancel Sessions -- cancel flow session lifecycle
• Analytics -- recovery and revenue metrics
• Decline Codes -- decline code reference and lookup