---
title: >-
  New paymentInstrumentSendAddEmail mutation emails customers a link to add a
  payment method for a subscription, order, or draft order - Shopify developer
  changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: 'https://shopify.dev/changelog/new-paymentinstrumentsendaddemail-mutation'
  md: 'https://shopify.dev/changelog/new-paymentinstrumentsendaddemail-mutation.md'
metadata:
  effectiveApiVersion: 2026-10
  affectedApi:
    - displayName: Admin GraphQL API
      handle: admin-graphql
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: New
    handle: new
  indicatesActionRequired: false
  createdAt: '2026-09-02T07:29:50-04:00'
  postedAt: '2026-09-03T12:00:00-04:00'
  updatedAt: '2026-09-14T10:05:48-04:00'
  effectiveAt: '2026-09-03T12:00:00-04:00'
---

September 3, 2026

# New paymentInstrumentSendAddEmail mutation emails customers a link to add a payment method for a subscription, order, or draft order

DateSeptember 3, 2026

Version[2026-10](https://shopify.dev/changelog?api_version=2026-10)

FlagsNew

SurfacesAPI

Affected APIs[Admin GraphQL API](https://shopify.dev/changelog?api_type=admin-graphql)

You can now use the `paymentInstrumentSendAddEmail` 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: `customerPaymentMethodSendUpdateEmail` requires a `customerPaymentMethodId`, 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 `paymentInstrumentSendAddEmail` 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 [`paymentInstrumentSendAddEmail` mutation reference](https://shopify.dev/docs/api/admin-graphql/latest/mutations/paymentInstrumentSendAddEmail).

You identify the resource with the required `mandate` argument, a `PaymentInstrumentMandateInput` with two fields. `resourceType` takes `SUBSCRIPTIONS`, `ORDERS`, or `DRAFT_ORDERS`. `resourceId` 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.

***

**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 `userErrors` rather than as top-level errors, scoped to the input that failed, so you can tell a `resourceId` 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 `paymentInstrumentSendAddEmail`, your app needs the `write_customers` 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:

1. Check whether your app already requests the `write_customers` access scope. If it doesn't, adding it requires merchants to approve the updated scope before your app can call the mutation.
2. Update your app's API version to `2026-10` or later.
3. Call `paymentInstrumentSendAddEmail` with the resource you want the payment method bound to.
4. Test on a development store by sending the email to a test customer, then following the link and adding a card.

```graphql
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 `resourceId` with your own contract, order, or draft order ID, set `resourceType` 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 `userErrors` array. The email itself is queued and delivered asynchronously. If `userErrors` is populated, no email is sent.

## Related docs

* [paymentInstrumentSendAddEmail mutation reference](https://shopify.dev/docs/api/admin-graphql/latest/mutations/paymentInstrumentSendAddEmail)
* [Access scopes for Shopify apps](https://shopify.dev/docs/api/usage/access-scopes)
* [Protected customer data requirements](https://shopify.dev/docs/apps/launch/protected-customer-data)