新的 paymentInstrumentSendAddEmail 突变会向客户发送一封电子邮件，其中包含一个链接，用于为订阅、订单或草稿订单添加支付方式。

您现在可以在 GraphQL Admin API 中使用 paymentInstrumentSendAddEmail 变体，向客户发送链接以将付款方式添加到特定资源（例如订阅合同），从而让客户直接提供付款详情，而无需提前收集，并且该链接会将客户限定于该特定资源，因此他们无需登录账户。此变体自 API 版本 2026-10 起可用。这是一项新增功能，因此现有集成不受影响，也无需采取任何操作。

变更内容

在此更改之前，GraphQL Admin API 只能要求客户更新现有的付款方式：customerPaymentMethodSendUpdateEmail 需要 customerPaymentMethodId，因此无法为没有存档付款方式的订阅合同、订单或草稿订单请求付款详情。商家和应用必须在设置资源之前自行收集付款方式。

paymentInstrumentSendAddEmail 变体填补了这一空白。它自版本 2026-10 起在 GraphQL Admin API 中可用，向与资源关联的客户发送用于添加付款方式的链接，并返回发送邮件的 Customer。有关完整的参数和返回结构，请参阅 paymentInstrumentSendAddEmail 变体参考。

您通过所需的 mandate 参数标识资源，这是一个包含两个字段的 PaymentInstrumentMandateInput。resourceType 接受 SUBSCRIPTIONS、ORDERS 或 DRAFT_ORDERS。resourceId 接受该订阅合同、订单或草稿订单的数字 ID，而不是 GID；如果使用 GID，则会返回未找到用户错误。客户添加的付款方式将绑定到您指定的资源上，因此为某个合同发送的链接不能用于其他合同。

可选的 email 参数控制邮件投递。from 设置发件人地址，默认值为商店的客户联系邮箱。bcc 接受消息抄送地址列表。

---

注意： <code>email</code> 接受 <code><span class="PreventFireFoxApplyingGapToWBR">Email<wbr/>Input</span></code>，但变体仅读取 <code>from</code> 和 <code>bcc</code>。<code><span class="PreventFireFoxApplyingGapToWBR">Email<wbr/>Input</span></code> 上的其他字段在此处无效。

---

验证失败会作为 userErrors 返回，而非顶级错误，并限定于失败的输入，因此您可以区分未引用现有资源的 resourceId 与格式错误的 bcc 地址。无效的 resourceType 是例外情况：它是一个枚举，因此 unrecognized 值会在变体运行前导致 GraphQL 验证失败。此变体是增加一项能力而非更改现有功能，因此不会弃用或替换任何现有字段或变体。

受影响对象

此更改适用于调用版本为 2026-10 或更高版本的 GraphQL Admin API 的应用。该变体不存在于 2026-07 或更早版本中，因此固定在这些版本上的应用不受影响，且行为无变化。

要调用 paymentInstrumentSendAddEmail，您的应用需要 write_customers 访问权限范围。在员工上下文中发出的请求还要求该员工具备创建和编辑客户的权限，否则请求将被拒绝而不是发送电子邮件。

如果您正在构建订阅应用，此突变最为相关，因为它允许您向客户请求合同设置时的付款详情，而不是由您自行提供。它同样适用于订单和草稿订单。如果您的应用不向客户请求付款方式，则没有任何变化：此次发布仅添加了一个突变，并未改变任何现有突变的行为。

无需进行买家端的集成工作。客户会收到电子邮件，点击链接并从其客户账户中添加付款方式。

操作指南

无需采取任何操作。此版本添加了一个变更操作，且未更改、弃用或删除任何现有字段、变更操作或行为，因此运行在 2026-07 及更早版本上的应用仍可保持不变地继续工作。

开始使用该突变：

1. 检查您的应用是否已请求 write_customers 访问权限范围。如果尚未请求，添加该权限范围需要商户批准更新后的权限范围，之后您的应用才能调用该变更操作。
2. 将应用的 API 版本更新至 2026-10 或更高版本。
3. 使用您希望绑定支付方式的目标资源调用 paymentInstrumentSendAddEmail。
4. 在开发商店中测试，向测试客户发送电子邮件，然后点击链接并添加银行卡。

mutation { paymentInstrumentSendAddEmail( mandate: { resourceType: SUBSCRIPTIONS, resourceId: "1234567890" } ) { customer { id } userErrors { field message } } }

示例代码向订阅合同中的客户发送默认电子邮件。请将 resourceId 替换为您自己的合同、订单或草稿订单 ID，设置 resourceType 以匹配，并在希望覆盖发件人地址或抄送其他收件人时添加可选参数 email。

成功的调用会返回电子邮件发送到的 customer 以及一个空的 userErrors 数组。电子邮件本身会被排队并异步投递。如果 userErrors 有内容，则不会发送电子邮件。

相关文档

• paymentInstrumentSendAddEmail 突变参考
• Shopify 应用的访问范围
• 受保护的客户数据要求