Oliver/my-biz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: classy dark one-pager with modal, webhook, shiny gold, sticky nav

Browse Source
This commit is contained in:
oliver
2026-04-24 11:07:02 -03:00
commit 74aa890b5d
152 changed files with 40078 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/churn-prevention/references/dunning-playbook.md
+408
View File
@@ -0,0 +1,408 @@
# Dunning Playbook
Complete guide to recovering failed payments and reducing involuntary churn.
---
## Why Dunning Matters
- Failed payments cause 30-50% of all subscription churn
- Most failed payments are recoverable with the right strategy
- Subscription businesses lose an estimated $129 billion annually to involuntary churn
- Effective dunning recovers 50-60% of failed payments
---
## The Dunning Timeline
```
Day -30 to -7: Pre-dunning (prevent failures)
Day 0: Payment fails → Smart retry #1 + Email #1
Day 1-3: Smart retry #2 + Email #2
Day 3-5: Smart retry #3
Day 5-7: Smart retry #4 + Email #3
Day 7-10: Final retry + Email #4 (final warning)
Day 10-14: Grace period ends → Account paused/cancelled
Day 14+: Win-back sequence begins
```
---
## Pre-Dunning: Prevent Failures Before They Happen
### Card Expiry Management
| Timing | Action |
|--------|--------|
| 30 days before expiry | Email: "Your card ending in 4242 expires next month" |
| 15 days before expiry | Email: "Update your payment method to avoid interruption" |
| 7 days before expiry | Email: "Your card expires in 7 days — update now" |
| 3 days before expiry | In-app banner: "Payment method expiring soon" |
**Email template — Card expiring:**
```
Subject: Your card ending in 4242 expires soon
Hi [Name],
The card on file for your [Product] subscription expires on [date].
Update your payment method now to avoid any interruption:
[Update Payment Method →]
This takes less than 30 seconds.
— [Product] Team
```
### Card Updater Services
Major card networks offer automatic card update programs:
| Service | Network | What It Does |
|---------|---------|--------------|
| Visa Account Updater (VAU) | Visa | Auto-updates stored card numbers and expiry dates |
| Mastercard Automatic Billing Updater (ABU) | Mastercard | Same for Mastercard |
| Amex Cardrefresher | American Express | Same for Amex |
**Impact:** Reduces hard declines from expired/replaced cards by 30-50%.
**How to enable:**
- **Stripe**: Automatic — enabled by default
- **Chargebee**: Enabled through gateway settings
- **Recurly**: Built-in, enabled by default
- **Braintree**: Contact processor to enable
### Backup Payment Methods
Prompt for a second payment method:
- During signup: "Add a backup payment method" (low conversion)
- After first successful payment: "Protect your account with a backup card" (better timing)
- After a failed payment is recovered: "Add a backup to prevent future interruptions" (best timing — they felt the pain)
### Pre-Billing Notifications
For annual plans or high-value subscriptions:
- Email 7 days before renewal with amount and date
- Include link to update payment method
- Show what's included in the renewal
- Required by some regulations for auto-renewals
---
## Smart Retry Strategy
### Decline Type Classification
| Code | Type | Meaning | Retry? |
|------|------|---------|--------|
| `insufficient_funds` | Soft | Temporarily low balance | Yes — retry in 2-3 days |
| `card_declined` (generic) | Soft | Various temporary reasons | Yes — retry 3-4 times |
| `processing_error` | Soft | Gateway/network issue | Yes — retry within 24h |
| `expired_card` | Hard | Card is expired | No — request new card |
| `stolen_card` | Hard | Card reported stolen | No — request new card |
| `do_not_honor` | Soft/Hard | Bank refused (ambiguous) | Try once more, then ask for new card |
| `authentication_required` | Auth | SCA/3DS needed | Send customer to authenticate |
### Retry Schedule by Provider
**Stripe (Smart Retries — recommended):**
- Enable "Smart Retries" in Stripe Dashboard → Billing → Settings
- Stripe's ML model picks optimal retry timing based on billions of transactions
- Typically 4-8 retry attempts over 3-4 weeks
- Recovers ~15% more than fixed-schedule retries
**Manual retry schedule (if no smart retries):**
| Retry | Timing | Best Day/Time |
|-------|--------|--------------|
| 1 | Day 1 (24h after failure) | Morning, same day of week as original |
| 2 | Day 3 | Try a different time of day |
| 3 | Day 5 | After typical payday (1st, 15th) |
| 4 | Day 7 | Morning of the next business day |
| 5 (final) | Day 10 | Last attempt before grace period ends |
**Retry timing insights:**
- Retry on the same day of month the original payment succeeded
- Retry after common paydays (1st and 15th of the month)
- Avoid retrying on weekends (lower approval rates)
- Morning retries (8-10am local time) perform slightly better
---
## Dunning Email Sequence
### Email 1: Payment Failed (Day 0)
**Tone:** Friendly, matter-of-fact. No alarm.
```
Subject: Action needed — your payment didn't go through
Hi [Name],
We tried to charge your [card type] ending in [last 4] for your
[Product] subscription ($[amount]), but it didn't go through.
This happens sometimes — usually a quick card update fixes it.
[Update Payment Method →]
Your access isn't affected yet. We'll retry automatically, but
updating your card is the fastest fix.
Need help? Just reply to this email.
— [Product] Team
```
### Email 2: Reminder (Day 3)
**Tone:** Helpful, slightly more urgent.
```
Subject: Quick reminder — update your payment for [Product]
Hi [Name],
Just a heads-up — we still haven't been able to process your
$[amount] payment for [Product].
[Update Payment Method →]
Takes less than 30 seconds. Your [data/projects/team access]
is safe, but we'll need a valid payment method to keep your
account active.
Questions? Reply here and we'll help.
— [Product] Team
```
### Email 3: Urgency (Day 7)
**Tone:** Direct, clear consequences.
```
Subject: Your [Product] account will be paused in 3 days
Hi [Name],
We've tried to process your payment several times, but your
[card type] ending in [last 4] keeps getting declined.
If we don't receive payment by [date], your account will be
paused and you'll lose access to:
• [Key feature/data they use]
• [Their projects/workspace]
• [Team access for X members]
[Update Payment Method Now →]
Your data won't be deleted — you can reactivate anytime by
updating your payment method.
— [Product] Team
```
### Email 4: Final Warning (Day 10)
**Tone:** Final, clear, no guilt.
```
Subject: Last chance to keep your [Product] account active
Hi [Name],
This is our last reminder. Your payment of $[amount] is past
due, and your account will be paused tomorrow ([date]).
[Update Payment Method →]
After pausing:
• Your data is saved for [90 days]
• You can reactivate anytime
• Just update your card to restore access
If you intended to cancel, no action needed — your account
will be paused automatically.
— [Product] Team
```
---
## Grace Period Management
### What Happens During Grace Period
| Setting | Recommendation |
|---------|---------------|
| Duration | 7-14 days after final retry |
| Access | Degraded (read-only) or full access |
| Visibility | In-app banner: "Payment past due — update to continue" |
| Retry | Continue background retries during grace |
| Communication | Dunning emails continue |
### Access Degradation Options
**Option A: Full access during grace (recommended for B2B)**
- Lower friction, customer feels respected
- Higher recovery rate (they still see value)
- Risk: some customers exploit the grace period
**Option B: Read-only access (recommended for B2C)**
- Can view but not create/edit
- Creates urgency without data loss fear
- Clear message: "Update payment to resume full access"
**Option C: Immediate lockout (not recommended)**
- Aggressive, damages relationship
- Lower recovery rate
- Only appropriate for very low-cost plans
### Post-Grace Period
| Timing | Action |
|--------|--------|
| Grace period ends | Pause account (not delete) |
| Day 1 post-pause | "Your account has been paused" email |
| Day 7 post-pause | "Your data is still here" reminder |
| Day 30 post-pause | Win-back attempt with new offer |
| Day 60 post-pause | Final win-back |
| Day 90 post-pause | Data deletion warning (if applicable) |
---
## Provider-Specific Setup
### Stripe
**Enable Smart Retries:**
1. Dashboard → Settings → Billing → Subscriptions and emails
2. Enable "Smart Retries" under retry rules
3. Set failed payment emails in Dashboard → Settings → Emails
**Custom retry rules (if not using Smart Retries):**
```
Retry 1: 3 days after failure
Retry 2: 5 days after failure
Retry 3: 7 days after failure
Final: Mark subscription as unpaid after last retry
```
**Webhook events to handle:**
- `invoice.payment_failed` — trigger dunning
- `invoice.paid` — cancel dunning, restore access
- `customer.subscription.updated` — status changes
- `customer.subscription.deleted` — final cancellation
### Chargebee
**Built-in dunning:**
1. Settings → Configure Chargebee → Retry Settings
2. Configure retry attempts and intervals
3. Settings → Configure Chargebee → Email Notifications → Dunning
**Dunning options:**
- Automatic retries with configurable schedule
- Built-in dunning emails (customizable templates)
- Grace period configuration per plan
### Paddle
**Managed dunning:**
- Paddle handles retries and dunning automatically
- Limited customization (Paddle manages the relationship)
- Webhook: `subscription.payment_failed`, `subscription.cancelled`
- Best for hands-off approach
### Recurly
**Revenue Recovery:**
1. Configuration → Dunning Management
2. Set retry schedule per plan
3. Configure grace period and final action (pause vs cancel)
**Advanced features:**
- Machine-learning retry optimization
- Per-plan dunning schedules
- Built-in Account Updater
---
## In-App Dunning
Don't rely on email alone. Show payment failures in the app:
### Banner Pattern
```
┌──────────────────────────────────────────────────────┐
│ ⚠ Your payment of $29 failed. Update your card to │
│ avoid losing access. [Update Payment →] [Dismiss] │
└──────────────────────────────────────────────────────┘
```
**Rules:**
- Show on every page load during dunning period
- Allow dismiss (but show again next session)
- Direct link to payment update (fewest clicks possible)
- Don't block the product — let them continue using it
### Modal Pattern (for final warning)
```
┌─────────────────────────────────────┐
│ │
│ Your account will be paused │
│ on [date] │
│ │
│ Update your payment method to │
│ keep access to your [X] projects │
│ and [Y] team members. │
│ │
│ [Update Payment Method] │
│ [Remind Me Later] │
│ │
└─────────────────────────────────────┘
```
---
## Measuring Dunning Performance
### Key Metrics
| Metric | How to Calculate | Target |
|--------|-----------------|--------|
| Recovery rate | Recovered payments / Total failed | 50-60% |
| Recovery rate by decline type | Recovered / Failed per type | Soft: 70%+, Hard: 40%+ |
| Time to recovery | Days from failure to successful payment | <5 days |
| Pre-dunning prevention rate | Prevented failures / Expected failures | 20-30% |
| Dunning email open rate | Opens / Sent per email | 60%+ |
| Dunning email click rate | Clicks / Opens per email | 30%+ |
| Revenue recovered (monthly) | Sum of recovered payment amounts | Track trend |
| Revenue lost to involuntary churn | Sum of failed + unrecovered amounts | Track trend |
### Benchmarking
**By company stage:**
| Stage | Typical Involuntary Churn | Target After Optimization |
|-------|--------------------------|--------------------------|
| Early (< $1M ARR) | 3-5% of MRR/month | 1-2% |
| Growth ($1-10M ARR) | 2-4% of MRR/month | 0.5-1.5% |
| Scale ($10M+ ARR) | 1-3% of MRR/month | 0.3-0.8% |
### ROI Calculation
```
Monthly failed payment MRR: $10,000
Current recovery rate: 30% ($3,000 recovered)
Target recovery rate: 60% ($6,000 recovered)
Monthly improvement: $3,000/month
Annual improvement: $36,000/year
Cost of dunning optimization: ~$200-500/month (tooling)
ROI: 6-15x
```