顧客のカードが銀行側で差し替えられ、更新課金が失敗する。契約を開き、決済手段のところに入って、更新リンクをメールする。2クリック、問い合わせ対応ゼロ。

同じストアが、別プラットフォームから400件の定期購入者を移行してきたとします。あるいは、残額を後から請求してほしいという卸先から電話注文を受けたとします。カードは登録されていません。顧客自身に登録してもらう必要があります。

そのボタンを探しても、見つかりません。

管理画面が実際にできること

アクション自体は存在します。そしてShopifyヘルプセンターは、その位置について珍しく正確です。顧客の定期購入決済情報の編集の手順にはこう書かれています。「For the relevant saved card, click ⋯ > Send link to update card.」

「For the relevant saved card」。このアクションは、すでに存在するカードにぶら下がっています。Shopify Subscriptionsアプリ側の契約単位の同じ画面も、選択肢は3つで前提は同じです。更新リンクをメールする、「Replace card」、「Delete card」。どれも保存済みの決済手段を対象にした操作です。

その下にあるのが、このボタンが呼んでいるAPIです。customerPaymentMethodSendUpdateEmailの必須引数はちょうど1つ、customerPaymentMethodId: ID!だけ。ドキュメントはユースケースを、カードが「is expiring or has been declined」場合と説明しています。このmutationは「カードが無い」という状態を表現できません。識別対象そのものがカードだからです。

そのため、カード未登録の状態に置かれたマーチャントに残るのは手入力の経路です。自分で顧客のカード番号をShopifyへ打ち込む。draft orderではこの手順が「Enter the customer's billing and credit card information」と書かれており、Shopifyのヘルプページは2つの条件を付けています。draft orderでのクレジットカード手動決済は「only through Shopify Payments」であり、Shopify Paymentsの本人確認完了が必要です。さらに他の決済プロバイダを使っている場合は、「handling customer information in this way」がPCI compliance requirementsに影響するかプロバイダへ確認するよう案内しています。

もう1つの標準機能、draft orderのinvoice送付は、カードの保存ではなく支払いを発生させるものとして書かれています。ヘルプセンターはinvoiceを「secure checkout links for customers to complete payment online」と説明しており、このページにinvoiceの流れが後から再課金できる決済手段を保管するという記載はありません。

2026年9月3日に出荷されたもの

paymentInstrumentSendAddEmailが、ボタンでは扱えないケース向けのmutationです。Shopifyのリファレンスはこれを「a secure link to add a new payment instrument (e.g., credit card) for a specific resource such as a subscription, order, or draft order」を送るものと説明し、想定場面として上記そのものを挙げています。「after a payment method was revoked or when setting up payment for a new subscription contract」。

機能そのものより重要な設計判断が2つあります。

リンクは1つのリソースにスコープされます。 必須のmandate引数でリソースを指定し、changelogはその帰結を明快に書いています。リンクは「scopes the customer to that specific resource, so they don't need to sign in to their account」で、「a link sent for one contract can't be used against another」。サインイン不要という部分が効きます。Shopifyが文書化している「顧客が自分で決済手段を管理する」経路はcustomer accountで、ヘルプセンターは顧客がアカウントへサインインして「manage their payment methods and shipping address」と書いています。このリンクはそこを飛ばします。

リソース種別は3つに固定されています。 PaymentInstrumentMandateResourceTypeの値はちょうどSUBSCRIPTIONS、ORDERS、DRAFT_ORDERSだけです。顧客単位の選択肢はありません。つまり「とりあえずカードを登録しておいて」と依頼することはできず、ストア内に既に存在する何かに対してしか要求できません。

まだstableバージョンには入っていない

changelogはこのmutationが「is available in the GraphQL Admin API as of version 2026-10」と書いています。この文は正確ですが、いま使えるように読めます。本番で使うという意味では、まだ使えません。

/latest/のパスでリファレンスを開くと、ページは 「This API version is not supported.」 を返します。/latest/は2026-07に解決され、このmutationはそこに存在しません。2026-10のページは正常に表示され、release candidate というラベルが付いています。

Shopifyのバージョニング方針は、このラベルを曖昧さなく定義しています。release candidateは「may include backwards-incompatible changes, so not recommended for production」。新バージョンの公開は「at 5pm UTC on the first day of the quarter」なので、2026-10がstableになるのは2026年10月1日です。

つまり、おおよそ9月3日から10月1日までは、機能は文書化されテストもできるが、責任あるアプリが本番ストアに対して実行するものではないという期間でした。9月にこの件をサブスクリプションアプリのベンダーへ問い合わせて「まだstableバージョンに入っていません」という回答だったなら、それは適切な回答であって、はぐらかされたわけではありません。

resourceId の罠

ここが、誰かの午後を潰す可能性がもっとも高い箇所です。

