You can now use the mutation in the GraphQL Admin API to email a customer a link for adding a payment method to a specific resource (for example, a subscription contract). This lets you collect payment details directly from the customer rather than needing them up front, and the link scopes the customer to that specific resource, so they don't need to sign in to their account. The mutation is available as of API version 2026-10. This is an additive change, so existing integrations are unaffected and no action is required.
What changed
Before this change, the GraphQL Admin API could only ask a customer to update an existing payment method: requires a , so there was no way to request payment details for a subscription contract, order, or draft order that has no payment method on file. Merchants and apps had to collect the payment method themselves before setting up the resource.
The mutation closes that gap. It is available in the GraphQL Admin API as of version 2026-10. It emails the customer associated with a resource a link to add a payment method, and returns the Customer the email was sent to. For the full argument and return shape, see the mutation reference.
You identify the resource with the required mandate argument, a with two fields. takes SUBSCRIPTIONS, ORDERS, or DRAFT_ORDERS. takes the numeric ID of that subscription contract, order, or draft order, not the GID. A GID comes back as a not found userError. The payment method the customer adds is bound to the resource you name, so a link sent for one contract can't be used against another.
The optional email argument controls delivery. from sets the sender address and defaults to your store's customer contact email. bcc takes a list of addresses to copy on the message.
email takes an , but the mutation reads only from and bcc. Other fields on have no effect here.
email takes an , but the mutation reads only from and bcc. Other fields on have no effect here.
Note: <code>email</code> takes an <code><span class="PreventFireFoxApplyingGapToWBR">Email<wbr/>Input</span></code>, but the mutation reads only <code>from</code> and <code>bcc</code>. Other fields on <code><span class="PreventFireFoxApplyingGapToWBR">Email<wbr/>Input</span></code> have no effect here.
Validation failures come back in rather than as top-level errors, scoped to the input that failed, so you can tell a that doesn't reference an existing resource apart from a malformed bcc address. An invalid resourceType is the exception: it's an enum, so an unrecognized value fails GraphQL validation before the mutation runs. The mutation adds a capability rather than changing one, so it doesn't deprecate or replace any existing field or mutation.
Who's affected
This change applies to apps calling the GraphQL Admin API on version 2026-10 or later. The mutation doesn't exist in 2026-07 or earlier, so apps pinned to those versions are unaffected and see no change in behavior.
To call , your app needs the access scope. Requests made in a staff context additionally require the staff member to have the create and edit customers permission, and requests without it are denied rather than sending an email.
The mutation is most relevant if you build subscription apps, because it lets you ask a customer for payment details for a contract you're setting up rather than supplying them yourself. It applies equally to orders and draft orders. If your app doesn't request payment methods from customers, nothing changes: this release adds a mutation and doesn't alter the behavior of any existing one.
No buyer-side integration work is required. The customer receives the email, follows the link, and adds a payment method from their customer account.
What to do
No action is required. This release adds a mutation and doesn't change, deprecate, or remove any existing field, mutation, or behavior, so apps on 2026-07 and earlier continue to work unchanged.
To start using the mutation:
- Check whether your app already requests the
access scope. If it doesn't, adding it requires merchants to approve the updated scope before your app can call the mutation. - Update your app's API version to
2026-10or later. - Call
with the resource you want the payment method bound to. - Test on a development store by sending the email to a test customer, then following the link and adding a card.
mutation {
paymentInstrumentSendAddEmail(
mandate: { resourceType: SUBSCRIPTIONS, resourceId: "1234567890" }
) {
customer {
id
}
userErrors {
field
message
}
}
}The sample sends the default email to the customer on a subscription contract. Replace with your own contract, order, or draft order ID, set to match, and add the optional email argument if you want to override the sender address or copy other recipients.
A successful call returns the customer the email was sent to and an empty array. The email itself is queued and delivered asynchronously. If is populated, no email is sent.