Resolve a dunning run

POST

/v1/dunning/runs/{id}/resolve

curl --request POST \
  --url http://localhost:8080/v1/dunning/runs/example/resolve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "resolution": "payment_recovered" }'

• Local development

Stops payment retries for a run and applies the chosen outcome to its invoice first:

• payment_recovered: records an offline payment for the full amount due, as POST /v1/invoices/{id}/record-payment does.
• invoice_voided: voids the invoice and stops collection at Stripe, as POST /v1/invoices/{id}/void does.
• invoice_not_collectible: writes the invoice off, as POST /v1/invoices/{id}/mark-uncollectible does.

If the invoice step fails, the run stays open and the error is returned. If the invoice is already in the requested state, that step is skipped. Fires the dunning.resolved webhook event once.

Authorizations

• BearerAuth

Parameters

Path Parameters

id

required

string

Header Parameters

Idempotency-Key

string

Makes the call safe to retry. Send a unique value (a UUID works) and the same value on every retry. For 24 hours, a repeat with the same key, method, path and body gets the first response again, with an Idempotent-Replayed: true header, instead of running again. The error cases are in docs/api-surface.md. The usage routes do not take it: each usage event carries its own idempotency_key.

Request Body^required

Media typeapplication/json

object

resolution

required

string

Allowed values: payment_recovered invoice_voided invoice_not_collectible

Responses

200

The run as stored after the call. If another process resolved it first, its existing resolution is returned.

Media typeapplication/json

object

id

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

Example

{
  "state": "active",
  "resolution": "payment_recovered"
}

400

Body is not valid JSON.

Media typeapplication/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"
  }
}

404

Dunning run or invoice not found.

Media typeapplication/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"
  }
}

409

The invoice step was refused because of the invoice’s state, for example voiding a paid invoice or a charge still running. Codes as on the matching invoice endpoint.

Media typeapplication/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"
  }
}

422

resolution is missing or not one of the three values.

Media typeapplication/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"
  }
}