Dunning as a state machine: retries, grace and when access stops
In short
Dunning is the state machine a subscription enters when a payment fails and leaves by recovering or cancelling. It has 6 states worth naming — failed, retrying, grace, suspended, cancelled, recovered — and each must be written into the entitlement record rather than inferred from billing, because access, the reader's message and the churn report all read it.
Key takeaways
- Dunning is a state machine, not an email sequence — the emails are one output of it.
- Every dunning state needs an explicit entitlement value; inferring access from billing status is where drift starts.
- Grace is the only state where the money says no and access deliberately says yes.
- The transition nobody builds is recovery after suspension, so paying readers stay locked out.
Dunning is what happens between a payment failing and the subscription either recovering or ending. Most teams build it as a campaign — mail on days 1, 3, 7 and 14 — then find that access, the reader's message and the retention report have drifted apart, because each read a different signal. As a state machine it stops drifting: the subscription is in exactly 1 state, that state carries 1 entitlement value, and the rest derives from it.
Two adjacent questions are settled elsewhere: what persuades a card to succeed on retry, in what actually recovers a failed card, and how long grace runs, in the grace period is a product decision.
Six states, and the access value each one carries
| State | Entitlement value | What the reader is told | What ends it |
|---|---|---|---|
| Payment failed | Active | Nothing yet — attempt 1 often succeeds unaided | A retry succeeds, or the schedule starts |
| Retrying | Active | One message naming the card's last 4 digits and the amount | A retry succeeds, the card is updated, or attempts are exhausted |
| Grace | Active, with an end date | Access continues until a stated date, said plainly | That date arrives, or payment succeeds |
| Suspended | Not active, reason coded as payment | Locked out, with the reason and the 1 action that fixes it | Payment succeeds, an operator acts, or the deadline passes |
| Cancelled | Ended, reason coded as involuntary | Treated as a former subscriber, not a delinquent one | Terminal — a new subscription starts a new record |
| Recovered | Active, window realigned | Confirmation that access is back, and from when | Resolves immediately to the normal active state |
Your billing provider has its own vocabulary and it is not this list. Stripe's subscription object documents statuses including incomplete, incomplete_expired, past_due, unpaid, canceled and paused, and notes that a subscription whose first invoice goes unpaid for 23 hours moves to incomplete_expired, which is terminal. Adyen, Chargebee and Recurly name things differently again. Those are facts about money. Whether a reader in past_due may open an article is a product decision, and no billing status expresses it.
Grace: the state where money and access disagree on purpose
Grace is the only node where the billing system says no and the entitlement deliberately says yes. It cannot be inferred, because it exists only because somebody decided it should. So it is stored: a distinct state, an end instant, a reason. Infer it from the age of an unpaid invoice and extending one reader's grace by 7 days means editing an invoice, while nobody can say how many are reading on credit.
It also needs its own bucket in reporting. A subscriber in grace is neither active nor churned, and folding them into either makes retention wrong in the flattering direction.
The transitions that never get built
- Suspended back to active. The card succeeds 6 days after suspension, the provider marks the subscription paid, and nothing reissues the grant. The reader is paying and locked out, and they will not report it twice.
- Grace expiring while a retry is in flight. Two clocks, no coordination, and a reader suspended 40 minutes before the payment that would have saved them. Make the payment result an input to the grace timer.
- Cancelled back to active. Involuntary cancellation is not a reader choosing to leave, and treating them identically forces a recovered subscriber to make a new account and lose their history.
- Anything to suspended, when an operator pulls the lever. Manual suspensions need the same coded reason as automatic ones, or the churn report files a fraud block as a failed card.
A dunning system that can suspend but cannot cleanly un-suspend is not a retention tool. It is a way of losing subscribers who already paid.
The machine belongs in the entitlement, not in the mailer
The state must be written into the entitlement record every surface reads, which is why the authority question matters — billing system or entitlement service as the authority. If the site reads the grant, the app a store receipt and the email tool a marketing tag, a reader in grace is locked out by 1 surface, welcomed by another and sent a win-back campaign by the third.
What a suspended reader sees depends on your wall model — under a hard wall the gate, under a meter a quiet return to metered reading, a choice made in hard wall or meter for a news archive. And a locked-out reader does not give up. They search, and often find a syndicated copy of the story open on a partner's site, the retention edge of the partner's copy is outranking the original.
Run the machine as operations software with alerting on stuck states rather than as a campaign: count subscriptions in retrying or grace beyond that state's declared maximum, and treat a rising count as an incident. That is the discipline any exception queue needs, argued in AI in logistics operations and built into the workflows we ship under AI agents and automation. This silo sits under paywalls, subscriptions and entitlements, inside our media and publishing practice.
Frequently asked questions
Short answers to the follow-ups this page tends to raise.
What does dunning mean in a subscription business?
Dunning is the process that runs after a payment fails: retrying the charge, telling the subscriber, and deciding when access stops. Model it as a state machine with named states rather than an email sequence, because access, messaging and reporting all have to agree on which state a subscriber is in.
Should a subscriber keep access while their payment is being retried?
Usually yes, for a bounded and explicit grace window whose length is a product decision rather than a billing default. Cutting access on the first failure punishes people whose card simply expired; unbounded grace gives the product away. What matters technically is that grace is a stored state with an end instant, not something inferred from the age of an unpaid invoice.
Should dunning states come straight from the billing provider's status field?
Map them, but never use them directly. Provider statuses describe money — whether an invoice is unpaid, whether retries are exhausted — while your states describe access, a product decision. Keep 1 mapping table with a fail-closed default, so a status added later cannot silently grant or remove access.
- dunning
- subscriptions
- entitlements
- state machines
The work behind this page
Builds from our portfolio that this page draws on.
Read next
- The app says subscribed, the site says notCross-surface disagreement is three causes wearing one complaint: two identities, two authorities, or two caches. Resolving the identifier on each surface eliminates the first in minutes.diagnostic
- Paying subscribers are hitting the wall, and only on the popular storiesThe symptom tracks popularity because the hit ratio is the exposure: the more cacheable a story is, the more likely a subscriber gets served the anonymous copy of it.diagnostic
- Renewals that never reached the access systemCount the gap between what the provider sent and what you processed. Its size and shape separate delivery loss from processing loss, and only one of them is fixed by a better handler.diagnostic
- The meter count: where it lives, what it counts and who can reset itA meter is not a number. It is 4 decisions — countable event, storage location, reset window and exemptions — and most implementations make only the first one consciously.definition
- The meter resets for anyone who opens a private windowA meter stored in the browser can be cleared by the browser. Measure the leak first, then decide whether identity-bound counting is worth what it costs.diagnostic
- The registration wall is not a cheap paywallA regwall trades content for a durable identity. Judged on revenue it always looks like a weak paywall; judged on known-reader coverage it is a different instrument entirely.definition
Working on something in this space?
Tell us where you are in a sentence or two. We'll tell you honestly whether we're the right team, and what a sensible first slice of the work looks like.
Start the conversation