LostChurn Docs

Query recovery metrics, campaign performance, and revenue analytics via the LostChurn REST API.

The Analytics API provides aggregated metrics for recovery performance and campaign effectiveness. Use it to build custom dashboards, generate reports, or feed data into your business intelligence tools.

Endpoints

Method	Path	Description
`GET`	`/v1/analytics/recovery`	Recovery performance metrics
`GET`	`/v1/analytics/campaigns`	Campaign performance metrics

Recovery Analytics

Retrieve aggregated recovery metrics for a specified date range.

GET /v1/analytics/recovery

Query Parameters

Parameter	Type	Default	Description
`start_date`	`string`	30 days ago	Start of date range (ISO 8601 date, e.g., `2025-01-01`)
`end_date`	`string`	today	End of date range (ISO 8601 date)
`group_by`	`string`	`day`	Grouping: `hour`, `day`, `week`, `month`
`currency`	`string`	workspace default	ISO currency code for amount fields
`psp`	`string`	all	Filter by payment processor
`decline_category`	`string`	all	Filter: `soft_retry`, `hard_customer`, `terminal`, `unknown`

Example Request

curl "https://api.lostchurn.com/v1/analytics/recovery?start_date=2025-02-01&end_date=2025-02-28&group_by=week" \
  -H "Authorization: Bearer lc_live_your_api_key"

Example Response

{
  "data": {
    "summary": {
      "total_failures": 312,
      "total_recovered": 168,
      "total_terminal": 22,
      "total_pending": 122,
      "recovery_rate": 0.539,
      "total_failed_amount": 2846700,
      "total_recovered_amount": 1534200,
      "total_terminal_amount": 197800,
      "currency": "usd",
      "avg_time_to_recovery_hours": 52.3
    },
    "by_category": [
      {
        "category": "soft_retry",
        "failures": 198,
        "recovered": 134,
        "recovery_rate": 0.677,
        "recovered_amount": 1156800
      },
      {
        "category": "hard_customer",
        "failures": 92,
        "recovered": 34,
        "recovery_rate": 0.370,
        "recovered_amount": 377400
      },
      {
        "category": "terminal",
        "failures": 22,
        "recovered": 0,
        "recovery_rate": 0.0,
        "recovered_amount": 0
      }
    ],
    "series": [
      {
        "period": "2025-02-03",
        "failures": 78,
        "recovered": 42,
        "recovery_rate": 0.538,
        "failed_amount": 711200,
        "recovered_amount": 383400
      },
      {
        "period": "2025-02-10",
        "failures": 81,
        "recovered": 45,
        "recovery_rate": 0.556,
        "failed_amount": 735900,
        "recovered_amount": 410600
      },
      {
        "period": "2025-02-17",
        "failures": 74,
        "recovered": 39,
        "recovery_rate": 0.527,
        "failed_amount": 672400,
        "recovered_amount": 354800
      },
      {
        "period": "2025-02-24",
        "failures": 79,
        "recovered": 42,
        "recovery_rate": 0.532,
        "failed_amount": 727200,
        "recovered_amount": 385400
      }
    ]
  }
}

Response Fields

Summary Object

Field	Type	Description
`total_failures`	`integer`	Total failed payments in the period
`total_recovered`	`integer`	Total recovered payments
`total_terminal`	`integer`	Total terminal (unrecoverable) payments
`total_pending`	`integer`	Payments still in recovery
`recovery_rate`	`float`	Overall recovery rate (0.0 to 1.0)
`total_failed_amount`	`integer`	Sum of failed payment amounts
`total_recovered_amount`	`integer`	Sum of recovered payment amounts
`total_terminal_amount`	`integer`	Sum of terminal payment amounts
`currency`	`string`	Currency for all amount fields
`avg_time_to_recovery_hours`	`float`	Average hours from failure to recovery

Series Object

Field	Type	Description
`period`	`string`	Period start date (format depends on `group_by`)
`failures`	`integer`	Failures in this period
`recovered`	`integer`	Recoveries in this period
`recovery_rate`	`float`	Recovery rate for this period
`failed_amount`	`integer`	Failed amount in this period
`recovered_amount`	`integer`	Recovered amount in this period

Campaign Analytics

