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 →

Retry billing on a subscription whose billing is failing

POST

/v1/subscriptions/{id}/retry-billing

const url = 'http://localhost:8080/v1/subscriptions/example/retry-billing';
const options = {method: 'POST', 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 POST \
  --url http://localhost:8080/v1/subscriptions/example/retry-billing \
  --header 'Authorization: Bearer <token>'

Clears the subscription’s billing_failure and bills it now, with the same attempt the billing run makes. Use it after fixing the cause of a failure, to skip the wait, or to restart a parked subscription. An audit log entry records the retry.

Once the failure is cleared, the outcome of the attempt is never an HTTP error. A 200 has three outcomes:

Billed. No billing_failure, and still_due is false. A subscription that was overdue for several periods is billed for each of them, one invoice per period.
Failed again. The subscription carries a new billing_failure with attempts: 1, and the billing run then retries on its own schedule. This includes an attempt that finished without an error but left the subscription due.
Not completed. No billing_failure, and still_due is true. The attempt was cut short by a lost database connection or a deadlock, and nothing was saved. The subscription is still unbilled, and the next billing run attempts it. Calling this endpoint again answers 409, because the failure is already cleared.

The call bills inline. If it times out part-way through a long catch-up, the response is an error, the invoices already created stay, and the next billing run finishes the rest. The failure may already be cleared at that point, so a repeat call can answer 409.

Authorizations

BearerAuth

Parameters

Path Parameters

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.

Responses

200

The retry ran. Read the outcome from two fields. subscription.billing_failure is present when the attempt failed again. When it is absent, still_due false means the subscription billed or had nothing left to bill, and still_due true means the attempt did not complete and the subscription is still unbilled.

application/json

object

subscription

required

object

required

string

tenant_id

string

code

required

string

display_name

required

string

customer_id

required

string

items

The subscription’s priced lines. Each item names its plan.

Array<object>

One priced line of a subscription. It pairs a plan with a quantity.

object

required

string

tenant_id

string

subscription_id

required

string

plan_id

required

string

quantity

required

integer format: int64

metadata

The item’s stored metadata. Absent when empty.

object

key

additional properties

any

pending_plan_id

Plan the item moves to at pending_plan_effective_at. Absent when no change is scheduled.

string

pending_plan_effective_at

string format: date-time

plan_changed_at

When the plan was last changed immediately. Absent until the first such change.

string format: date-time

created_at

required

string format: date-time

updated_at

required

string format: date-time

status

required

string

Allowed values: draft trialing active canceled

billing_time

required

string

Allowed values: calendar anniversary

trial_start_at

string format: date-time

trial_end_at

string format: date-time

started_at

string format: date-time

activated_at

string format: date-time

canceled_at

When the subscription was canceled. Absent until then.

string format: date-time

cancel_at

A scheduled cancel time, if one is set.

string format: date-time

cancel_at_period_end

required

True when the subscription cancels at the end of the current period.

boolean

cancel_effective_at

When a scheduled cancel takes effect. Absent when no cancel is scheduled.

string format: date-time

pause_collection

Present on a subscription while collection is paused. New invoices are still created, but stay drafts and are not charged.

object

behavior

required

string

Allowed values: keep_as_draft

resumes_at

When collection resumes. Absent when the pause lasts until it is cleared. On a pause set by dunning, it is when Hardcount recorded the payment of the invoice the pause was set for.

string format: date-time

set_by

required

Who paused collection. operator: you, through the API or the dashboard; the pause lasts until you resume it or until resumes_at. dunning: a dunning policy’s pause final action. A dunning pause lifts by itself once the invoice whose dunning set it is paid, even if another invoice is still owed. Periods that ended during the pause keep their draft invoices.

string

Allowed values: operator dunning

billing_thresholds

Limits that make Hardcount invoice before the period ends. A threshold invoice bills the period’s usage so far, and no base fee. The period keeps its dates, the base fee is billed as it would be with no threshold, and the period’s next invoice bills the rest of the usage.

object

amount_gte

Usage threshold in cents, compared with the period’s usage so far (the base fee is not counted). Absent when not set.

integer format: int64

item_thresholds

required

Array<object>

object

subscription_item_id

required

string

usage_gte

required

Usage quantity threshold, as a decimal string.

string

current_billing_period_start

string format: date-time

current_billing_period_end

End of the current period (exclusive).

string format: date-time

current_billing_period_display

The current period as text, with the last day included, in the tenant’s billing time zone.

string

next_billing_at

string format: date-time

billing_anchor_day

Day of the month the subscription bills on (1-31). Absent for calendar-monthly subscriptions.

integer

test_clock_id

string

billing_failure

Present on a subscription while the billing run is failing on the work that subscription has due now (a period close, or a scheduled mid-period cancel). Absent otherwise: a subscription that bills cleanly, or whose due work changed, carries no billing_failure.

After each failed attempt the billing run waits before the next one: 15 minutes, 1 hour, 4 hours, 12 hours, then 24 hours three times. The eighth failure parks the subscription (parked: true, no next_attempt_at). A parked subscription is not attempted again until POST /v1/subscriptions/{id}/retry-billing is called.

Never set on a subscription attached to a test clock.

object

attempts

required

Failed attempts on the work that is due now. At least 1.

integer

max_attempts

required

The attempt at which the subscription parks (8).

integer

last_error

required

Why the latest attempt failed: a sentence an operator can act on, or a generic line carrying the subscription id as the reference to search the server log for. Never raw error text.

string

failed_at

required

When the latest attempt failed.

string format: date-time

next_attempt_at

The billing run does not attempt the subscription before this instant. The attempt happens on the first run at or after it, so on an hourly schedule it can be up to an hour later. Absent when parked.

string format: date-time

parked

required

True when automatic attempts have stopped.

boolean

created_at

required

string format: date-time

updated_at

required

string format: date-time

invoices_generated

required

Period-close invoices this call created. The final invoice of a scheduled cancel and the first invoice at a trial end are not counted, so 0 does not mean the retry failed. Read success from subscription.billing_failure and still_due.

integer

still_due

required

True when, after the attempt, the subscription has no billing_failure and is still due for billing. The attempt did not complete and nothing was saved; the next billing run attempts the subscription.

boolean

Example

{
  "subscription": {
    "status": "draft",
    "billing_time": "calendar",
    "pause_collection": {
      "behavior": "keep_as_draft",
      "set_by": "operator"
    }
  }
}

404

Subscription not found.

409

The retry was refused. Code billing_not_failing: the subscription has no billing_failure, so there is nothing to retry. Code invalid_state: the subscription is attached to a test clock; use the clock’s retry advance instead.