Files
skills/public/dunning-playbook.html
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

432 lines
26 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>dunning-playbook</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/dunning-playbook.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/dunning-playbook">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/dunning-playbook.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>dunning-playbook</h1><p class="lede">Complete guide to recovering failed payments and reducing involuntary churn.</p><h1>Dunning Playbook</h1>
<p>Complete guide to recovering failed payments and reducing involuntary churn.</p>
<hr>
<h2>Why Dunning Matters</h2>
<ul><li>Failed payments cause 30-50% of all subscription churn</li><li>Most failed payments are recoverable with the right strategy</li><li>Subscription businesses lose an estimated $129 billion annually to involuntary churn</li><li>Effective dunning recovers 50-60% of failed payments</li></ul>
<hr>
<h2>The Dunning Timeline</h2>
<pre><code>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</code></pre>
<hr>
<h2>Pre-Dunning: Prevent Failures Before They Happen</h2>
<h3>Card Expiry Management</h3>
<p>| Timing | Action | |--------|--------| | 30 days before expiry | Email: &quot;Your card ending in 4242 expires next month&quot; | | 15 days before expiry | Email: &quot;Update your payment method to avoid interruption&quot; | | 7 days before expiry | Email: &quot;Your card expires in 7 days — update now&quot; | | 3 days before expiry | In-app banner: &quot;Payment method expiring soon&quot; |</p>
<p><strong>Email template — Card expiring:</strong></p>
<pre><code>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</code></pre>
<h3>Card Updater Services</h3>
<p>Major card networks offer automatic card update programs:</p>
<p>| 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 |</p>
<p><strong>Impact:</strong> Reduces hard declines from expired/replaced cards by 30-50%.</p>
<p><strong>How to enable:</strong></p>
<ul><li><strong>Stripe</strong>: Automatic — enabled by default</li><li><strong>Chargebee</strong>: Enabled through gateway settings</li><li><strong>Recurly</strong>: Built-in, enabled by default</li><li><strong>Braintree</strong>: Contact processor to enable</li></ul>
<h3>Backup Payment Methods</h3>
<p>Prompt for a second payment method:</p>
<ul><li>During signup: &quot;Add a backup payment method&quot; (low conversion)</li><li>After first successful payment: &quot;Protect your account with a backup card&quot; (better timing)</li><li>After a failed payment is recovered: &quot;Add a backup to prevent future interruptions&quot; (best timing — they felt the pain)</li></ul>
<h3>Pre-Billing Notifications</h3>
<p>For annual plans or high-value subscriptions:</p>
<ul><li>Email 7 days before renewal with amount and date</li><li>Include link to update payment method</li><li>Show what&#x27;s included in the renewal</li><li>Required by some regulations for auto-renewals</li></ul>
<hr>
<h2>Smart Retry Strategy</h2>
<h3>Decline Type Classification</h3>
<p>| Code | Type | Meaning | Retry? | |------|------|---------|--------| | <code>insufficient_funds</code> | Soft | Temporarily low balance | Yes — retry in 2-3 days | | <code>card_declined</code> (generic) | Soft | Various temporary reasons | Yes — retry 3-4 times | | <code>processing_error</code> | Soft | Gateway/network issue | Yes — retry within 24h | | <code>expired_card</code> | Hard | Card is expired | No — request new card | | <code>stolen_card</code> | Hard | Card reported stolen | No — request new card | | <code>do_not_honor</code> | Soft/Hard | Bank refused (ambiguous) | Try once more, then ask for new card | | <code>authentication_required</code> | Auth | SCA/3DS needed | Send customer to authenticate |</p>
<h3>Retry Schedule by Provider</h3>
<p><strong>Stripe (Smart Retries — recommended):</strong></p>
<ul><li>Enable &quot;Smart Retries&quot; in Stripe Dashboard → Billing → Settings</li><li>Stripe&#x27;s ML model picks optimal retry timing based on billions of transactions</li><li>Typically 4-8 retry attempts over 3-4 weeks</li><li>Recovers ~15% more than fixed-schedule retries</li></ul>
<p><strong>Manual retry schedule (if no smart retries):</strong></p>
<p>| 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 |</p>
<p><strong>Retry timing insights:</strong></p>
<ul><li>Retry on the same day of month the original payment succeeded</li><li>Retry after common paydays (1st and 15th of the month)</li><li>Avoid retrying on weekends (lower approval rates)</li><li>Morning retries (8-10am local time) perform slightly better</li></ul>
<hr>
<h2>Dunning Email Sequence</h2>
<h3>Email 1: Payment Failed (Day 0)</h3>
<p><strong>Tone:</strong> Friendly, matter-of-fact. No alarm.</p>
<pre><code>Subject: Action needed — your payment didn&#x27;t go through
Hi [Name],
We tried to charge your [card type] ending in [last 4] for your
[Product] subscription ($[amount]), but it didn&#x27;t go through.
This happens sometimes — usually a quick card update fixes it.
[Update Payment Method →]
Your access isn&#x27;t affected yet. We&#x27;ll retry automatically, but
updating your card is the fastest fix.
Need help? Just reply to this email.
— [Product] Team</code></pre>
<h3>Email 2: Reminder (Day 3)</h3>
<p><strong>Tone:</strong> Helpful, slightly more urgent.</p>
<pre><code>Subject: Quick reminder — update your payment for [Product]
Hi [Name],
Just a heads-up — we still haven&#x27;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&#x27;ll need a valid payment method to keep your
account active.
Questions? Reply here and we&#x27;ll help.
— [Product] Team</code></pre>
<h3>Email 3: Urgency (Day 7)</h3>
<p><strong>Tone:</strong> Direct, clear consequences.</p>
<pre><code>Subject: Your [Product] account will be paused in 3 days
Hi [Name],
We&#x27;ve tried to process your payment several times, but your
[card type] ending in [last 4] keeps getting declined.
If we don&#x27;t receive payment by [date], your account will be
paused and you&#x27;ll lose access to:
• [Key feature/data they use]
• [Their projects/workspace]
• [Team access for X members]
[Update Payment Method Now →]
Your data won&#x27;t be deleted — you can reactivate anytime by
updating your payment method.
— [Product] Team</code></pre>
<h3>Email 4: Final Warning (Day 10)</h3>
<p><strong>Tone:</strong> Final, clear, no guilt.</p>
<pre><code>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</code></pre>
<hr>
<h2>Grace Period Management</h2>
<h3>What Happens During Grace Period</h3>
<p>| Setting | Recommendation | |---------|---------------| | Duration | 7-14 days after final retry | | Access | Degraded (read-only) or full access | | Visibility | In-app banner: &quot;Payment past due — update to continue&quot; | | Retry | Continue background retries during grace | | Communication | Dunning emails continue |</p>
<h3>Access Degradation Options</h3>
<p><strong>Option A: Full access during grace (recommended for B2B)</strong></p>
<ul><li>Lower friction, customer feels respected</li><li>Higher recovery rate (they still see value)</li><li>Risk: some customers exploit the grace period</li></ul>
<p><strong>Option B: Read-only access (recommended for B2C)</strong></p>
<ul><li>Can view but not create/edit</li><li>Creates urgency without data loss fear</li><li>Clear message: &quot;Update payment to resume full access&quot;</li></ul>
<p><strong>Option C: Immediate lockout (not recommended)</strong></p>
<ul><li>Aggressive, damages relationship</li><li>Lower recovery rate</li><li>Only appropriate for very low-cost plans</li></ul>
<h3>Post-Grace Period</h3>
<p>| Timing | Action | |--------|--------| | Grace period ends | Pause account (not delete) | | Day 1 post-pause | &quot;Your account has been paused&quot; email | | Day 7 post-pause | &quot;Your data is still here&quot; 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) |</p>
<hr>
<h2>Provider-Specific Setup</h2>
<h3>Stripe</h3>
<p><strong>Enable Smart Retries:</strong></p>
<ol><li>Dashboard → Settings → Billing → Subscriptions and emails</li><li>Enable &quot;Smart Retries&quot; under retry rules</li><li>Set failed payment emails in Dashboard → Settings → Emails</li></ol>
<p><strong>Custom retry rules (if not using Smart Retries):</strong></p>
<pre><code>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</code></pre>
<p><strong>Webhook events to handle:</strong></p>
<ul><li><code>invoice.payment_failed</code> — trigger dunning</li><li><code>invoice.paid</code> — cancel dunning, restore access</li><li><code>customer.subscription.updated</code> — status changes</li><li><code>customer.subscription.deleted</code> — final cancellation</li></ul>
<h3>Chargebee</h3>
<p><strong>Built-in dunning:</strong></p>
<ol><li>Settings → Configure Chargebee → Retry Settings</li><li>Configure retry attempts and intervals</li><li>Settings → Configure Chargebee → Email Notifications → Dunning</li></ol>
<p><strong>Dunning options:</strong></p>
<ul><li>Automatic retries with configurable schedule</li><li>Built-in dunning emails (customizable templates)</li><li>Grace period configuration per plan</li></ul>
<h3>Paddle</h3>
<p><strong>Managed dunning:</strong></p>
<ul><li>Paddle handles retries and dunning automatically</li><li>Limited customization (Paddle manages the relationship)</li><li>Webhook: <code>subscription.payment_failed</code>, <code>subscription.cancelled</code></li><li>Best for hands-off approach</li></ul>
<h3>Recurly</h3>
<p><strong>Revenue Recovery:</strong></p>
<ol><li>Configuration → Dunning Management</li><li>Set retry schedule per plan</li><li>Configure grace period and final action (pause vs cancel)</li></ol>
<p><strong>Advanced features:</strong></p>
<ul><li>Machine-learning retry optimization</li><li>Per-plan dunning schedules</li><li>Built-in Account Updater</li></ul>
<hr>
<h2>In-App Dunning</h2>
<p>Don&#x27;t rely on email alone. Show payment failures in the app:</p>
<h3>Banner Pattern</h3>
<pre><code>┌──────────────────────────────────────────────────────┐
│ ⚠ Your payment of $29 failed. Update your card to │
│ avoid losing access. [Update Payment →] [Dismiss] │
└──────────────────────────────────────────────────────┘</code></pre>
<p><strong>Rules:</strong></p>
<ul><li>Show on every page load during dunning period</li><li>Allow dismiss (but show again next session)</li><li>Direct link to payment update (fewest clicks possible)</li><li>Don&#x27;t block the product — let them continue using it</li></ul>
<h3>Modal Pattern (for final warning)</h3>
<pre><code>┌─────────────────────────────────────┐
│ │
│ 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] │
│ │
└─────────────────────────────────────┘</code></pre>
<hr>
<h2>Measuring Dunning Performance</h2>
<h3>Key Metrics</h3>
<p>| 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 | &lt;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 |</p>
<h3>Benchmarking</h3>
<p><strong>By company stage:</strong></p>
<p>| Stage | Typical Involuntary Churn | Target After Optimization | |-------|--------------------------|--------------------------| | Early (&lt; $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% |</p>
<h3>ROI Calculation</h3>
<pre><code>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</code></pre>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/dunning-playbook.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>