Selling

Subscriptions and dunning

Every subscription renews on its billing date. When a renewal fails, it moves into dunning: we retry on a schedule and give the buyer a chance to update their card, so you don't lose customers to an expired card.

Statuses

Status	Meaning
`trialing`	In a free trial. Not billed yet.
`active`	Paid up. Renews on nextBillingAt.
`retrying`	A renewal failed and an automatic retry is scheduled for nextRetryAt.
`pastDue`	Retries so far have failed. Still recoverable until maxRetries is reached.
`canceled`	Ended. No further charges.

How dunning recovers revenue

Each subscription allows up to four retry attempts (maxRetries). The record tells you which attempt it's on (retryAttempt), when the next one runs (nextRetryAt) and why the last one failed (lastFailure), for example insufficient_funds, do_not_honor or card_blocked.

A subscription in dunning

{
  "id": "sub_1002",
  "customer": "Lena Fischer",
  "country": "DE",
  "planName": "Pro",
  "status": "retrying",
  "amountCents": 99900,
  "retryAttempt": 2,
  "maxRetries": 4,
  "nextRetryAt": "2026-11-10T15:49:46Z",
  "lastFailure": "insufficient_funds"
}

Retry a payment now

You can trigger a retry yourself, for example after the buyer tells you they've topped up. The dashboard's Retry now button does the same.

bash

curl -X POST $HLAWULA_URL/api/subscriptions/sub_1002/retry

A successful retry returns outcome: "recovered", sets the subscription back to active, moves the billing date on a month and records the payment. A card blocked by the issuer can't be recovered by retrying, so it returns outcome: "failed" and schedules the next automatic attempt two days later.

Planned

Card update emails to the buyer, a customer portal for self-service cancellation, and configurable retry schedules. In the demo, renewal and automatic retry timing come from seed data rather than a scheduler.