How to set up payment retries
Configure how Roadmap retries failed subscription payments, how an expired card is replaced automatically, when contracts become Failed, and how payment recapture works.
When a subscription payment fails, Roadmap retries the charge on the schedule you configure. This is dunning.
Use this page to set the retry schedule, understand what stops dunning mid-flight, and recover contracts cleanly.
Set up dunning
Everything below lives in Subscriptions → Dunning Settings.
Choose retry timing
Under Retry intervals (days), each row sets the days to wait before the next attempt:
1st retry after: days to wait after the initial payment failure.
2nd retry after: days to wait after retry attempt 1.
3rd retry after: days to wait after retry attempt 2.
With intervals [1, 1, 1] the sequence runs:
initial failure: day
0payment method replaced, if a valid card is available: day
01st retry: day
12nd retry: day
23rd retry: day
3mark as Failed: day
3, after the last retry fails
Automatic Payment Method Replacement
The most common reason a subscription payment fails is a card that has expired or become invalid. Roadmap can fix that on its own, before the first retry attempt.
When a subscription's payment method has expired, been removed, or is no longer valid, Roadmap replaces it with another valid card saved to the customer's Shopify account. If the customer has more than one, the card with the latest expiry date is used.
This runs once a day, two hours after the daily billing run, so the replacement is in place before the first retry. In the timeline panel it appears as Payment method replaced on day 0, between the initial failure and the 1st retry attempt.
If the customer has no other valid card, the subscription is left unchanged and your normal retry schedule applies.
Use the Replace invalid payment methods automatically checkbox to turn it on or off. The card's badge reads Enabled while it is active.
Leaving it on is the recommendation for most stores. It recovers expired-card failures without the customer having to do anything, which is the single biggest cause of involuntary churn.
How dunning runs
Dunning runs daily.
Each day, Roadmap checks previous failed payments and retries any contract due for another attempt.
After the last retry
Roadmap waits 1 hour before marking the contract as Failed.
This gives Shopify time to settle asynchronous payments that may still succeed. If the contract is still unpaid after that hour, Roadmap marks it as Failed.
What cancels dunning mid-flight
The customer skips the delivery
Roadmap stops retrying that cycle.
The customer reschedules
Roadmap stops retrying the original cycle.
If the new billing date also fails, a new dunning cycle starts.
The subscription is manually charged successfully
This happens when you or the customer uses Order now during dunning.
Roadmap treats the older failed cycle as superseded and stops retrying it. The contract exits dunning and is rescheduled according to its delivery frequency, so the next billing date is counted from the successful charge rather than from the cycle that failed.
The customer gets Shopify's standard order confirmation, so the charge itself is no surprise. The shift in their next delivery date is not announced anywhere, so mention it when you recover a contract on their behalf. See Manually charging a subscription (Order Now).
Shop Pay payment update emails
The Shop Pay Payment Update section controls the Roadmap-specific $1 checkout recovery flow.
Check Enable auto Shop Pay update email to send the email whenever a merchant triggers the checkout-link recovery flow from a contract or bulk action. With it off, those actions still create the draft order but send no email.
The email itself lives in Mail Templates → Payment Method Update. Make sure it explains the $1 verification charge and refund clearly.
For the full recovery workflow, see Updating a customer's payment method.
Common configurations
Basic
max retries: 4
intervals:
[1, 1, 1, 1]total window: 4 days
Patient
max retries:
5intervals:
[1, 3, 3, 5, 7]total window:
19days
Where to see dunning status on failing contracts
Mid-dunning contracts are easily found in your 'failing' tab in the subscription manage customer view. Open a contract that is mid-dunning.
The right-hand panel shows the current stage, next retry date, and a timeline of attempts.
The upcoming order's Billing Attempts modal shows each attempt with its timestamp and failure reason.
Troubleshooting
Retries are not happening
Check Enable subscription dunning is on, that you clicked Save Settings, and that What happens after a failed payment matches what you expect.
A subscription failed sooner than expected
Review Maximum retry attempts and Retry intervals (days) against the timeline panel.
A customer was charged on a different card
Their original card was no longer valid, so Automatic Payment Method Replacement moved the subscription onto another card already saved to their account. Working as intended, but the customer is not told, so they may not expect it.
Expired cards are still failing every retry
Check Replace invalid payment methods automatically is on. If it is, those customers have no second card saved, so there is nothing to move them to. Recover them with Updating a customer's payment method.
A recovered contract's next delivery date moved
The contract was charged with Order now while it was dunning. That exits dunning and reschedules the contract from the successful charge, using its delivery frequency.
Shop Pay customers are not receiving update emails
Check Enable auto Shop Pay update email is on, that you clicked Save Settings, and that the Payment Method Update template is correct.
Frequently asked questions
Related guides
Last updated