Dunning and Churn Recovery

Pathrule1 Rule • 1 Memory • 2 Skills

Dunning and churn recovery is a stateful customer workflow, not a loop that charges every declined payment on the same schedule. This bundle separates recoverable and hard failures, consumes provider events idempotently, coordinates notifications and access, and measures recovery by cohort. Unlike Subscriptions and Usage Billing, it owns failed-payment recovery rather than metering and entitlement calculation.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

design-dunning-journey

src/

webhooks/

Drive dunning from idempotent billing events

billing/

dunning/

Failure reason selects the recovery path

audit-dunning-performance

Rules

Drive dunning from idempotent billing events/src/webhookshighstrictProvider events advance a stored recovery state machine and duplicate or out-of-order delivery cannot repeat effects.

1	Provider events advance a stored recovery state machine and duplicate or out-of-order delivery cannot repeat effects. A webhook handler that sends mail, changes access, and schedules work directly will duplicate side effects and regress state when events retry or arrive late. Enforce this boundary in /src/webhooks so invalid work stops before it reaches another subsystem or creates an externally visible side effect.
2
3	- Persist the provider event identifier and normalized invoice or subscription version before dispatching effects.
4	- Compare the incoming provider state with the local transition table and ignore stale transitions while retaining them for audit.
5	- Use stable idempotency keys for notices, retry jobs, access changes, and provider mutations.
6	- Re-fetch authoritative billing state when event ordering is ambiguous instead of guessing from delivery time.
7
8	Verification: Replay, reorder, and concurrently deliver failure, update, paid, and canceled events; confirm each state and side effect occurs exactly once.

Memories

Failure reason selects the recovery path/src/billing/dunningA temporary issuer decline, expired credential, missing method, required customer action, and terminal account state do not benefit from the same retry cadence.

1	A temporary issuer decline, expired credential, missing method, required customer action, and terminal account state do not benefit from the same retry cadence. Normalize provider details into a small internal failure taxonomy without exposing sensitive payment data.
2
3	Use automatic retries only for categories the provider and payment method can recover without new customer input. Send customers to a short-lived authenticated update or action flow when intervention is required. Stop futile retries and switch messaging when the provider marks a hard decline or no usable method exists. Keep the decision explicit at /src/billing/dunning; moving it into an incidental caller makes behavior depend on which route happened to execute first.
4
5	See /src/jobs for retry scheduling and /src/webhooks for authoritative state transitions. That related boundary consumes this decision and carries the evidence that proves it still holds.

Skills

design-dunning-journey/rootDesign a failed-payment journey with retry, communication, access, and recovery states for each failure class.

1	---
2	name: design-dunning-journey
3	description: Design a failed-payment journey with retry, communication, access, and recovery states for each failure class.
4	---
5
6	# Design Dunning Journey
7
8	Run this procedure whenever the governed surface changes or its operational evidence becomes stale.
9
10	1. Map provider invoice and subscription states into the product's recovery states, including temporary, action-required, hard-failure, recovered, and terminal outcomes.
11	2. Choose retry ownership and cadence per payment method and failure class; never run an application scheduler on top of provider-managed retries unintentionally.
12	3. Define notice timing, channel, authenticated recovery action, grace behavior, access changes, and support escalation for each transition.
13	4. Test event reordering, duplicate delivery, customer update during retry, late payment, cancellation, and payment after access restriction.
14
15	Record the decision, failed checks, and follow-up owner with the change. A successful run leaves reproducible evidence that another reviewer can inspect without repeating the investigation from memory.

audit-dunning-performance/src/billing/dunningAudit recovery performance by failure reason, cohort, retry path, message, and customer outcome.

1	---
2	name: audit-dunning-performance
3	description: Audit recovery performance by failure reason, cohort, retry path, message, and customer outcome.
4	---
5
6	# Audit Dunning Performance
7
8	Run this procedure whenever the governed surface changes or its operational evidence becomes stale.
9
10	1. Select a closed cohort and reconcile failed invoices, attempts, customer actions, payments, cancellations, credits, and access outcomes against provider records.
11	2. Segment temporary versus hard failures, payment method, tenure, plan, geography where permitted, and the exact recovery journey received.
12	3. Measure recovered revenue and customers without counting late duplicates, write-offs, or payments unrelated to the failed invoice.
13	4. Identify harmful or futile steps, document an experiment with guardrails, and monitor complaints, opt-outs, and support load alongside recovery.
14
15	Record the decision, failed checks, and follow-up owner with the change. A successful run leaves reproducible evidence that another reviewer can inspect without repeating the investigation from memory.

Why this pattern

Agents retry every failure uniformly, send duplicate notices, revoke access from stale local state, or recover payment without restoring the customer lifecycle coherently.

Built for Subscription teams reducing involuntary churn after recurring payment failures.

Keeps your assistant from:

Retrying hard declines without a new payment method
Duplicate notices and state transitions from webhook retries
Access revoked or restored from an out-of-order billing event

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25