Executive summary
- What: Admin GraphQL API 2026-10 adds paymentInstrumentSendAddEmail, which emails the customer on a subscription contract, order, or draft order a link to add a payment method.
- Why: It removes the requirement to hold payment details before the resource exists, and the link scopes the customer to that one resource without an account login.
- Who: Teams building subscription, quote-to-cash, or draft order flows. The change is additive, so existing integrations need no action.
What changed
The Admin API could previously only ask a customer to refresh a payment method it already had. customerPaymentMethodSendUpdateEmail requires a customerPaymentMethodId, so there was no supported way to request payment details for a subscription contract, order, or draft order with nothing on file. Apps and merchants collected the card themselves first.
paymentInstrumentSendAddEmail closes that gap. The required mandate argument takes a PaymentInstrumentMandateInput with two fields: resourceType, an enum accepting SUBSCRIPTIONS, ORDERS, or DRAFT_ORDERS, and resourceId, which expects the numeric ID rather than the GID. Passing a GID returns a not found userError, the first thing to check when a call fails against a resource you know exists.
The optional email argument accepts an EmailInput but reads only from and bcc. Validation failures surface in userErrors scoped to the offending input rather than as top-level errors, with one exception: an unrecognized resourceType fails enum validation before the mutation runs. The method the customer adds is bound to the resource you named, so a link issued for one contract cannot be redeemed against another.
Why it matters
For Plus merchants running assisted sales, this closes a gap usually solved with a phone call. A representative building a quote as a draft order no longer has to hold or relay card details while the order is assembled, which removes an informal handling path most compliance reviews would rather not find. The same applies to subscription onboarding: build the contract first, request the instrument after.
Two details are worth planning around. The email is queued and delivered asynchronously, so a successful response confirms acceptance rather than delivery, and monitoring needs a separate signal for whether the customer acted. Second, the mutation sends an email of its own, alongside whatever dunning or onboarding sequence you already run. Merchants automating repeat and custom order flows should map this against existing triggers, which we cover in
automating custom orders and repeat purchases.
Role-specific impact
- Marketers: Payment collection becomes a system-triggered step rather than a manual chase, but it adds a message whose copy you do not control. Sequence it against Flow and your ESP so a buyer gets one prompt, not three.
- Developers: Pin to 2026-10 or later, confirm the write_customers scope, pass the numeric resource ID, and read userErrors on every call, since validation failures will not raise a top-level GraphQL error.
- Store admins: Staff-context calls also require the create and edit customers permission. Requests without it are denied rather than queued, so audit staff roles before anyone relies on the flow.
Use-case example
Real-world scenario
A B2B distributor on Plus quotes through draft orders. A representative assembles a 60-line draft order, then sends the payment method link straight to the buyer's accounts payable contact, who adds a card with no account login and no call back. If the team issues 400 quotes a month and a third stall about two days on card collection, compressing that to same day recovers roughly 260 quote-days of cycle time monthly. The number is illustrative, the mechanism is not: the delay is rarely the quote, it is waiting for someone with authority to read out a card number.
Implementation checklist
- Confirm the target API version is 2026-10 or later; the mutation does not exist in 2026-07 and earlier.
- Check whether your app already requests write_customers; adding it requires merchant re-approval.
- Audit staff permissions for any call made in a staff context.
- Pass the numeric resourceId, not the GID, and match resourceType to the resource you are targeting.
- Handle userErrors explicitly and log the field each is scoped to, so a bad bcc address is distinguishable from a missing resource.
- Test end to end on a development store: send, follow the link, add a card, and confirm it is bound to the intended resource.
- Deconflict the message with existing dunning and Flow-driven sequences before enabling it in production.
FAQ
Q: Does this replace customerPaymentMethodSendUpdateEmail?
A: No. That mutation still handles updating a payment method the customer already has, and is unchanged. The new one covers the case it never could: a resource with no payment method on file.
Q: Does the customer need to log into their account to use the link?
A: No. The link scopes them to the resource it was issued for, so they can add a payment method without signing in, and it cannot be applied to another contract or order.
Resources
paymentInstrumentSendAddEmail mutation reference
Need guidance? Talk to Makro.