Failed payments
The /reports/cashflow-failed-payments endpoint returns a timeline of failed payment metrics, including amounts failed, recovered, still unpaid, and churned, along with recovery rates.
GET /reports/cashflow-failed-payments
Query parameters
| Parameter | Type | Description |
|---|
date | string | Date range. Format: YYYYMMDD-YYYYMMDD. Defaults to last 365 days. |
interval | string | Aggregation interval: day, week, month, quarter, year. Defaults to month. |
baseCurrency | string | Target currency for conversion. Defaults to account base currency. |
region | string | Filter by region or country codes (space-separated). |
currency | string | Filter by currency codes (space-separated). |
plan | string | Filter by plan group IDs (space-separated). |
industry | string | Filter by industry (space-separated). |
data_source | string | Filter by data source ID (space-separated). |
Example response
200 OK
{
"currency": "usd",
"result": [
{
"date": "2025-01-01",
"failed_amount": 15000,
"recovered": 10000,
"still_unpaid": 3000,
"churned": 2000,
"failed_invoices": 12,
"recovered_customers": 8,
"still_unpaid_customers": 2,
"churned_customers": 2,
"affected_customers": 10,
"total_invoices": 250,
"failed_pct": 4.8,
"recovery_rate": 66.7
}
]
}
Response fields
| Field | Type | Description |
|---|
date | string | Period start date |
failed_amount | number | Total failed payment amount (cents) |
recovered | number | Amount recovered after retry (cents) |
still_unpaid | number | Amount still outstanding (cents) |
churned | number | Amount lost to churn (cents) |
failed_invoices | integer | Number of failed invoices |
recovered_customers | integer | Customers whose payments were recovered |
still_unpaid_customers | integer | Customers still unpaid |
churned_customers | integer | Customers who churned due to failed payment |
affected_customers | integer | Total customers affected |
total_invoices | integer | Total invoices in period |
failed_pct | float | Percentage of invoices that failed |
recovery_rate | float | Percentage of failed amount recovered |
