Shopify Subscription Dunning: Complete Setup Guide for Recharge and Stripe
Dunning is the automated sequence of payment retries and customer communications that runs after a subscription billing failure. For Shopify merchants using Recharge, dunning is configured in Recharge Admin with per-error-type rules and up to 8 retry attempts. For Stripe-native subscriptions, Smart Retries uses ML to pick optimal retry timing. The critical mistake most merchants make is applying the same retry cadence to every error type. PAYMENT_METHOD_REVOKED is permanently invalid — retrying it wastes attempts and delays recovery. INSUFFICIENT_FUNDS benefits from a 3–5 day retry delay. Here is how to configure each correctly.
What is subscription dunning and why do default settings cause revenue loss?
Dunning is the automated process of retrying failed subscription payments and notifying customers. Every subscription platform has some form of dunning built in. The problem is default settings apply the same retry cadence to every failure type, which is wrong. A CARD_DECLINED from a temporary bank issue should be retried after 3 days. A PAYMENT_METHOD_REVOKED should trigger an immediate payment update email — retrying the revoked token will fail every time.
Default Recharge dunning settings retry all failures uniformly, regardless of error_type. This burns through retry attempts on permanently invalid tokens and delays recovery for temporarily insufficient funds. Configuring dunning per error type is the single highest-leverage change a Shopify subscription merchant can make to improve payment recovery rates.
How do you configure dunning in Recharge for different error types?
In Recharge Admin, navigate to Settings > Dunning. The default schedule retries failed charges at days 1, 3, 5, 7 after failure. For INSUFFICIENT_FUNDS, adjust the schedule to retry at days 3, 7, and 12 — aligned with common payday cycles. Avoid retrying on day 1; insufficient funds rarely resolves in 24 hours.
For PAYMENT_METHOD_REVOKED, configure Recharge to skip retries and immediately send a payment method update email. Retrying a revoked Shop Pay token is guaranteed to fail. The Recharge dunning settings allow per-error-type actions — set PAYMENT_METHOD_REVOKED to trigger the customer payment update flow immediately, bypassing the retry schedule entirely.
How does Stripe handle failed subscription payment retries?
Stripe's revenue recovery feature includes Smart Retries, which uses ML models to determine the optimal time to retry a failed subscription invoice. Smart Retries is enabled in Stripe Dashboard under Subscriptions > Subscription settings > Smart Retries. When enabled, Stripe listens to the invoice.payment_failed webhook and schedules retries automatically.
Stripe also classifies failures into hard and soft declines. Hard declines — such as lost_card, stolen_card, and do_not_honor with no retry advice — are not retried by Smart Retries. Soft declines — such as insufficient_funds and issuer_not_available — are retried with optimized timing. When a Stripe invoice fails, the invoice.payment_action_required webhook fires if 3DS authentication is required; merchants must handle this separately by sending the customer a confirmation URL.
What happens when max retries are reached and how do you reconcile subscription state?
When Recharge exhausts all retry attempts, it fires the charge/max_retries_reached webhook and cancels the subscription on its side. The critical issue: Shopify's subscription contract may still show ACTIVE. At this point, you have a ghost subscription — the customer may be receiving product while no payment is collected.
Reconciliation requires calling Shopify's subscriptionContractUpdate GraphQL mutation to set the contract status to PAUSED or CANCELLED, matching Recharge's state. Without this step, Shopify's records are inaccurate and the customer may continue receiving service without paying. AltorLab detects these MAX_RETRIES_REACHED states and flags the Shopify/Recharge mismatch automatically so merchants can reconcile before more inventory is shipped.
How do you build a dunning strategy when using both Recharge and Stripe together?
When using Recharge as your subscription app and Stripe as the payment processor, both platforms have retry logic. Recharge's dunning retries the charge on its schedule. Stripe Smart Retries operates at the invoice level if you're using Stripe Billing directly. Using both simultaneously can result in conflicting retry timing — Recharge attempts at day 3 while Stripe independently retries at a different interval.
The cleanest approach: disable Stripe Smart Retries and rely entirely on Recharge's dunning if Recharge is managing subscription billing. If using Shopify Payments (which routes through Stripe), Smart Retries does not apply to Shopify subscription billing attempts — Recharge's dunning is the only retry layer. Configure Recharge dunning per error type as described above and monitor state sync to catch cases where Recharge and Shopify diverge.
Frequently asked questions
How many times does Recharge retry a failed subscription charge by default?
Recharge retries up to 8 times by default, spread across a configurable schedule. The exact retry days depend on your dunning settings in Recharge Admin > Settings > Dunning. After the maximum attempts are exhausted, Recharge fires the charge/max_retries_reached webhook and stops automatic retries.
Should dunning settings be different for credit card declines vs Shop Pay revocations?
Yes, absolutely. Credit card declines like INSUFFICIENT_FUNDS benefit from a 3–5 day retry delay. Shop Pay revocations (PAYMENT_METHOD_REVOKED) indicate a permanently invalid token — retrying is pointless. Configure Recharge to skip retries for PAYMENT_METHOD_REVOKED and trigger a payment update email immediately instead.
What is the difference between Recharge dunning and Stripe Smart Retries?
Recharge dunning retries charges on a merchant-configured schedule with configurable per-error-type rules. Stripe Smart Retries uses ML to pick optimal retry timing for Stripe Billing invoices. If Recharge manages your subscription billing via Shopify Payments, Smart Retries does not apply — only Recharge's dunning schedule runs.
How do I prevent Shopify subscription contracts from showing active after max retries?
After Recharge fires charge/max_retries_reached, call Shopify's subscriptionContractUpdate GraphQL mutation to set the contract status to PAUSED or CANCELLED. Without this step, Shopify shows the subscription active while Recharge has stopped retrying — creating a ghost subscription that leaks revenue and inventory.
Does AltorLab detect when dunning is misconfigured?
AltorLab detects the symptoms of dunning misconfiguration: subscriptions in MAX_RETRIES_REACHED state, mismatches between Recharge and Shopify contract state, and PAYMENT_METHOD_REVOKED errors that have been retried multiple times. These patterns indicate that dunning settings are not aligned with the underlying error types.