Return policy profiles マーケット別の返品ルールを「構造化データ」で読めるように

図解 ： Return policy profiles が GraphQL Admin API で利用可能に（API 2026-10） GraphQL Admin API 2026-10 / 新機能 Return policy profiles マーケット別の返品ルールを「構造化データ」で読めるように 返品ポリシーの文章ではなく、返品期間などのルールをマーケットごとに API から取得できるようになった。プロファイルはストアの返品ポリシー本文より優先される。API からは読み取り専用。 このページの構成 そもそも何が変わるのか（30秒で理解） 仕組み図解 ： プロファイルとマーケットの関係 追加された API 必要なアクセススコープ 実装で気をつける挙動 含まれないもの と アプリ側でやること 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 そもそも何が変わるのか API バージョン 2026-10 から、GraphQL Admin API で 返品ポリシープロファイル（ReturnPolicyProfile） を読めるようになった。 プロファイルはマーケットに紐づける返品ルールのセットで、 ストアの返品ポリシー本文より優先される 。アプリはマーケットごとの返品ルール（返品期間の長さなど）を構造化データとして取得できる。 これまで ： ポリシーは「文章」 Shop.shopPolicies の REFUND_POLICY などから返品条件をテキストで読むしかなかった。 これから ： ルールは「構造化データ」 マーケットごとの返品ルールをフィールド単位で取得できる。マーケット別に異なる返品ルールを表すにはプロファイルを使う必要がある。 2 仕組み図解 ： プロファイルとマーケットの関係 1 プロファイル = 1 ルールセット どのマーケットからも参照できる プロファイルは返品ルールを設定する単位で、マーケットが紐づく先。 影響範囲に注意 編集は参照中の全マーケットに効く プロファイルを編集すると、それを参照するすべてのマーケットの返品条件が変わる。 EU 規制 Managed Markets の EU 用はロック 返品の最低基準を下回らないようロックされている。アプリは読めるが、他マーケットには割り当てられない。 3 追加された API 種類 名前 内容 Query returnPolicyProfile ID を指定して 1 件のプロファイルを返す Query returnPolicyProfiles ストアのプロファイル一覧を返す。 default 引数でデフォルトかどうかで絞り込める Field Market.returnPolicyProfile そのマーケットに直接割り当てられたプロファイル（無ければ null） Mutation 入力 marketCreate / marketUpdate マーケット作成・更新時にプロファイルを割当。更新時は割当の解除もできる（入力フィールドは各リファレンス参照） 4 必要なアクセススコープ 読む ： read_legal_policies プロファイルの読み取り（ Market の returnPolicyProfile フィールドを含む）に必要。 割り当てる ： write_markets マーケットへのプロファイル割当・解除は「マーケットの編集」扱い。 読み取りと割当の両方を行うアプリは、 両方のスコープ をリクエストする。 5 実装で気をつける挙動 null の意味 ① Market.returnPolicyProfile が null そのマーケットに 直接 割り当てられたプロファイルが無いという意味。マーケット階層は解決しない。 null の意味 ② returnRules / editRules が null データ欠損ではなく そのルールが OFF という意味。 returnRules が null のプロファイルでは、顧客は制限なく返品できる。 更新検知 updatedAt は集約値 プロファイル行に直接書かれた値ではなく、プロファイルとルール全体から集約される。ポリシーのどこかが変わると進む。 user error エラーになる 2 パターン ① マーケット更新時、同一リクエストで割当と解除を両方指定 ② Shopify が用意した Managed Markets プロファイルをマーケットに割当。 6 含まれないもの と アプリ側でやること プロファイル自体の mutation は無い。 作成・更新・削除は Shopify 管理画面で行い、API からは読み取り専用。 1 必須の変更はなし ポリシー本文を読む既存クエリはそのまま動く。 2 REFUND_POLICY 依存を移行 Shop.shopPolicies の REFUND_POLICY から返品条件を読んでいるなら returnPolicyProfiles へ。 3 マーケット別ルールはプロファイルで マーケットごとに異なる返品ルールを表すには、プロファイルを使う必要がある。 7 技術者が押さえるべき5つのポイント 1. 「null」を 2 通りに読み分ける Market.returnPolicyProfile の null は「直接割当なし」。 returnRules の null は「ルール OFF ＝ 制限なく返品可」。どちらも「データ無し」扱いにすると誤表示になる。 2. 階層解決はアプリ側の責務 API はマーケット階層を解決しない。未割当マーケットにはデフォルトプロファイルが適用される仕様なので、実効ルールを出すなら returnPolicyProfiles(default: …) でデフォルトを引いて補う設計に。 3. キャッシュ無効化は updatedAt で プロファイル配下のルール変更でも進む集約値なので、変更検知キーとして使える。プロファイル編集は参照中の全マーケットに波及する点も合わせて考慮。 4. API は読み取り専用＋割当だけ プロファイルの CRUD は管理画面のみ。アプリが触れるのは marketCreate / marketUpdate での割当・解除だけ（ write_markets ）。 5. user error になる操作を事前に弾く 同一の marketUpdate で「割当」と「解除」を同時に送らない。Managed Markets の EU 用（ロック済み）プロファイルは割当候補の UI から除外しておく。 8 業務に活かせる3つのユースケース USE CASE 1 返品アプリ／返品ポータルで「マーケット別の返品期間」を正しく判定 課題 返品受付アプリが REFUND_POLICY の文章や独自設定に依存し、マーケットごとに違う返品条件を反映できていない。 打ち手 returnPolicyProfiles と Market.returnPolicyProfile で各マーケットのルールを取得し、受付可否の判定に使う。 効果 管理画面で設定したルールとアプリの判定が一致し、二重管理がなくなる。 技術メモ read_legal_policies が必要。 returnRules が null なら「制限なし」として扱う。直接割当が null のマーケットはデフォルトプロファイルで補完。 USE CASE 2 越境ストアのマーケット設定を自動化する際の返品ルール割当 課題 多国展開でマーケットを作る運用ツールがあるが、返品条件の紐づけは手作業で漏れが出やすい。 打ち手 管理画面で名前付きプロファイルを用意 → ツールから marketCreate / marketUpdate で該当プロファイルを割当。 効果 マーケット追加時に返品条件も同時に確定し、設定漏れを防げる。 技術メモ write_markets が必要。割当と解除を同一リクエストに混ぜない。Managed Markets の EU 用プロファイルは割当不可（user error）なので候補から除外。 USE CASE 3 マーケット別の返品条件を一覧化し、変更を検知する 課題 どのマーケットにどの返品条件が効いているか、運用・CS チームが把握しづらい。プロファイル編集が複数マーケットに波及することにも気づきにくい。 打ち手 定期的にプロファイルとマーケットの割当を取得して一覧化し、 updatedAt の変化で変更を通知する。 効果 返品条件の現状と変更が可視化され、CS 対応や社内確認がしやすくなる。 技術メモ updatedAt はルール変更でも進む集約値なので差分検知キーに使える。Webhook についての記載はなし。 9 提案で使える1行サマリ 「API 2026-10 から、マーケットごとの返品ルールを GraphQL Admin API で構造化データとして読める。 既存アプリは改修不要。ただしマーケット別の返品条件を扱うならプロファイルへの移行が必須。 API は読み取り専用で、アプリから操作できるのはマーケットへの割当だけ。」 source ： shopify.dev / changelog / return-policy-profiles-are-now-available-in-the-graphql-admin-api published 2026-10-01