Step 1 — Resume the ledger
Read .kortix/memory/payment-recovery-ledger.md. For every subscription
already tracked, note its current rung, the timestamp of its last action, and
its next-eligible-escalation time. Anything not yet on the ledger is a
candidate for Step 2.
Step 2 — Pull failed invoices and subscription state from Stripe
Query Stripe for invoices in a failed/past-due state and their parent
subscriptions. For each:
- New failure (not on the ledger) → start at rung 1 (smart retry).
- Already on the ledger → check whether
now >= next-eligible time; if
not, leave it alone this run.
- No longer failing (invoice paid, subscription active/current) → go to
Step 6 (close out), regardless of rung.
Step 3 — The ladder
| Rung |
Name |
Action |
Minimum wait before this rung |
| 1 |
Smart retry |
Retry the failed charge against the existing payment method via Stripe (off-session), no email sent yet |
Immediately on first failure |
| 2 |
Payment reminder |
Friendly email: the charge didn't go through, here's the amount and a pay link |
24h after rung 1 if still failing |
| 3 |
Update-your-card notice |
Firmer email naming the likely cause (expired/declined card) with a direct link to update the payment method |
48h after rung 2 if still failing |
| 4 |
Final notice |
Clear, professional email stating this is the last automated reminder before the account needs manual attention |
72h after rung 3 if still failing |
A subscription advances at most one rung per run, and only once its
minimum wait has elapsed. Never send two rungs' worth of email in the same
run, and never re-send the same rung.
Step 4 — Send the rung's email
Send the exact email for the current rung via {{dunning_channel}}, addressed
to the subscription's billing contact. Keep the tone matched to the rung —
rung 2 is a nudge, rung 4 is unambiguous but still professional, never
threatening. Every send is logged to the ledger with the rung and timestamp.
Step 5 — Rung 4 is the ceiling
Once a subscription has received the final notice and the invoice is still
unpaid, do not create a rung 5. Mark it awaiting-human on the ledger and
surface it in the Slack summary every run until a person acts or it pays.
Never cancel the subscription, issue a credit, or process a refund — that
decision, and the action, belongs to a human.
Step 6 — Close out on payment
If a tracked subscription's invoice has been paid (checked fresh from Stripe
every run, not assumed), mark it recovered on the ledger with the rung it
was on when it cleared, stop sending it anything, and report it as a recovery
in the summary.
Step 7 — Post the summary
Post one message per run to {{alert_channel}}: subscriptions that advanced a
rung (with new rung), subscriptions newly at awaiting-human, and
subscriptions that recovered since the last run. Omit subscriptions with no
change.
Step 8 — Update the ledger
Write the full current state back to .kortix/memory/payment-recovery-ledger.md
(see <ledger-format>) before ending the turn.
1---2name: dunning-escalation3description: Per-subscription dunning ladder for recovering failed Stripe payments — smart retry, payment reminder, update-your-card notice, final notice — with minimum wait times between rungs, the ledger format that carries state across hourly runs, and the stop-for-human line at cancellation, credits, and refunds.4---56<skill name="dunning-escalation">78<overview>9Turn a failed Stripe invoice into a worked recovery instead of a silent lapse.10An hourly cron re-prompts one persistent session; this skill defines the fixed11four-rung ladder each failed subscription climbs, how long to wait between12rungs, and what to send at each one. The ledger is what makes this a ladder and13not a loop — without it, every run would just resend rung one forever.14</overview>1516<when-to-load>17- The hourly cron fires the payment-recovery sweep.18- A human asks why a specific subscription is or isn't being emailed, or what19 rung it's on.20</when-to-load>2122<workflow>2324## Step 1 — Resume the ledger2526Read `.kortix/memory/payment-recovery-ledger.md`. For every subscription27already tracked, note its current rung, the timestamp of its last action, and28its next-eligible-escalation time. Anything not yet on the ledger is a29candidate for Step 2.3031## Step 2 — Pull failed invoices and subscription state from Stripe3233Query Stripe for invoices in a failed/past-due state and their parent34subscriptions. For each:3536- **New failure** (not on the ledger) → start at rung 1 (smart retry).37- **Already on the ledger** → check whether `now >= next-eligible time`; if38 not, leave it alone this run.39- **No longer failing** (invoice paid, subscription active/current) → go to40 Step 6 (close out), regardless of rung.4142## Step 3 — The ladder4344| Rung | Name | Action | Minimum wait before this rung |45|---|---|---|---|46| 1 | Smart retry | Retry the failed charge against the existing payment method via Stripe (off-session), no email sent yet | Immediately on first failure |47| 2 | Payment reminder | Friendly email: the charge didn't go through, here's the amount and a pay link | 24h after rung 1 if still failing |48| 3 | Update-your-card notice | Firmer email naming the likely cause (expired/declined card) with a direct link to update the payment method | 48h after rung 2 if still failing |49| 4 | Final notice | Clear, professional email stating this is the last automated reminder before the account needs manual attention | 72h after rung 3 if still failing |5051A subscription advances **at most one rung per run**, and only once its52minimum wait has elapsed. Never send two rungs' worth of email in the same53run, and never re-send the same rung.5455## Step 4 — Send the rung's email5657Send the exact email for the current rung via {{dunning_channel}}, addressed58to the subscription's billing contact. Keep the tone matched to the rung —59rung 2 is a nudge, rung 4 is unambiguous but still professional, never60threatening. Every send is logged to the ledger with the rung and timestamp.6162## Step 5 — Rung 4 is the ceiling6364Once a subscription has received the final notice and the invoice is still65unpaid, do **not** create a rung 5. Mark it `awaiting-human` on the ledger and66surface it in the Slack summary every run until a person acts or it pays.67Never cancel the subscription, issue a credit, or process a refund — that68decision, and the action, belongs to a human.6970## Step 6 — Close out on payment7172If a tracked subscription's invoice has been paid (checked fresh from Stripe73every run, not assumed), mark it `recovered` on the ledger with the rung it74was on when it cleared, stop sending it anything, and report it as a recovery75in the summary.7677## Step 7 — Post the summary7879Post one message per run to {{alert_channel}}: subscriptions that advanced a80rung (with new rung), subscriptions newly at `awaiting-human`, and81subscriptions that recovered since the last run. Omit subscriptions with no82change.8384## Step 8 — Update the ledger8586Write the full current state back to `.kortix/memory/payment-recovery-ledger.md`87(see `<ledger-format>`) before ending the turn.8889</workflow>9091<ledger-format>92Lives at `.kortix/memory/payment-recovery-ledger.md`. One row per subscription93currently or recently on the ladder: subscription ID, customer, current rung94(1–4, or `recovered` / `awaiting-human`), last action + timestamp, next-eligible95escalation time, and outcome once resolved (`recovered` with the rung it paid96at, or `awaiting-human` with the date it hit rung 4). Prune a row only after97it's been `recovered` for a full cycle, so a bounce-back failure is still98recognized as a returning case rather than a brand-new one.99</ledger-format>100101<guardrails>102- **Smart-retry and dunning only.** The only Stripe write this skill performs103 is retrying an existing failed charge. The only customer-facing action is104 sending one of the four ladder emails. Nothing else is in scope.105- **Never cancel, credit, or refund.** Regardless of how long a subscription106 has been failing, ending it, crediting it, or refunding it requires a human107 and is never done by this skill.108- **One rung per run, minimum wait enforced.** A subscription cannot skip a109 rung or be re-messaged before its wait time elapses, even if a run is110 manually re-triggered.111- **Stops immediately on payment.** A paid invoice ends the ladder for that112 subscription on the very next check — no extra emails, no delay.113- **Scoped secrets.** Stripe access is brokered through the connector; no raw114 key is ever shown to the model or written to logs.115- **Ledger is the source of truth for state.** Between runs, nothing about116 ladder position is inferred or guessed — it comes from the ledger, checked117 against fresh Stripe state.118</guardrails>119120</skill>
kortix-ai