Shopify Admin APIのmutationは、ほぼすべてGlobal IDでレコードを指定します。gid://shopify/Customer/544365967のような形です。兄弟mutationもそうで、customerPaymentMethodId: ID!を取り、ドキュメントの例ではgid://shopify/CustomerPaymentMethod/b7cc6e3267aace169e516ed48be72dffを渡しています。

新しい方は違います。PaymentInstrumentMandateInputはresourceId: String!と宣言しています。IDではなくStringです。慣れた形式に手を伸ばした場合どうなるかも、changelogが明記しています。「takes the numeric ID of that subscription contract, order, or draft order, not the GID. A GID comes back as a not found userError.」

型エラーではなく、not foundエラーです。存在する契約に対して完全に妥当なGIDを渡すと、Shopifyは「そのリソースは存在しない」と返してきます。決済手段に関する2つの兄弟mutationが、どちらもリンクをメールするものなのに、逆の識別子規約を使っている。しかも失敗の出方が、間違った方向を指しています。

Shopifyはこの領域に関しては少なくとも自己一貫しています。subscription contractのCSVも、customer_payment_method_idを「a unique alphanumeric code. For example, 24e8c839c47ef47d30ad28346d130e74」と記載しています。GIDのラッパー無し、裸のトークンです。

メールの6フィールドのうち4つは何もしない

任意引数のemailはEmailInputを取ります。リファレンスページのスキーマには6つのフィールドが並びます。bcc、body、customMessage、from、subject、to。

mutationが読むのはそのうち2つです。引数の説明が直接そう書いています。「Only the 'from' and 'bcc' fields are accepted for input.」fromは送信元を上書きし、既定値はストアのcustomer contact emailです。bccは他のアドレスを控えに入れます。

厄介なのは、同じページにあるShopify自身の自動生成サンプルが6つすべてを埋めていることです。"body": "<your-body>"、"subject": "<your-subject>"、"to": "<your-to>"も含めて。このサンプルをコピーして件名と本文を書き込むと、呼び出しは成功し、userErrorsは空配列で返り、既定のメールが送信されます。自分が書いた文面が破棄されたことを教えてくれるものは、どこにもありません。

マーチャントにとっての意味は1つです。このメールの文面は自分では書けません。アプリのUIがどう見えようと、顧客から見えるかたちで操作できるのは送信元アドレスだけです。

権限はボタンより厳しい

新しいmutationのリファレンスページは、兄弟よりも長いアクセス要件を掲げています。customerPaymentMethodSendUpdateEmailが要求するのはwrite_customersです。paymentInstrumentSendAddEmailが要求するのはwrite_customersに加えて、ページの原文で「The user must have permission to create and edit customers, and read access to the mandate resource.」

changelogはcreate and edit customers権限には触れていますが、mandateリソースへのread accessには触れていません。どちらもスタッフ単位の条件なので、顧客編集できるスタッフを絞っているストアでは、これが失敗するスタッフが出ます。さらにアプリがwrite_customersをまだ要求していない場合、採用には新しいスコープの承認が必要になります。

これで解決しないこと

多くのマーチャントがこのボタンを探す最大の理由である移行のケースは、いまも上流で止まっています。

Shopify Subscriptionsへsubscription contractをインポートするにはCSVが必要で、列の仕様は「all columns must be added to the CSV file to import correctly, and all fields are required unless otherwise noted」と書いています。customer_payment_method_idはその列の1つで、optionalとは書かれていません。契約をインポートしてから後でカードを要求する、という順番は取れません。インポート側が、カードの無い契約を受け付けないからです。

同じページには2つ目の壁もあります。「If your third-party subscription app isn't Shopify Checkout integrated, then you can't import your contracts.」

新しいmutationが効くのは、リソースが先に存在して支払いが後から付くケースです。アプリがAPI経由で作成した契約、卸先向けに組んだdraft order、決済手段が失効したorder。トークンが持ち出せないプラットフォームから定期購入者の一覧を運んでくる作業には効きません。

第一者アプリはまだ採用していない

Shopify Subscriptionsは、これを自分で確認できる点でアプリとしては珍しい存在です。App Storeのリスティングがソースの場所をgithub.com/Shopify/subscriptions-reference-appと明記しています。

出典: Shopify App Store（Shopify Subscriptions、2026-09-17時点）

このリポジトリは旧来のmutationを分かりやすい場所に実装しています。CustomerPaymentMethodSendUpdateEmailMutationというファイル、SendPaymentMethodUpdateEmailService、そのフロー用のモーダルコンポーネント。一方でpaymentInstrumentSendAddEmailをチェックアウトしたリポジトリ全体から検索しても、1件も出てきません。公開リポジトリの最新コミットは2026年1月2日付なので、これは公開されているリファレンスアプリについての証拠であって、あなたの管理画面で動いているアプリについての証明ではありません。ただしShopify外部の人間が読める第一者実装はこれだけで、新しいmutationはそこに入っていません。

