Payment Mandate に
id フィールドが追加
API 2026-07〜 | CustomerPaymentMethod のマンデート特定がシンプルに
API バージョン 2026-07 以降、PaymentMandateResource オブジェクトに新たな id フィールドが追加されます。この id は紐づく CustomerPaymentMethod.id と同一の値であり、1つの決済手段（ペイメントインストゥルメント）が複数のマンデートタイプに関連付けられている場合でも、特定スコープ（例: SUBSCRIPTIONS）向けのマンデートがどの決済手段に対応するかを正確に特定できるようになります。
01変更内容の図解：Before / After
USE CASES02業務に活かせる具体的ユースケース
- 課題
- 定期購入（サブスクリプション）ユーザーがクレジットカードを複数枚登録しており、どのカードがサブスク用マンデートを持つかが判別できなかった。
- 打ち手
-
mandatesコネクションを取得し、PaymentMandateResource.idをCustomerPaymentMethod.idと照合してSUBSCRIPTIONSスコープのマンデートに紐づくカードを特定する。 - 効果
- サブスク更新時に正しい決済手段を確実に選択でき、決済失敗率を低減できる。
- 技術メモ
- API 2026-07 以降が必須。
CustomerPaymentMethodのmandatesコネクションにidフィールドを追加するだけで対応可能。
- 課題
- 1枚のカードが「サブスクリプション」「都度課金」など複数のマンデートタイプに紐づいており、UI上でどのマンデートがどの決済手段に属するかを表示できなかった。
- 打ち手
- 各
PaymentMandateResourceのidを使って、管理画面やカスタマーポータルに「このカードが利用されるマンデート一覧」を正確に表示する。 - 効果
- 顧客が自分の決済設定を直感的に理解・管理できる体験を提供でき、問い合わせ削減につながる。
- 技術メモ
-
idはCustomerPaymentMethod.idと同値なので、追加の API コールは不要。
- 課題
- マンデートスコープごとに異なる処理ロジックを実行したいが、どの
CustomerPaymentMethodに対してアクションを起こせばよいかコード上で特定できなかった。 - 打ち手
- バックエンド処理で
PaymentMandateResource.idを取得し、その値でcustomerPaymentMethodクエリを直接実行してスコープ別の分岐処理に使う。 - 効果
- マンデート起点でペイメントメソッドを逆引きする処理フローが簡潔になり、コード複雑度が下がる。
- 技術メモ
- id は GID 形式の想定。元記事には具体的な型の記載なし。公式スキーマを要確認。
03技術者目線のポイント
対象APIバージョン
2026-07 以降で有効。それ以前のバージョンでは PaymentMandateResource に id フィールドは存在しない。旧バージョンでクエリを実行してもフィールドが返らない点に注意。
idの同一性
PaymentMandateResource.id の値は、対応する CustomerPaymentMethod.id と同一。新たな識別子が増えるわけではなく、既存の CPM ID を mandates 側から参照できるようになるイメージ。
複数マンデートタイプの扱い
1つの決済手段が複数のマンデートタイプ（例: SUBSCRIPTIONS・その他）に関連付けられているケースで特に有効。スコープを指定したフィルタリングと組み合わせることで、意図した CPM を確実に絞り込める。
取得経路
CustomerPaymentMethod オブジェクト上の mandates コネクション経由で PaymentMandateResource を取得する。mandates コネクションの詳細な引数やページネーション仕様は公式ドキュメントを参照のこと。
後方互換性への影響
フィールドの追加のみの変更であり、既存クエリへの破壊的変更はない。ただし 2026-07 未満のバージョンに固定しているアプリは、新フィールドを使うために API バージョンのアップグレードが必要。
Liquidへの影響
元記事の記載なし。本変更は Admin GraphQL API の PaymentMandateResource オブジェクトに関するもので、Liquid テンプレートへの直接的な影響については公式ドキュメントの確認を推奨。
「1決済手段・複数マンデート」構成の複雑な定期購入フローも、PaymentMandateResource.id を使えばマンデート起点で正確なペイメントメソッドを特定でき、サブスク決済ロジックの実装が大幅にシンプルになります。
Source: https://shopify.dev/changelog/payment-mandates-id-field | 公開日: 2026年6月27日
Share:
販売チャネルアプリの注文帰属設定が強化