Skip to content

Dunning

When a renewal charge is declined, bc-subscriptions runs a dunning flow: a sequence of automatic retries paired with subscriber emails that invite the customer to update their payment method. This page explains what the flow does by default, how to configure it for your business, what your subscribers see, and what happens when retries run out.

What dunning is

A subscription renewal charge can fail for many reasons — insufficient funds, an expired card, a transient processor error. bc-subscriptions distinguishes two categories:

  • Soft decline — a temporary condition (insufficient funds, processing error, network timeout). Retries are scheduled per your dunning policy.
  • Hard decline — a permanent condition (stolen card, do-not-honor, invalid card number after an updater pass). No retries are scheduled. The subscription moves to past_due immediately and the subscriber gets a payment-method update email.

For soft declines, the subscription moves to past_due and the dunning sequence begins.

The retry schedule

The default retry schedule is three attempts at 1, 3, and 7 days after the initial failure. The timeline looks like this:

Event Days after initial failure
Charge fails; dunning opens; recovery email #1 sent Day 0
Retry attempt 1 Day 1
Recovery email #2 sent (if retry 1 fails) Day 1
Retry attempt 2 Day 4 (1 + 3)
Final-notice email sent (if retry 2 fails) Day 4
Retry attempt 3 Day 11 (1 + 3 + 7)
Final action triggers (if retry 3 fails) Day 11

If any retry succeeds, dunning closes immediately and the subscription returns to active.

If a subscriber updates their payment method while in dunning, the retry counter resets and the charge runs within about one minute — they do not need to wait for the next scheduled retry.

Configuring dunning

Go to Admin → Settings → Dunning to adjust the policy.

Retry schedule

The schedule is a comma-separated list of day offsets from the initial failure. The default is 1, 3, 7. Examples:

  • Digital products (low churn risk): 1, 2, 4
  • High-AOV subscriptions (more recovery time): 3, 7, 14
  • More attempts: 1, 3, 7, 14

Keep at least 24 hours between retries. Tighter intervals risk processor rate limits and increase dispute exposure. Also avoid very long windows (e.g., 7, 14, 30) — subscribers may dispute a charge they've forgotten about.

Final action

When all retries are exhausted, three options are available:

Option What happens
Cancel (default) Subscription moves to cancelled. No further charges.
Route to exception queue Subscription stays past_due and appears in the merchant dashboard Exception Queue for manual resolution.
Keep retrying Retries continue indefinitely at the last interval. Use cautiously — unmonitored retries on long-dead payment methods accumulate disputes.

Policy changes apply to dunning sequences that start after you save. In-flight sequences run to completion under the policy active when they started.

Recovery email templates

Go to Admin → Settings → Emails → Dunning. Three template slots correspond to the three retry stages:

  • First decline
  • Second decline
  • Final notice

Each template supports merge tags: {{subscriber.first_name}}, {{subscription.plan_name}}, and {{portal_url}} (links directly to the subscriber's payment-method update view). Preview each template with a real subscription before saving — a typo in a merge tag breaks delivery silently.

What subscribers see

At each dunning step where the next retry is more than 24 hours away, the subscriber receives an email that explains what went wrong, when the next retry is scheduled, and includes a link to update their payment method in the portal.

If a subscriber has opted into SMS, they also receive an SMS reminder when a retry is less than 6 hours away (Phase 2 feature).

Subscribers do not need the email link to recover — they can go directly to the portal (https://<your-portal>/account/payment-methods) and update their card at any time.

Outcomes

Recovery: If any retry succeeds, or if the subscriber updates their payment method and the immediate retry succeeds, the subscription returns to active. A confirmation email goes to the subscriber. Dunning closes.

Final cancellation: If all retries fail and the final action is Cancel, the subscription moves to cancelled. No further charges run. The subscriber receives a final email.

Exception queue: If the final action is Route to exception queue, the subscription remains past_due in the merchant dashboard. Your team can contact the subscriber directly and trigger a manual retry or close the subscription.

Inspecting a stuck dunning sequence

  1. Go to Subscriptions → filter by status past_due
  2. Click a subscription → open the Dunning tab
  3. The tab shows the retry-attempt timeline, each recovery email's delivery status, the next scheduled retry, and the current position in the state machine

If a subscription is stuck past_due beyond 7 days after the schedule should have exhausted, contact support. The dunning state machine can get wedged; support has a manual unblock procedure.