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

# Updating a customer's payment method

How to switch a subscription contract to a new card or wallet — covering the in-modal options on a single contract and the bulk action across many at once.

When a card on a subscription expires, gets revoked, or the customer asks you to switch them to a different one, you have three ways to fix it from the admin. This article walks through all three, plus the bulk action for handling many contracts at once.

For the customer-driven version of the same flow (initiated from the storefront), see What customers can do from their account page.

#### Where to update payment methods

You have two entry points:

* Single contract — open the contract from the Subscriptions list, then click Update payment method on the Payment method card in the right-hand rail.
* Bulk — from the Subscriptions list view, apply any filters you want (e.g., Status: Failed), then open Actions ▾ and choose Update payment method for N subscriptions.

#### The Payment method card on a contract

The Payment method card shows the card or wallet currently attached to the contract, with an Active badge and the expiry date. If the customer has another payment method on file with Shopify, you'll also see "1 other payment method available" below.

Click Update payment method to open the modal.

#### The Update payment method modal

The modal has three sections, top to bottom. You pick the one that fits the situation.

**1. Select from existing payment methods**

If the customer has already given Shopify another card or wallet (you'll see them listed here as radio options, with the currently-Active one marked), pick the one you want and the contract is switched to it.

This is the fastest fix. No email, no customer action. Use it whenever the "1 other payment method available" notice appears on the Payment method card.

{% hint style="info" %}
Switching the payment method does not immediately retry billing.

The new method is used the next time the contract is charged — either the next scheduled cycle, or the next dunning retry if the contract is mid-dunning. If the contract is already Failed, use Order Now after switching to verify the new method works, then reactivate.
{% endhint %}

**2. Send an update payment method email (Shopify-native)**

Sends the customer an email with a Shopify-native link they follow to add or update their card via Shopify's own customer-account UI. Same flow customers can trigger themselves from the storefront.

The modal carries an explicit warning: "May not work with subscriptions setup through Shop Pay." If the customer originally subscribed using ShopPay, Shopify's native flow doesn't always reattach the new payment method to the existing subscription contract — use option 3 instead.

This option works for any payment method type Shopify supports. Use it as the default for non-ShopPay customers.

**3. Send a $1 checkout order link (the Shop Pay flow)**

Roadmap creates a $1 draft order for the customer and emails them the checkout link. The customer completes the $1 checkout, which captures their new payment method as a side-effect, and Roadmap attaches that payment method to the subscription.

The $1 charge is refunded automatically once the payment method updates. The modal includes this disclaimer for you to relay to anxious customers:

Please note: The customer will be charged $1 for this transaction. The order will be refunded automatically once the payment method is updated.

Use this option whenever:

* The customer paid with ShopPay and Option 2 didn't work
* You want a single workflow that works for every payment type the customer might use

#### The bulk "Update payment method for N subscriptions" action

The Subscriptions list view's Actions ▾ menu contains an Update payment method for N subscriptions option, where N is the number of contracts currently visible after your filters.

This is for situations like a card-issuer mass reissue, a known billing-processor outage, or a recovery push after a holiday-season failure spike. Apply your filter (most commonly Status: Failed or Last Payment Status: Failed), open Actions ▾, and dispatch the update to the whole filtered set in one click.

The bulk action uses the $1 checkout order link option for every contract — Roadmap creates a $1 draft order per contract and emails each customer the checkout link. The same auto-refund rule applies (the $1 charge reverses once the customer's new payment method is captured).

{% hint style="warning" %}
The bulk action operates on whatever is currently in the filtered list, not on a row selection. Always verify your filters first — the count next to the action ("for 6 subscriptions") tells you exactly how many emails will go out, and how many $1 charges will be created.
{% endhint %}

#### The "Enable auto Shop Pay update email" toggle, demystified

Open Subscriptions → Dunning Settings and you'll see a section titled Shop Pay Payment Update with a toggle labeled Enable auto Shop Pay update email.

The label is misleading — there is no automatic trigger here. What this toggle actually does:

* On — every time you press Send checkout order link (per-contract) or run the bulk update action, the email goes out.
* Off — those merchant-triggered actions silently complete without sending any email. The draft order is created but the customer never receives the link.

Leave this on for normal operation. Turn it off only if you want to suppress the email side of the recapture (for testing, during an outage, or while running a coordinated communication out-of-band).

#### The email customers receive

The email body for the $1-checkout flow lives in Settings → Mail Templates → Payment Method Update. The default subject is "Action Required: Update Your Payment Method for \[Store Name]" and the body explains the $1 verification and refund.

You can edit the subject and body in the template editor, using Liquid variables for the customer's name, the checkout link, and the next billing date. Test changes by triggering an Update payment method on a real contract before relying on the new copy.

The Shopify-native email (Option 2) is sent by Shopify, not by Roadmap, and isn't editable from the Roadmap admin.

#### What the customer experiences

| Option                 | Customer action required                      | Customer charge    |
| ---------------------- | --------------------------------------------- | ------------------ |
| Select existing method | None                                          | None               |
| Shopify-native email   | Click email link → update card via Shopify UI | None               |
| $1 checkout order link | Click email link → complete $1 checkout       | $1 (auto-refunded) |

#### Common scenarios

**A regular subscription's card expired**

1. Select existing method if there's another on file — easiest fix.
2. Otherwise, send the Shopify-native email.

**A ShopPay subscription's payment method needs replacing**

Skip Option 2 and use the $1 checkout order link. Tell the customer the $1 will be refunded automatically.

**Bulk recovery after a payment-processor outage**

Filter the Subscriptions list to Status: Failed (or Last Payment Status: Failed), then Actions ▾ → Update payment method for N subscriptions. Confirm the count matches your expected impact before dispatching.

**Customer ignores the email**

Draft orders for the $1-checkout flow expire after 7 days. After that, you can re-trigger the action from the contract page to create a fresh draft order and send a new email.

#### Related guides

* Failed payment retries (dunning)
* Subscription statuses explained
* What customers can do from their account page
* The Subscription Activity Timeline


---

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