Pre-1.0 · one maintainer · Stripe and cards only · no SDKs (client libraries) yet · no production users yet. Docs describe v0.9.1 (29 Oct 2026) · What’s new →

List dunning runs

GET

/v1/dunning/runs

const url = 'http://localhost:8080/v1/dunning/runs?state=active&limit=50&offset=0';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'http://localhost:8080/v1/dunning/runs?state=active&limit=50&offset=0' \
  --header 'Authorization: Bearer <token>'

Dunning is the process of retrying a failed invoice payment on a schedule. A dunning run tracks those retries for one invoice. Runs are listed newest first.

Authorizations

BearerAuth

Parameters

Query Parameters

invoice_id

string

state

string

Allowed values: active escalated resolved

limit

integer

default: 50 >= 1 <= 100

Rows per page, from 1 to 100. Default 50. Any other value, or one that is not a whole number, is a 422 with param: limit.

offset

integer

Rows to skip, 0 or more. Default 0. A negative value, or one that is not a whole number, is a 422 with param: offset.

Responses

200

Dunning run list.

application/json

object

data

required

Array<object>

object

required

string

tenant_id

string

invoice_id

required

string

customer_id

string

policy_id

required

string

state

required

active: retries are running. escalated: retries ran out (resolution is retries_exhausted). resolved: the run ended another way; see resolution.

string

Allowed values: active escalated resolved

reason

string

attempt_count

required

integer

last_attempt_at

string format: date-time

next_action_at

string format: date-time

paused

required

boolean

resolved_at

string format: date-time

resolution

How the run ended, set when it is resolved. Exception: action_failed is set on a run that is still active. The final action (pause, cancel or mark uncollectible) failed and will be retried at next_action_at. amount_below_minimum: a charge on the invoice was refused by Stripe because the amount is below its minimum charge, so the run ended without its final action.

string

Allowed values: payment_recovered invoice_voided invoice_not_collectible retries_exhausted action_failed amount_below_minimum

created_at

required

string format: date-time

updated_at

required

string format: date-time

invoice_number

Filled in on list responses.

string

invoice_amount_due_cents

Filled in on list responses.

integer format: int64

invoice_currency

Filled in on list responses.

string

effective_now

The test clock’s current time, when the customer is on a test clock. Filled in on list responses.

string format: date-time

test_clock_id

Filled in on list responses.

string

max_retry_attempts

How many retries the run’s policy makes: the length of its retry_days. Filled in on list responses. When attempt_count has reached it, no charge is retried: next_action_at is when the final action (pause, cancel or mark uncollectible) runs.

integer

total

required

How many rows match the request’s filters, on every page, not only this one. The audit log and the customer list’s search and name or email sort say where they stop counting.

integer

Example

{
  "data": [
    {
      "state": "active",
      "resolution": "payment_recovered"
    }
  ]
}

422

limit or offset is out of range or not a whole number, or the request sends the removed after cursor (param names it)

application/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}