Cart に新警告コード PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION 「買えない地域の商品」が明示される

図解 ： Storefront API Cart の新警告 PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION Storefront GraphQL API 2026-07 Cart に新警告コード PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION 「買えない地域の商品」が明示される 2026-07 版の Storefront API から、購入者の所在地で取り扱い対象外の商品が Cart line に含まれていると、Cart が該当行ごとに警告を返すようになる。target には CartLine ID が入り、UI 上の行に直接マップできる。 このページの構成 そもそも何が変わるのか（30秒で理解） 仕組み図解 ： Cart 取得から警告表示までの流れ 警告の中身（コード／対象／粒度） 従来 vs 新警告コードの比較 利用条件 実装の流れ（3ステップ） 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 そもそも何が変わるのか 今まで Cart は「買えない地域の商品が混ざっている」ことをカートライン単位で明示してこなかった。 2026-07 から、その状況を カートライン 1 本ずつ別々の警告 として返してくれるようになる。 従来 ： 暗黙のまま 地域で売れない商品がカートに残っていても、専用の警告コードが無く、決済直前に気付かれる／問い合わせになる、というケースが起こりやすかった。 新規 ： 行ごとに警告 Cart の warnings に PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION が返り、 target に該当 CartLine ID が入る。UI でその行をピンポイントで赤くできる。 2 仕組み図解 ： Cart 取得から警告表示までの流れ 警告は cart line ごとに 1 件ずつ 返る。複数の不可商品が混ざっていれば、その本数だけ警告が発行されるため、UI 側で対象 line を一覧で赤色化／削除 CTA を出すといった出し分けがしやすい。 3 警告の中身（コード／対象／粒度） code PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION 。買い手の所在地で取り扱い対象外の商品がカート行に含まれていることを表す。 target 該当する CartLine ID 。UI 上のどの行に対する警告なのかを直接特定できる。 粒度 影響を受けるカート行 1 本につき 1 件の警告が発行される（複数行影響 ＝ 複数件の警告）。 4 従来 vs 新警告コードの比較 項目 従来 2026-07 以降 地域で買えない商品の検知 独自実装 自前でチェックロジックが必要 API が通知 Cart 警告として返る 影響行の特定 カート全体で曖昧 CartLine ID に target が紐づく 複数行同時の扱い — 行ごとに警告が個別発行 UI 反映 決済画面まで遅延しがち カート画面で即時赤化／削除導線が出せる 位置づけ — warning 既存の cart warnings 仕組みに乗る 5 利用条件 Storefront API 2026-07 以降 2026-07 バージョンで Cart が発行するようになる。古いバージョン固定のクライアントは恩恵を受けない。 Cart の warnings を購読 Cart クエリのレスポンスに warnings を含めて取得し、 code と target を読む実装が必要。 「買い手の所在地」がどう判定されるか（IP／配送先／マーケット設定など）の具体ロジックは本記事には 記載なし 。マーケットや国別公開設定の挙動と合わせて実機検証すること。 6 実装の流れ（3ステップ） 1 API バージョンを 2026-07 に Storefront クライアントのバージョン指定を 2026-07 以降に更新する。 2 cart クエリで warnings を取る cart { warnings { code target } } を要求して取得する。 3 該当 CartLine を赤化／削除導線 target の CartLine ID を UI 上の行にマップして警告表示・削除 CTA を出す。 背景や他の cart warning コードと一緒の扱い方は、公式の「cart warnings」ドキュメント参照が記事内で案内されている。 7 技術者が押さえるべき5つのポイント 1. errors ではなく warnings GraphQL の errors ではなく Cart の warnings として返る扱い。クエリは成功しつつ、業務的な注意点として情報が乗ってくる設計。 2. 行ごとに 1 件発行 「カートに 2 つ不可商品 → 警告 2 件」の挙動。UI 実装側は配列としてループ処理する前提で組む。 3. target = CartLine ID UI 側のデータと付き合わせる際は、CartLine ID をキーに警告を join する設計が必要。商品 ID ではない点に注意。 4. リリースは 2026-07 起点 クライアントの API バージョン固定運用をしている場合、明示的に 2026-07 に上げないとこの警告は飛んでこない。バージョンアップ計画に含める。 5. 決済画面まで持ち越さない設計に変えられる これまで「決済直前にエラーになる」だったケースを、 カート画面で先回り表示 できるようになる。離脱や問い合わせコストを減らす UX 改修の根拠として使える設計変更。 8 業務に活かせる3つのユースケース USE CASE 1 越境 EC で「決済直前エラー」をカート段階に前倒し 課題 マーケット別に商品の販売可否を設定している越境ストアで、買い手が「ロンドンから日本限定品をカート投入 → 決済画面で弾かれる」となり離脱・問い合わせが発生。 打ち手 Storefront 2026-07 に上げ、Cart の warnings から PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION を拾い、対象 CartLine をカート画面で赤化＋削除 CTA を表示。 効果 カート→決済の遷移段階のエラー離脱が減り、CS 問い合わせも減少。 技術メモ target = CartLine ID。商品 ID ではないため、UI 側で CartLine と warning を ID 突合する実装を組む。 USE CASE 2 Hydrogen / Headless ストアの汎用ハンドラに組み込み 課題 Headless 構成のストアで、Cart 警告のハンドリングがコード単位で散らばっており、新コード追加のたびに各画面で個別対応が必要。 打ち手 Cart の warnings を 1 箇所で吸い上げる共通フックを用意し、 code === 'PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION' を含めた既知コードを enum で集中管理。 効果 新警告コード追加時の改修コストが下がり、UI 表現のブレも防げる。 技術メモ 公式 docs「cart warnings」と整合させて、表示文言は i18n 辞書に集約。target は line 単位なので、行コンポーネントに props で渡す設計が無難。 USE CASE 3 カート離脱の原因分析にイベントとして活用 課題 カート離脱は計測しているが「なぜ離脱しているか」の内訳が薄く、地域不可商品の影響度を定量化できていない。 打ち手 Cart 取得時に PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION 警告が立ったセッションをタグ付けし、分析基盤（GA4 / BigQuery 等）へイベント送出。 効果 「地域不可商品が原因のカート離脱」の規模感が見え、マーケット別の品揃え／販売地域設定の優先順位を意思決定できる。 技術メモ warning は line ごとに 1 件出る前提なので、セッション集計時は重複排除（distinct CartLine）か件数集計のどちらにするかを事前に決めておく。 9 提案で使える1行サマリ 「Storefront API 2026-07 から、Cart が 『買えない地域の商品』をカート行ごとに警告 してくれる。 決済直前で弾かれていたエラーを カート画面に前倒し でき、越境 EC・Headless ストアの離脱率改善に直結する。」 source ： shopify.dev / changelog / PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION generated 2026-05-23