Files
skills/public/dunning-playbook.md
zeekayandHanzo Dev 65c3b27843 160 marketing, growth and PM skills, on our own connectors
Four MIT collections ported — growthOS, openclaw-marketing-skills,
Marketing-Skills and pm-skills — as 160 skills, 12 agents and 45
commands, each naming its origin in its own frontmatter so the tree can
be checked against THIRD_PARTY_NOTICES rather than trusted. Sixteen names
appeared in more than one collection and none of the copies were
identical; the longest wins, which lands on the more developed text where
they genuinely diverge.

A fifth collection is deliberately absent. awesome-growth-hacking-skills
carries NO licence, which leaves its author every right by default — and
it is a list of links rather than a collection of skills, so there is
nothing in it to port and no permission to port it with. It is cited as a
directory to read.

THE CONNECTOR SKILLS ARE REWRITTEN, not ported. They arrived installing
vendor SDKs, running OAuth flows of their own, and ending with long-lived
credentials in JSON files under .agents/ and ~/.growthos/ at mode 600.
That is a secret on a disk with no rotation path, protected from other
users and not from the agent — and one auth implementation per skill.
Hanzo holds these connectors in Go, per user, sealed in KMS, so `connect`
is the one home for the flow and the platform skills defer to it by
provider id: google_ads, meta_ads, x. It is reachable as HTTP or as MCP
tools at api.hanzo.ai/v1/mcp — the same routes, typed once in Go, so a
tool and a curl cannot disagree.

Two had nothing real behind them and now say so. There is no
search_console provider, so that skill names what does answer the same
questions (google_analytics, google_bigquery) and states that the remedy
is a provider in hanzoai/cloud rather than a vendor SDK here. And
getxapi-connect was a wrapper around a paid reseller of X's public data
with the vendor's key in an env var; it is `listen` now, on our own x
connector — a skill named after a vendor makes the vendor the capability
and dies with it.

The skills referenced paths that only existed inside the source repo, so
the shared material they read is ported to reference/ and the paths
rewritten. Three skills need the growthOS APPLICATION rather than its
data; per the estate's own split an application belongs in hanzoai/ads,
social, email or sms as a cloud plugin, so those three say what they need
instead of carrying an import that resolves to nothing.

Third-party product names are out of our prose and kept in the notices,
which is where the licence requires them and the only place they belong.
A skill's persona names a role, not somebody else's product.


Co-authored-by: Hanzo Dev <[email protected]>
2026-09-15 01:27:26 -07:00

12 KiB

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