How to Request New Payment Method After Shopify Removes Revoked customerPaymentMethod

GraphQL Admin API Troubleshooting
1

Hi,

I’m developing a custom embedded subscriptions app, which is currently live in production. We’ve noticed that after a billing attempt fails—typically due to a revoked or invalid payment method—Shopify removes the customerPaymentMethod from the subscription contract and also deletes it from the customer.

At this point, the contract is left without a payment method, and we’re unable to recover it through the customerPaymentMethodSendUpdateEmail mutation, since it requires a valid customerPaymentMethodId, which no longer exists.

How can we request a new payment method from the customer in this scenario?

Any guidance would be appreciated.

Thanks.

2

Hi @Raisel_Castellanos_S

This is a known limitation in the Shopify Subscriptions API: once a failed billing attempt results in the payment method being revoked or deleted, the customerPaymentMethod is removed from both the customer and the subscription contract. At this point, you cannot use the customerPaymentMethodSendUpdateEmail mutation, because it requires a valid customerPaymentMethodId, which no longer exists.

The recommendation is that you provide a customer-facing portal where customers can add a new payment method themselves. This is the only secure way for a customer to add a new payment method when none exists. You can:

  • Send the customer a secure link to your app’s customer portal (using an app proxy).
  • Instruct the customer to add a new payment method via your portal.
  • Once the customer adds a new payment method, you can associate it with the subscription contract.

See the official guide to do this here: Create a customer-facing purchase option portal.

3

Hi Liam,

Thanks for the great documentation — the Customer Portal guide clearly outlines how to build the purchase option portal for customers.

However, I couldn’t find a way to allow a customer to add a new payment method if they no longer have an existing one. Both the customerPaymentMethodGetUpdateUrl and customerPaymentMethodSendUpdateEmail mutations require a valid customerPaymentMethodId, which isn’t available in cases where the previous method was revoked or deleted (e.g., after a failed billing attempt).

Is there currently any mutation or flow to initiate collection of a brand new payment method when no valid one exists?

Thanks in advance for your help,

4

The only supported flow is to have the customer add a new payment method through the Shopify-hosted customer portal. This is the secure and recommended approach. When a customer has no payment methods, you must:

  • Direct the customer to your app’s customer portal (typically via an app proxy or embedded app page).
  • Present a UI that allows the customer to add a new payment method.
  • Once the customer completes the process, Shopify will create a new CustomerPaymentMethod object for them.
  • You can then associate this new payment method with their subscription contract using the subscriptionContractUpdate mutation.

There is no API mutation to “initiate” the payment method collection process itself; the customer must perform this action interactively via the portal.

5

Hi Liam,

Which GraphQL mutation should I use to allow a customer to add a new payment method to their account, especially when they currently have no existing payment methods?

Thanks for your help!

6

Hi again @Raisel_Castellanos_S

To allow a customer to add a new payment method to their account (especially when they have no existing payment methods), you should use the customerPaymentMethodRemoteCreate mutation for most gateways, or the customerPaymentMethodPaypalBillingAgreementCreate mutation for PayPal Express.

These mutations are designed to associate a remote payment method (such as a credit card from Stripe, Braintree, or Authorize.net, or a PayPal billing agreement) with a Shopify customer.

7

Got it — thank you so much, Liam! Really appreciate your help.