Get a dunning run with its events

GET

/v1/dunning/runs/{id}

curl --request GET \
  --url http://localhost:8080/v1/dunning/runs/example \
  --header 'Authorization: Bearer <token>'

• Local development

Authorizations

• BearerAuth

Parameters

Path Parameters

id

required

string

Responses

200

The run and its event history. events is empty if the event history could not be read, and degraded then names it.

Media typeapplication/json

object

run

required

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

events

required

Array<object>

object

id

required

string

run_id

required

string

tenant_id

string

invoice_id

required

string

event_type

required

string

Allowed values: dunning_started retry_attempted escalated resolved

state

required

string

Allowed values: active escalated resolved

reason

string

attempt_count

required

integer

metadata

object

key

additional properties

any

created_at

required

string format: date-time

recorded_at

string format: date-time

line

The event in the words of the activity line standard (ADR-128): the line the invoice’s payment timeline shows for the same event, without that timeline’s folds. Absent when the run’s invoice could not be read (degraded names invoice).

object

id

required

The row’s stable key: the event’s id on an invoice timeline row, the audit entry’s id on a subscription timeline row, dunning: and the event’s id on a dunning run event (the same key the invoice timeline gives that event), and email: and the email’s id on a sent email (likewise).

string

kind

required

Machine name of the event.

string

title

required

string

amount

object

cents

required

integer format: int64

currency

required

string

problem

string

detail

required

The meta line before the actor. Each item is one segment, shown joined by “ · “; a segment’s parts read as one phrase, for example a money part followed by the text “ refunded to card”.

Array<Array<object>>

actor

Who did it. person and api_key carry the name (a person’s email when they have no name), customer says where through via, and automatic is anything Hardcount did on its own. Absent when no fact written with the row names one.

object

kind

required

string

Allowed values: person api_key customer automatic

name

string

via

string

Allowed values: payment_page portal

tone

required

Neutral: something happened. success: money arrived, or was returned as intended. warning: needs a look, or money will not be collected. failure: an attempt failed.

string

Allowed values: neutral success warning failure

occurred_at

required

string format: date-time

recorded_at

string format: date-time

degraded

required

Sources that could not be read. events: the event history, so events is empty. invoice: the run’s invoice, so no event has a line. The others leave the lines without what they would add: emails the reminder and final-notice clauses, charge_attempts the decline reason and amount, audit who resolved the run.

Array<string>

Allowed values: events invoice emails charge_attempts audit

Example

{
  "run": {
    "state": "active",
    "resolution": "payment_recovered"
  },
  "events": [
    {
      "event_type": "dunning_started",
      "state": "active",
      "line": {
        "kind": "invoice.voided",
        "title": "Payment failed",
        "amount": {
          "currency": "USD"
        },
        "problem": "Card declined: insufficient funds",
        "detail": [
          [
            {
              "money": {
                "currency": "USD"
              },
              "link": {
                "kind": "invoice"
              }
            }
          ]
        ],
        "actor": {
          "kind": "person",
          "via": "payment_page"
        },
        "tone": "neutral"
      }
    }
  ],
  "degraded": [
    "events"
  ]
}

404

Dunning run 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"
  }
}