| name | dunning-action-planner |
| description | Takes a scored dunning cohort (from dunning-cohort-builder) and applies error-code playbooks to produce three outputs: (1) a prioritised action list per subscription, (2) an error-code segment summary table, and (3) playbook reference cards grouped by error code. Propose-only — all recommendations require human approval. Use after dunning-cohort-builder has run, or when the user asks for a recommended action plan for at-risk subscriptions.
|
Dunning Action Planner
Apply error-code playbooks and produce the prioritised remediation report.
Error-Code Playbooks
For each gateway_error_code, apply the strategy below. If the code is not in this
table, use the unknown row.
| Error Code | Root Cause | Owner | Primary Action | Secondary Action | Retry Delay (days) | Auto-Recoverable | Escalate if retry ≥ | Incentive |
|---|
card_expired | Card past expiry date | customer | send_card_update_request | escalate_to_support | 3 | No | 2 | none |
insufficient_funds | Account lacks funds | customer | retry_after_delay | offer_pause_or_downgrade | 7 | Yes | 3 | 10% off on resume |
do_not_honor | Bank declined (generic) | customer | send_card_update_request | escalate_to_support | 5 | No | 2 | none |
card_declined | Bank declined (unspecified) | customer | send_card_update_request | offer_alternative_payment_method | 5 | No | 2 | none |
processing_error | Transient gateway/network error | auto | retry_immediately | retry_after_delay | 1 | Yes | 4 | none |
authentication_required | 3DS / SCA required | customer | send_authentication_link | request_new_payment_method | 2 | No | 2 | none |
invalid_card_number | Card number invalid or reissued | customer | send_card_update_request | escalate_to_support | 0 | No | 1 | none |
lost_card | Card reported lost | support | escalate_to_support | request_new_payment_method | 0 | No | 1 | none |
stolen_card | Card reported stolen | support | escalate_to_support | request_new_payment_method | 0 | No | 1 | none |
fraud_suspected | Transaction flagged as fraud | support | manual_triage | contact_customer_via_alternate_channel | 0 | No | 1 | none |
transaction_not_permitted | Card type / account restriction | customer | request_alternative_payment_method | escalate_to_support | 0 | No | 1 | none |
currency_not_supported | Card can't transact in billing currency | support | review_billing_currency_config | request_alternative_payment_method | 0 | No | 1 | none |
unknown | Code not recognised or not returned | support | retry_after_delay | manual_triage | 3 | Yes | 3 | none |
Retry delay of 0 means do not retry — the customer or support must act first.
Communication templates by action:
| Primary Action | Customer-facing subject line |
|---|
| send_card_update_request | "Action required: Update your payment method" |
| retry_after_delay | "We'll retry your payment shortly — no action needed" |
| offer_pause_or_downgrade | "We couldn't process your payment — here are your options" |
| send_authentication_link | "Action required: Verify your payment to keep your subscription active" |
| request_alternative_payment_method | "Your card can't be used — please add a new payment method" |
| retry_immediately | (silent — no email for auto-retry) |
| escalate_to_support | "[Internal] Payment failure requires manual review" |
| manual_triage | "[Internal] Payment failure requires manual review" |
Step 0 — Setup
Input: The JSON cohort emitted by dunning-cohort-builder. If called standalone,
run dunning-cohort-builder first.
Step 1 — Apply playbooks to each subscription
Look up each subscription's gateway_error_code in the playbook table. Apply:
| Field | Value |
|---|
playbook_owner | from table |
primary_action | from table |
secondary_action | from table |
suggested_retry_delay_days | from table |
incentive | from table |
auto_recoverable | from table |
needs_escalation | true if retry_number ≥ escalate_if_retry_gte |
next_suggested_retry | today + retry_delay days (null if retry_delay == 0) |
Escalation override
If needs_escalation: true → override primary_action to escalate_to_support and append flag "⚠ Escalation threshold reached".
High-value note
If is_high_value: true → append note "★ High-value customer — prioritise personal outreach over automated message".
Step 2 — Error-code segment summary table
For each error group:
| Column | Value |
|---|
| Error Code | error_code |
| # Subs | subscription_count |
| Total at Risk | total_bcy_amount |
| P0 | p0_count |
| Avg LTV | avg_ltv |
| Avg LTD (days) | avg_ltd |
| Owner | from playbook table |
| Primary Action | from playbook table |
| Auto-Recover? | ✓ or ✗ |
Sort by total_bcy_amount DESC. Add a totals row at the bottom.
Step 3 — Prioritised action list
Flat list of all subscriptions ordered by: priority tier (P0 first) then composite_score DESC.
Columns: Priority, Score, Sub#, Customer, Amount, LTV, LTD, Retry#, Error Code, Action, Notes
Annotations: ★ high-value · ⚠ needs escalation · ↻ auto-recoverable and no escalation
Priority indicators: 🔴 P0 · 🟠 P1 · 🟡 P2 · ⚪ P3
Step 4 — Playbook reference cards
One card per distinct error code in the cohort, ordered by total_bcy_amount DESC:
### <error_code> (<count> subscriptions · <total_bcy> at risk)
**Root cause:** ...
**Owner:** customer | support | auto
**Primary action:** ... **Secondary:** ...
**Retry delay:** N days **Auto-recoverable:** Yes / No
**Escalate if retries ≥:** N
**Incentive:** ... or None
**Communication:** <subject line or "Silent auto-retry">
Step 5 — Action metrics
total_needs_escalation count where needs_escalation == true
total_auto_recoverable count where auto_recoverable == true AND !needs_escalation
total_requires_customer_action count where owner == "customer"
total_requires_support_action count where owner == "support"
p0_high_value_overlap count where priority_tier == "P0" AND is_high_value == true
estimated_recoverable_revenue sum of bcy_amount where auto_recoverable == true
estimated_at_risk_manual sum of bcy_amount where auto_recoverable == false
Edge Cases
- Code not in table: apply
unknown playbook; add flag "Error code not recognised — applied default 'unknown' strategy".
- retry_delay == 0: set
next_suggested_retry: null; note "Do not retry — action required first".
- All subscriptions P0: add executive warning
"⚠ All dunning subscriptions are P0 — immediate triage required".
retry_immediately action: no customer email — annotate "Silent auto-retry".
