Subscriptions

Retry billing on a subscription whose billing is failing

Changed on

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.

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

Request

  • Base URL: http://localhost:8080
  • URL: http://localhost:8080/v1/subscriptions/{id}/retry-billing
  • Auth: HTTP bearer

Path parameters

idstring required

Response

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.

invoices_generatedinteger 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.

still_dueboolean

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.

Changes