Payment Retries re-charge failed subscription renewal payments automatically on a back-off schedule. When a retry succeeds, the subscription returns to
active, with no customer action and no integration work.What Are Payment Retries?
When a subscription renewal payment fails, the subscription moves toon_hold, or to past_due if you set a grace period. With Payment Retries on, Dodo Payments re-charges the customer’s saved payment method on a schedule until a charge succeeds or the recovery window closes.
Retries recover revenue lost to temporary failures, such as a temporary hold on the card, insufficient funds that the customer tops up later, or a transient network error. The customer gets no email and doesn’t need to change anything.
Payment Retries apply only to subscription renewal payments. The first payment of a subscription (mandate setup), one-time payments, plan-change charges, and on-demand charges are not retried.
How Payment Retries Work
1
Renewal fails
A subscription renewal payment fails, and the subscription moves to
on_hold, or to past_due during a grace period.2
Retryability check
Dodo Payments checks the failure’s error code. Soft declines, such as insufficient funds, a generic decline, or a processing or network error, are retryable. Hard declines end the retry chain, because another attempt won’t change the outcome. A failure without an error code counts as a hard decline.
3
Scheduled retry
If the decline is retryable and the next attempt fits in the recovery window, Dodo Payments schedules it. Each retry is an off-session charge to the customer’s saved payment method, and each delay counts from the previous failure.
4
Recovery
On the first successful retry, the subscription returns to
active, and the next billing date moves to one billing period after the successful retry. If the window closes before any retry succeeds, retries stop and the subscription keeps its status, such as on_hold.Configuring Payment Retries
Turn on and configure Payment Retries in Settings → Recovery in your dashboard.
Payment Retries settings under Settings → Recovery
The recovery window starts when the invoice for the failed renewal is created. Dodo Payments schedules an attempt only if the sum of all delays up to that attempt fits inside the window, and only while the window is still open.
Retry Schedule
Retries back off progressively. Dodo Payments makes up to 8 attempts, as long as each one fits in your recovery window:Subscription Status Transitions
Retries move the subscription between these statuses:When a subscription is cancelled, its retry chain ends and no further attempts are made. Every other status (
on_hold, past_due, expired, pending, failed) keeps retrying, because the open renewal invoice is a debt for a period the customer already used. Retries also stop when the invoice is paid another way, for example after the customer updates their payment method, or when you add the customer to your blocklist.Subscription Webhook Payloads
View the full webhook payload schemas for subscription lifecycle events.
Retryable vs. Non-Retryable Failures
The error code of the most recent failure decides whether the chain continues:Retrying a hard decline won’t change the outcome, so the chain ends as soon as a hard decline occurs. Pair Payment Retries with Subscription Dunning to ask the customer for a new payment method in those cases. For the type of every code, see Transaction Failures.
Retrying on Demand
You don’t have to wait for the next scheduled attempt. While a subscription ison_hold, you can send a retry from the failed payment’s detail page in the dashboard, or with POST /payments/{payment_id}/retry. Manual retries run independently of the schedule: they don’t use up or move an automatic attempt, and they work even when Payment Retries are off. See Manual Payment Retry.
Payment Retries vs. Dunning
Payment Retries and Subscription Dunning recover different kinds of failure:
Turn on both for the widest coverage: automatic retries catch transient failures, and dunning brings back customers whose payment method needs replacing.
Related
Manual Payment Retry
Send a retry right away instead of waiting for the next scheduled attempt.
Subscription Dunning
Email sequences that ask customers to update their payment method.
Abandoned Cart Recovery
Recover abandoned or failed checkouts with recovery emails.
Subscriptions
The subscription states that recovery flows move between.
Subscription Webhooks
React to
subscription.on_hold and subscription.active events.