GraphQL Admin APIで
返品ポリシープロファイルが読み取り可能に
API 2026-10 ｜ マーケット別の返品ルールを構造化データで取得
API 2026-10以降、返品ポリシープロファイル（Return Policy Profiles）がGraphQL Admin APIから取得可能になりました。マーケットごとに異なる返品条件を構造化データとして読み取れるようになり、従来のShop.shopPoliciesのテキスト取得から移行が推奨されます。ミューテーションは提供されず、読み取りのみ対応です。
1Before / After：ポリシー取得方法の変化
2追加されたクエリフィールドとスコープ
| フィールド / 操作 | 内容 | 必要スコープ |
|---|---|---|
returnPolicyProfile |
IDを指定して単一プロファイルを取得 | read_legal_policies |
returnPolicyProfiles |
ストアの全プロファイルを一覧取得。default引数でフィルタ可 |
read_legal_policies |
Market.returnPolicyProfile |
マーケットに直接紐づくプロファイルを返す。未割当はnull
|
read_legal_policies |
| マーケット作成・更新時のプロファイル割当 |
marketCreate / marketUpdate の入力フィールドで指定 |
write_markets |
| プロファイルの割当解除 |
marketUpdate で削除可能 |
write_markets |
3業務に活かせるユースケース
- 課題
- EU向けと国内向けで返品期間が異なるが、テキストポリシーでは区別できず、カスタマーサポートで混乱が生じている
- 打ち手
-
returnPolicyProfilesクエリでマーケットごとのプロファイルを取得し、フロントエンドの返品ポリシーページに市場別の返品期間を動的表示する - 効果
- 顧客が自分の地域に適した返品条件を即座に確認でき、問い合わせ件数の削減が期待できる
- 技術メモ
-
read_legal_policiesスコープが必要。EU市場はManaged Marketsの場合プロファイルがロックされており読み取りのみ可能
- 課題
- OMS（受注管理システム）で返品受付可否の判定ロジックを手動テキストから組んでおり、ポリシー変更のたびに実装修正が必要
- 打ち手
-
returnRulesフィールドを構造化データとして取得し、OMSの返品期間判定ロジックをAPI連携に切り替える - 効果
- Shopify管理画面でポリシーを更新するだけでOMSの判定ルールに自動反映され、開発工数を削減できる
- 技術メモ
-
returnRulesがnullの場合は返品無制限を意味する。nullチェックを必ず実装すること
- 課題
- 複数マーケットを持つ越境ECで、どの市場にどのポリシーが当たっているかを把握する管理ツールがなく、ポリシー設定ミスが発生する
- 打ち手
-
returnPolicyProfilesと各マーケットのreturnPolicyProfileフィールドを組み合わせてポリシー割当マップを生成し、管理ダッシュボードに可視化する - 効果
- 未割当マーケット（デフォルトプロファイル適用中）を即時発見でき、意図しないポリシー適用を防止できる
- 技術メモ
-
Market.returnPolicyProfileがnullはデフォルトプロファイル適用中を意味する。マーケット階層は解決しないため注意
4技術者目線のポイント
クエリ
新設されたreturnPolicyProfile（単一）とreturnPolicyProfiles（一覧）の2フィールドを使用。一覧にはdefault引数でデフォルトプロファイルのみ絞り込む機能あり。
スコープ設計
読み取りはread_legal_policies、マーケットへの割当変更はwrite_marketsが必要。両方行うアプリは両スコープをリクエストする。
ミューテーションなし
プロファイルの作成・更新・削除はGraphQL Admin APIからは行えない。Shopify管理画面での操作のみ。アプリからは読み取り専用として設計すること。
nullの意味
returnRules/editRulesがnullはルール無効ではなく「返品無制限」を意味する。Market.returnPolicyProfileがnullはプロファイル未割当（デフォルト適用）を意味する。意味が異なるため実装時に注意。
ユーザーエラー
同一リクエストでプロファイルの割当と解除を同時に行うとユーザーエラーが返る。Managed Marketsが自動プロビジョニングしたEUプロファイルを他マーケットに割り当てようとしてもエラーになる。
移行推奨
Shop.shopPoliciesのREFUND_POLICYでテキスト取得していた場合、returnPolicyProfilesクエリへの移行が公式推奨。既存クエリは引き続き動作するが、マーケット別ルールの表現には新APIが必須。
「返品ポリシーをマーケットごとに構造化データで管理・表示したいストアには、API 2026-10のreturnPolicyProfilesクエリへの移行を提案します。」
Source: https://shopify.dev/changelog/return-policy-profiles-are-now-available-in-the-graphql-admin-api | 公開日: 2026年10月1日
Share:
セグメントクエリ言語の関数構文が2026-10で刷新
Order Routing関数が複数フルフィルメントグループに対応