見ているついでに書いておくと、このリファレンスアプリはapi_version = "unstable"を指定しています。Shopifyのバージョニングページはunstableを「early testing only」向けで、「features can be added or removed at any time with no guarantee of release」と説明しています。

いま使っているアプリに何を聞くか

これはAdmin APIの機能です。これ自体が管理画面にボタンを作ることはないので、使えるかどうかは、そのリソースを管理しているアプリに完全に依存します。

出典: Shopify App Store（Appstle℠ Subscriptions App、2026-09-17時点）

いま何に対して支払っているかを知っておくと判断が早くなります。サードパーティのサブスクリプションアプリで規模の大きい2つは、どちらもこの機能に相当するものを売っており、どちらも最初の有料プランに置いています。

Appstle Inc.のAppstle℠ Subscriptions AppはBuilt for Shopifyバッジを持ち、評価は5.0（8,721件）です。FREEプランは「Shopify Native Customer Portal」を挙げ、上限は「Upto $500 in subscriptions per month」。「Manual Subscription Creation」と「Customer Portal Passwordless Login」が現れるのは、月額$10（年額$96）のSTARTERプランです。

Seal Subscriptions AppもBuilt for Shopifyで、評価は4.9（3,086件）です。無料プランは「Unlimited revenue, 50 subscriptions」。「Passwordless customer portal」を挙げるのは月額$5.95（年額$57.12）のSUPERSALEプランで、リスティングの機能説明自体が、顧客は「can easily access subscriptions (abonnements) with magic links」と謳っています。

Shopify Subscriptionsは無料で、上で見たとおり、文書化された管理画面のフローに相当するアクションはありません。

パターンは一貫しています。契約を手で作ること、そしてパスワード無しで顧客に決済情報を入れてもらうことは、現時点では有料機能です。標準のリソーススコープ付きサインイン不要リンクは、その機能の値段の意味を変えます。ただし、アプリがそれを呼んだ後の話です。

これらのアプリがpaymentInstrumentSendAddEmailを採用したかどうかは、App Storeのリスティングには書かれていません。これだけ新しいmutationについては、それは減点ではなく想定どおりの状態です。実際の答えを引き出す質問は3つです。

アプリはどのAPIバージョンを対象にしているか。 2026-07以前のものは、このmutationをそもそも呼べません。Shopify自身の注記は、それらのアプリは「are unaffected and see no change in behavior」です。機能交渉ではなく、イエスかノーのゲートです。

アプリはすでにwrite_customersを持っているか。 持っていない場合、採用にはスコープ変更とあなたの再承認が必要になります。予期しない権限プロンプトとして現れる前に知っておく価値があります。

いまカード登録依頼のメールを送ると、実際に送っているのは何か。 答えがアプリ自身のメールとアプリ自身のホスト型ポータル（両リスティングが謳うpasswordless loginやmagic links）なら、いま動く仕組みがあるということであり、移行時の挙動は別途確認すべき論点になります。答えがShopifyなら、顧客が受け取るのはShopifyの既定文面だと考えてください。mutationが読むのはfromとbccだけです。

結局どこに落ち着くか

Shopifyは実在する隙間を埋めました。そして丁寧に埋めています。送った対象以外のリソースには使えないリンクは、汎用のポータルログインより締まった設計で、3つのリソース種別はマーチャントが繰り返し突き当たるケースを覆っています。

ただし出荷された形はAPIであり、stableの1四半期手前であり、スキーマの他の部分と矛盾する識別子規約を持ち、受け取った4フィールドを捨てる入力オブジェクトを備えています。どれも致命的ではありません。ただしそのすべてが、「Shopifyはこれに対応した」と「あなたの管理画面でこれができる」の距離が、changelogの読後感より広いことを意味しています。

まずAPIバージョンを確認する。そのうえでアプリに聞く。

出典

• New paymentInstrumentSendAddEmail mutation emails customers a link to add a payment method for a subscription, order, or draft order — Shopify developer changelog、2026年9月3日
• paymentInstrumentSendAddEmail、PaymentInstrumentMandateInput、PaymentInstrumentMandateResourceType — GraphQL Admin API 2026-10
• customerPaymentMethodSendUpdateEmail — GraphQL Admin API 2026-07
• About Shopify API versioning — shopify.dev
• Managing customers、Managing subscription contracts、Shopify Subscriptions、Getting paid for draft orders、Draft orders and invoices、Importing and exporting a contract CSV — Shopifyヘルプセンター
• Shopify/subscriptions-reference-app — GitHub、コミット575a825（2026年1月2日付）
• Shopify Subscriptions、Appstle℠ Subscriptions App、Seal Subscriptions App — Shopify App Store、2026年9月17日取得