Retrieve performance metrics for your dunning campaigns.

GET /v1/analytics/campaigns

Query Parameters

Parameter	Type	Default	Description
`start_date`	`string`	30 days ago	Start of date range (ISO 8601 date)
`end_date`	`string`	today	End of date range (ISO 8601 date)
`campaign_id`	`string`	all	Filter to a specific campaign
`channel`	`string`	all	Filter by channel: `email`, `sms`, `push`, `whatsapp`
`group_by`	`string`	`day`	Grouping: `day`, `week`, `month`

Example Request

curl "https://api.lostchurn.com/v1/analytics/campaigns?start_date=2025-02-01&end_date=2025-02-28&channel=email" \
  -H "Authorization: Bearer lc_live_your_api_key"

Example Response

{
  "data": {
    "summary": {
      "total_sent": 456,
      "total_delivered": 441,
      "total_opened": 298,
      "total_clicked": 134,
      "total_bounced": 15,
      "total_unsubscribed": 3,
      "delivery_rate": 0.967,
      "open_rate": 0.676,
      "click_rate": 0.304,
      "bounce_rate": 0.033,
      "unsubscribe_rate": 0.007,
      "recovered_from_campaign": 89,
      "campaign_recovery_rate": 0.195
    },
    "by_campaign": [
      {
        "campaign_id": "cmp_abc123",
        "campaign_name": "Soft Decline Recovery",
        "sent": 312,
        "delivered": 302,
        "opened": 214,
        "clicked": 98,
        "recovered": 67,
        "recovery_rate": 0.215
      },
      {
        "campaign_id": "cmp_def456",
        "campaign_name": "Expired Card Outreach",
        "sent": 144,
        "delivered": 139,
        "opened": 84,
        "clicked": 36,
        "recovered": 22,
        "recovery_rate": 0.153
      }
    ],
    "series": [
      {
        "period": "2025-02-03",
        "sent": 112,
        "delivered": 108,
        "opened": 73,
        "clicked": 31,
        "recovered": 21
      },
      {
        "period": "2025-02-10",
        "sent": 118,
        "delivered": 114,
        "opened": 79,
        "clicked": 37,
        "recovered": 25
      },
      {
        "period": "2025-02-17",
        "sent": 108,
        "delivered": 105,
        "opened": 68,
        "clicked": 30,
        "recovered": 19
      },
      {
        "period": "2025-02-24",
        "sent": 118,
        "delivered": 114,
        "opened": 78,
        "clicked": 36,
        "recovered": 24
      }
    ]
  }
}

Response Fields

Campaign Summary Object

Field	Type	Description
`total_sent`	`integer`	Total messages sent
`total_delivered`	`integer`	Messages successfully delivered
`total_opened`	`integer`	Messages opened (email only)
`total_clicked`	`integer`	Messages with at least one click
`total_bounced`	`integer`	Messages that bounced
`total_unsubscribed`	`integer`	Recipients who unsubscribed
`delivery_rate`	`float`	Delivered / sent
`open_rate`	`float`	Opened / delivered
`click_rate`	`float`	Clicked / delivered
`bounce_rate`	`float`	Bounced / sent
`unsubscribe_rate`	`float`	Unsubscribed / delivered
`recovered_from_campaign`	`integer`	Payments recovered via campaign
`campaign_recovery_rate`	`float`	Recovered / sent

Combining Filters

You can combine multiple query parameters to drill down into specific segments:

# Recovery metrics for Stripe soft declines in January, grouped by week
curl "https://api.lostchurn.com/v1/analytics/recovery?\
start_date=2025-01-01&\
end_date=2025-01-31&\
group_by=week&\
psp=stripe&\
decline_category=soft_retry" \
  -H "Authorization: Bearer lc_live_your_api_key"

# Campaign metrics for a specific campaign's email channel
curl "https://api.lostchurn.com/v1/analytics/campaigns?\
start_date=2025-02-01&\
end_date=2025-02-28&\
campaign_id=cmp_abc123&\
channel=email" \
  -H "Authorization: Bearer lc_live_your_api_key"

Next Steps

Payments API -- query individual payment records
Campaigns API -- manage campaigns programmatically
Decline Codes -- complete decline code reference

Analytics API

On this page