> For the complete documentation index, see [llms.txt](https://docs.roadmap.so/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roadmap.so/subscriptions/pricing-and-billing/how-to-set-up-payment-retries.md).

# 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**.

{% stepper %}
{% step %}

#### Enable subscription dunning

In **General Settings**, check **Enable subscription dunning**, described in the admin as *automatically retry failed subscription payments*.

This is the master switch. When it is off, failed contracts are not retried at all.
{% endstep %}

{% step %}

#### Set the retry limit

**Maximum retry attempts** is how many times Roadmap tries before giving up. The allowed range is `1–10`.

<figure><img src="https://393112916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJ8asLD4FVCFagK40xEr4%2Fuploads%2FXNXb4iNf16RQbzyOXxLK%2FScreenshot%202026-09-25%20at%204.50.25%E2%80%AFPM.png?alt=media&amp;token=50555c48-98a0-439c-b9bf-f4e11f09bfcb" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### 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 `0`
* payment method replaced, if a valid card is available: day `0`
* 1st retry: day `1`
* 2nd retry: day `2`
* 3rd retry: day `3`
* mark as Failed: day `3`, after the last retry fails
  {% endstep %}

{% step %}

#### Review the timeline

The **What happens after a failed payment** panel on the right lays out the schedule your settings produce, from the initial failure through each retry to the point the contract is marked as Failed. Check it before saving.

<figure><img src="https://393112916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJ8asLD4FVCFagK40xEr4%2Fuploads%2F2mp7J3ZAUTee2p5j5TCH%2FScreenshot%202026-09-25%20at%205.02.28%E2%80%AFPM.png?alt=media&amp;token=c51e05ec-4867-4b9d-bad7-08d899e01464" alt="" width="339"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Save your changes

Click **Save Settings** in the top-right.
{% endstep %}
{% endstepper %}

### 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.

<figure><img src="https://393112916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJ8asLD4FVCFagK40xEr4%2Fuploads%2FLpo4OpCQvqgk0rS59Rwv%2FScreenshot%202026-09-25%20at%204.19.38%E2%80%AFPM.png?alt=media&amp;token=4b3466fd-5d8b-498d-bfd4-8b96474ed723" alt="" width="563"><figcaption></figcaption></figure>

{% hint style="info" %}
Customers are not notified when their payment method is replaced. The next charge simply succeeds against the other card they already had on file.
{% endhint %}

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)](/subscriptions/managing-subscriptions/manually-charging-a-subscription-order-now.md).

### 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](/subscriptions/managing-subscriptions/updating-a-customers-payment-method.md).

### Common configurations

#### Basic

* max retries: 4
* intervals: `[1, 1, 1, 1]`
* total window: 4 days

#### Patient

* max retries: `5`
* intervals: `[1, 3, 3, 5, 7]`
* total window: `19` days

### 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.

<figure><img src="https://393112916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJ8asLD4FVCFagK40xEr4%2Fuploads%2FPK9hgvdLvjFOSxyPNXu0%2FScreenshot%202026-09-25%20at%205.04.05%E2%80%AFPM.png?alt=media&amp;token=889985de-5167-487e-9b90-be1f38e2ab37" alt="" width="342"><figcaption></figcaption></figure>

### 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](/subscriptions/managing-subscriptions/updating-a-customers-payment-method.md).

#### 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

<details>

<summary>When is a subscription marked as failed?</summary>

After the last retry fails and the 1-hour grace period ends.

</details>

<details>

<summary>Can I stop dunning without deleting my settings?</summary>

Yes.

Uncheck **Enable subscription dunning** and click **Save Settings**.

</details>

<details>

<summary>Do Shop Pay update emails send automatically?</summary>

They send when a merchant triggers the checkout-link recovery flow and **Enable auto Shop Pay update email** is on.

</details>

### Related guides

* [Updating a customer's payment method](/subscriptions/managing-subscriptions/updating-a-customers-payment-method.md)
* [The Subscription Activity Timeline](/subscriptions/managing-subscriptions/the-subscription-activity-timeline.md)
* [Manually charging a subscription (Order Now)](/subscriptions/managing-subscriptions/manually-charging-a-subscription-order-now.md)
* [Marking a subscription as failed](/subscriptions/managing-subscriptions/marking-a-subscription-as-failed.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.roadmap.so/subscriptions/pricing-and-billing/how-to-set-up-payment-retries.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.