LostChurn Docs

Query customer records, retrieve customer details, and list a customer's payment history via the LostChurn REST API.

The Customers API provides access to customer records that LostChurn has received through webhook events from your payment processor. Customers are created automatically when LostChurn receives their first failed payment event.

Endpoints

Method	Path	Description
`GET`	`/v1/customers`	List customers
`GET`	`/v1/customers/:id`	Get a customer
`GET`	`/v1/customers/:id/payments`	List a customer's payments
`DELETE`	`/v1/customers/:id`	Delete customer data (GDPR erasure)

List Customers

Retrieve a paginated list of customers, optionally filtered by status or search query.

GET /v1/customers

Query Parameters

Parameter	Type	Default	Description
`query`	`string`	--	Search by name or email
`status`	`string`	all	Filter: `active` (has pending recovery), `recovered` (all payments recovered), `churned` (subscription canceled)
`psp`	`string`	--	Filter by payment processor
`has_failed_payment`	`boolean`	--	Filter to customers with at least one currently failed payment
`created_after`	`string`	--	ISO 8601 datetime
`created_before`	`string`	--	ISO 8601 datetime
`sort`	`string`	`created_at`	Sort field: `created_at`, `name`, `email`, `total_recovered`
`order`	`string`	`desc`	Sort order: `asc`, `desc`
`page`	`integer`	`1`	Page number
`per_page`	`integer`	`20`	Results per page (max: 100)

Example Request

curl "https://api.lostchurn.com/v1/customers?has_failed_payment=true&per_page=10" \
  -H "Authorization: Bearer lc_live_your_api_key"

Example Response

{
  "data": [
    {
      "id": "cus_def456",
      "email": "jane.smith@example.com",
      "name": "Jane Smith",
      "psp": "stripe",
      "psp_customer_id": "cus_stripe_abc123",
      "status": "active",
      "total_payments": 3,
      "failed_payments": 1,
      "recovered_payments": 2,
      "total_recovered_amount": 9998,
      "total_recovered_currency": "usd",
      "created_at": "2024-11-15T10:00:00Z",
      "updated_at": "2025-03-08T14:30:00Z"
    },
    {
      "id": "cus_ghi789",
      "email": "john.doe@example.com",
      "name": "John Doe",
      "psp": "stripe",
      "psp_customer_id": "cus_stripe_def456",
      "status": "active",
      "total_payments": 1,
      "failed_payments": 1,
      "recovered_payments": 0,
      "total_recovered_amount": 0,
      "total_recovered_currency": "usd",
      "created_at": "2025-01-20T08:30:00Z",
      "updated_at": "2025-03-07T09:15:00Z"
    }
  ],
  "pagination": {
    "total": 234,
    "page": 1,
    "per_page": 10,
    "total_pages": 24
  }
}

Get a Customer

Retrieve full details for a single customer, including their current subscription status and recovery summary.

GET /v1/customers/:id

Example Request

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

Example Response

{
  "data": {
    "id": "cus_def456",
    "email": "jane.smith@example.com",
    "name": "Jane Smith",
    "psp": "stripe",
    "psp_customer_id": "cus_stripe_abc123",
    "status": "active",
    "subscriptions": [
      {
        "id": "sub_ghi789",
        "psp_subscription_id": "sub_stripe_xyz",
        "plan": "Pro Monthly",
        "amount": 4999,
        "currency": "usd",
        "status": "active",
        "current_period_end": "2025-04-08T00:00:00Z"
      }
    ],
    "payment_method": {
      "type": "card",
      "brand": "visa",
      "last_four": "4242",
      "exp_month": 12,
      "exp_year": 2026
    },
    "recovery_summary": {
      "total_failures": 3,
      "total_recovered": 2,
      "total_terminal": 0,
      "total_pending": 1,
      "recovery_rate": 0.67,
      "total_recovered_amount": 9998,
      "currency": "usd"
    },
    "created_at": "2024-11-15T10:00:00Z",
    "updated_at": "2025-03-08T14:30:00Z"
  }
}

List Customer Payments

Retrieve all payments (failed, recovered, and terminal) for a specific customer.

GET /v1/customers/:id/payments

Query Parameters

Parameter	Type	Default	Description
`status`	`string`	all	Filter by status: `pending`, `retrying`, `recovered`, `terminal`, `communication_pending`
`sort`	`string`	`created_at`	Sort field
`order`	`string`	`desc`	Sort order
`page`	`integer`	`1`	Page number
`per_page`	`integer`	`20`	Results per page (max: 100)

Example Request

curl "https://api.lostchurn.com/v1/customers/cus_def456/payments?status=recovered" \
  -H "Authorization: Bearer lc_live_your_api_key"

Example Response

{
  "data": [
    {
      "id": "pay_abc123",
      "amount": 4999,
      "currency": "usd",
      "status": "recovered",
      "decline_code": "insufficient_funds",
      "decline_category": "soft_retry",
      "retry_count": 2,
      "created_at": "2025-03-01T14:30:00Z",
      "recovered_at": "2025-03-03T06:12:00Z"
    },
    {
      "id": "pay_xyz789",
      "amount": 4999,
      "currency": "usd",
      "status": "recovered",
      "decline_code": "generic_decline",
      "decline_category": "soft_retry",
      "retry_count": 1,
      "created_at": "2025-02-01T10:00:00Z",
      "recovered_at": "2025-02-02T08:30:00Z"
    }
  ],
  "pagination": {
    "total": 2,
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  }
}

Delete Customer Data

Permanently delete all personal data for a customer. This supports GDPR right-to-erasure requests. Transaction records are anonymized (customer identifiers removed) but retained for financial reporting. See GDPR & Data Privacy for details.

DELETE /v1/customers/:id

Example Request

curl -X DELETE https://api.lostchurn.com/v1/customers/cus_def456 \
  -H "Authorization: Bearer lc_live_your_api_key"

Example Response

{
  "data": {
    "id": "cus_def456",
    "deleted": true,
    "anonymized_records": 3
  }
}

This action is irreversible. The API key must have write or admin scope.

Customer Object

Field	Type	Description
`id`	`string`	LostChurn customer ID
`email`	`string`	Customer email address
`name`	`string`	Customer display name
`psp`	`string`	Payment processor
`psp_customer_id`	`string`	Customer ID in your PSP
`status`	`string`	`active`, `recovered`, `churned`
`total_payments`	`integer`	Total failed payments recorded
`failed_payments`	`integer`	Currently failed (pending) payments
`recovered_payments`	`integer`	Successfully recovered payments
`total_recovered_amount`	`integer`	Total recovered in smallest currency unit
`total_recovered_currency`	`string`	Currency of recovered amount
`subscriptions`	`array`	Active subscriptions (on detail endpoint)
`payment_method`	`object`	Current payment method details (on detail endpoint)
`recovery_summary`	`object`	Recovery statistics (on detail endpoint)
`created_at`	`string`	First seen timestamp
`updated_at`	`string`	Last update timestamp

Next Steps

Payments API -- query and retry failed payments
Campaigns API -- manage dunning campaigns
Analytics API -- recovery and campaign metrics

Customers API

On this page