Dunning is how you recover failed payments. Done well, it saves 20–40% of subscription revenue that a naive “charge once, cancel on fail” flow throws away.
1. Open dunning settings
recurrabee console → Settings → Dunning.
2. Retry schedule
Default schedule (tunable per merchant):
Attempt 1: on failure
Attempt 2: +1 day
Attempt 3: +3 days
Attempt 4: +7 days
Terminal: +14 days → cancel
Each attempt is a real Shopify charge via the subscription contract. The contract enters past-due state on the first failure and remains there until either a retry succeeds (→ active) or the terminal attempt exhausts (→ cancelled).
3. Branded emails
For each retry step you can enable an email to the subscriber:
- Soft retry (attempt 2–3): “Your card on file was declined. We’ll try again in a couple days. Update your payment method to avoid interruption.”
- Hard retry (attempt 4): “Final retry coming up. Update now to avoid cancellation.”
- Terminal: “Your subscription was cancelled after multiple failed attempts.”
Emails use ZeptoMail (the same transactional provider the rest of the stack uses). Copy is merchant-editable; the default copy is reviewed for tone (firm but not hostile).
4. Include update payment link
Every dunning email includes a magic link to Shopify’s customer account → payment methods page, where the subscriber can update their card in one click. This is what actually moves the needle on recovery.
5. Past-due visibility
recurrabee’s console has a Past-due view that lists every contract currently in dunning, ordered by next retry date. You can manually trigger a retry now, cancel early, or mark the contract as “don’t retry” (for customers you’ve already reached out to via support).
Why a state machine?
Dunning crosses many entities — a billing attempt, a notification, a state transition, a customer. Keeping it in a state machine (rather than a pile of booleans on the contract row) means every transition is logged, replayable, and testable.