Subscription Dunning automatically sends email sequences to customers whose subscriptions have lapsed due to payment failure or customer cancellation, prompting them to update their payment method and reactivate.
What Is Subscription Dunning?
Dunning automatically detects when a subscription enters a recoverable state and sends a sequence of emails prompting the customer to take action:- On Hold subscriptions: Renewal payment failed (insufficient funds, expired card, etc.)
- Cancelled subscriptions: Customer cancelled from the customer portal
How Dunning Works
1
Trigger
Dunning is triggered when a subscription enters one of two states:
- On Hold: A renewal payment failed (insufficient funds, expired card, etc.)
- Cancelled: The customer cancelled their subscription from the customer portal
2
Email Sequence
Based on the trigger state, the system sends up to 4 dunning emails at
configured intervals. Each email includes a link to the customer portal where
the customer can update their payment method or re-purchase the subscription.
3
Recovery
When the customer updates their payment method through the customer portal, a charge is automatically created for remaining dues. If the payment succeeds, the subscription is reactivated and the dunning attempt is marked as recovered.
Status Lifecycle
When a dunning attempt is marked as
exhausted, the subscription state is not modified. The subscription remains in its current state (on hold or cancelled).Configuring Dunning
Enable and configure Dunning from Settings in your dashboard.
Dunning settings in the dashboard showing enable toggle, on-hold sequence, and cancelled sequence
Email Sequences
Dunning supports two email sequences — On Hold and Cancelled — each with up to 4 configurable emails. Each email has the following configurable fields:
Default email timing:
Example Dunning Emails
Dunning sends different emails depending on the subscription state. Below are examples of each type as seen by the customer.- On Hold
- Cancelled
Dunning email sent when a renewal payment fails and the subscription is on hold
Customer Recovery Experience
When a customer clicks the link in a dunning email, they are taken to the customer portal where they can see their subscription status and update their payment method.
Customer portal showing an on-hold subscription with option to update payment method
Analytics
Track the performance of Dunning from the Recovery tab in the Analytics section of your dashboard.
Recovery analytics dashboard showing ACR and dunning metrics
Webhook Events
Recovery Webhook Payloads
View the full webhook payload schemas for dunning events.
Edge Cases
Best Practices
- Start with defaults: The default email timing is designed with reasonable spacing (1, 3, 5 and, 7 days) to avoid overwhelming customers while maintaining urgency.
- Monitor success rates: Track which email in the sequence drives the most recoveries. If later emails have near-zero conversion, consider disabling them.
- Coordinate with support: Ensure your support team knows that dunning emails are being sent, so they can assist customers who reach out.
- Review subscription states: Pair dunning with
subscription.on_holdandsubscription.cancelledwebhooks for comprehensive lifecycle tracking.
Dunning works alongside the existing subscription on-hold and reactivation flows in the customer portal. Once enabled, it runs automatically with no additional integration required.
Related
Recovery Webhooks
React to
dunning.started and dunning.recovered events.Abandoned Cart Recovery
Recover incomplete or failed one-time checkouts with targeted emails.
Customer Portal
Customers update payment methods through the customer portal.
Subscriptions
Understand subscription states that trigger dunning workflows.