Dunning is the automated process of recovering failed payments. When an invoice payment fails, the dunning policy defines a sequence of escalating actions - retry the payment, send reminder emails, and eventually cancel the subscription if payment isn't recovered.
How it works:
- An invoice payment fails
- The dunning policy's first step activates (e.g., retry after 3 days)
- If the retry fails, the next step activates (e.g., send a reminder email after 7 days)
- Steps escalate until payment succeeds or the final action triggers (e.g., cancel subscription after 30 days)
Dunning policies can be set at the organization level (default for all plans) or per-plan for different escalation paths.
List dunning cases
Money your customers owe outside any invoice, newest first. A case opens when a dispute you lost could not take back, from the customer's wallet, money a reversal or a refund had already returned there, because the wallet had spent it. If the customer has another saved payment method than the one charged back, the case is charged to it once; if there is none, the charge fails, or your organization's dunning.case_payment setting is top_up_only, it is deducted from the customer's next top-up instead. It is reversed — and a charge that paid it refunded — when the payment provider reports the dispute won after it was lost. Filter by status and customer.
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
sortOrdering: opened_at with an optional :asc/:desc suffix (default opened_at:desc). An unknown value is rejected. Cursors are bound to the ordering that issued them, so changing sort mid-walk needs a fresh first page.
statusKeep only cases in this status: open, paid or reversed. Absent keeps all.
customer_idKeep only this customer's cases.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List dunning cases › Responses
OK