Shopify merchants and developers can now request payment details from customers — without needing the information up front. The brand‑new paymentInstrumentSendAddEmail mutation, released in API version 2026‑10, sends a scoped email link that lets a shopper add a payment method directly to a subscription contract, order, or draft order. In this post we break down what changed, who needs to care, and exactly how to start using the mutation in your apps.
What Changed?
Previously the Admin GraphQL API only offered customerPaymentMethodSendUpdateEmail, which required an existing customerPaymentMethodId. That meant merchants and subscription apps had to collect a card themselves before they could create a subscription, order, or draft order lacking a payment method. The new mutation fills that gap. It accepts a mandate argument that points to the target resource (subscription, order, or draft order) and automatically sends a personalized email link. The link is scoped: the customer can only add a payment method to the resource specified, and they don’t need to log in first.
Who Is Affected?
The change is relevant for any app that calls the Admin GraphQL API with version 2026‑10 or later and needs to collect payment details after a resource has been created. Developers must add the write_customers scope if it isn’t already present. For staff‑context calls, the staff member also needs the “Create and edit customers” permission; otherwise the request is denied. Merchants who install or update an app will be prompted to approve the new scope, but no existing integrations break—apps pinned to older API versions simply won’t see the mutation.
How to Implement the Mutation
graphql
mutation {
paymentInstrumentSendAddEmail(
mandate: { resourceType: SUBSCRIPTIONS, resourceId: "1234567890" }
) {
customer {
id
}
userErrors {
field
message
}
}
}
Replace resourceId with the numeric ID of your subscription contract, order, or draft order, and set resourceType accordingly (SUBSCRIPTIONS, ORDERS or DRAFT_ORDERS). You can also supply an optional email argument to override the sender address or add BCC recipients.
Testing and Best Practices
• Use a development store and a test customer email to verify the link works before rolling out to live shoppers. The email is queued asynchronously, so you’ll see the message in the store’s email logs shortly after the mutation resolves.
• Handle userErrors gracefully. If the mutation returns any errors, no email is sent, so surface the messages in your UI and allow the merchant to retry.
• Never expose raw GIDs for the resource ID. The mutation expects the numeric ID; passing a GID will produce a “not found” userError.
What Merchants Should Know
From a merchant’s perspective, the new mutation is invisible until an app they use starts sending the “add payment method” email. When that happens, shoppers receive a clean, one‑click link that bypasses the storefront login flow. This reduces friction for subscription sign‑ups and for orders that need a payment method after the fact (e.g., manual invoice collections). No store‑level configuration is required.
Conclusion & Call to Action
The paymentInstrumentSendAddEmail mutation eliminates a common pain point for subscription and custom‑order workflows by letting the customer provide payment details at the moment they’re ready. If you’re building a subscription app, a custom checkout flow, or an invoicing solution, update to API version 2026‑10, add the required scope, and start testing the mutation today. Your merchants will appreciate the smoother checkout experience, and you’ll gain a powerful new tool for managing payment collection.
Ready to implement? Review the full mutation reference in Shopify’s developer docs, update your OAuth scopes, and fire off a test email on a sandbox store. Need help? Drop a comment below or reach out to the Shopify Partner community for troubleshooting tips.
