> 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/failed-payment-retries.md).

# Failed payment retries

Configure how Roadmap retries failed subscription payments, 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.

### Where to configure it

In Roadmap, open **Subscriptions** → **Dunning Settings**.

### What you can configure

#### Enable subscription dunning

This is the master switch.

When it is off, failed contracts are not retried.

#### Maximum retry attempts

Set how many retries Roadmap should attempt before giving up.

Allowed range is `1–10`.

#### Retry intervals

Each row sets the number of days to wait before the next retry.

Example with intervals `[1, 1, 1]`:

* initial failure: day `0`
* 1st retry: day `1`
* 2nd retry: day `2`
* 3rd retry: day `3`
* mark as Failed: day `3`, after the last retry fails

#### Retry Schedule Preview

Use the preview panel to confirm the exact timeline before saving.

### Configure dunning

{% stepper %}
{% step %}

#### Open Dunning Settings

Go to **Subscriptions** → **Dunning Settings**.
{% endstep %}

{% step %}

#### Enable dunning

In **General Settings**, check **Enable subscription dunning**.
{% endstep %}

{% step %}

#### Set the retry limit

Enter a value in **Maximum retry attempts**.
{% endstep %}

{% step %}

#### Choose retry timing

Under **Retry intervals (days)**, set how many days should pass before each retry.
{% endstep %}

{% step %}

#### Review the schedule

Review **Retry Schedule Preview** before saving.
{% endstep %}

{% step %}

#### Save your changes

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

### How dunning runs

Dunning runs daily.

Each day, Roadmap checks previous failed payments and retries any contract due for another attempt.

A contract is skipped if:

* the customer has already paid
* the customer skipped the delivery
* the customer rescheduled the delivery
* a later cycle was charged successfully

This prevents unnecessary retry attempts on orders the customer has already resolved or moved.

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

#### A later cycle is charged successfully

This usually happens when you or the customer use **Order now** during dunning.

Roadmap treats the older failed cycle as superseded and stops retrying it.

### Shop Pay payment update emails

The **Shop Pay Payment Update** section controls the Roadmap-specific `$1` checkout recovery flow.

When **Enable auto Shop Pay update email** is on, the email is sent whenever a merchant triggers the checkout-link recovery flow from a contract or bulk action.

When it is off, those actions still create the draft order but do not send the email.

For the full recovery workflow, see [Updating a customer's payment method](/subscriptions/managing-subscriptions/updating-a-customers-payment-method.md).

{% stepper %}
{% step %}

#### Find the Shop Pay section

On **Dunning Settings**, find **Shop Pay Payment Update**.
{% endstep %}

{% step %}

#### Turn on the email

Check **Enable auto Shop Pay update email**.
{% endstep %}

{% step %}

#### Review the email template

Open **Mail Templates** → **Payment Method Update**.

Make sure the email explains the `$1` verification charge and refund clearly.
{% endstep %}
{% endstepper %}

### Common configurations

#### Conservative

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

#### Patient

* max retries: `5`
* intervals: `[2, 3, 3, 5, 7]`
* total window: `20` days

#### Aggressive

* max retries: `1`
* intervals: `[1]`
* total window: `1` day

### Where to see dunning state

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 these first:

* **Enable subscription dunning** is on
* you clicked **Save Settings**
* **Retry Schedule Preview** matches what you expect

#### A subscription failed sooner than expected

Review:

* **Maximum retry attempts**
* **Retry intervals (days)**
* **Retry Schedule Preview**

Remember the contract moves to **Failed** after the last retry fails and the 1-hour grace period passes.

#### Shop Pay customers are not receiving update emails

Check these first:

* **Enable auto Shop Pay update email** is on
* you clicked **Save Settings**
* 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)


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.roadmap.so/subscriptions/pricing-and-billing/failed-payment-retries.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.