Shopify Storefront API: デベロッパーとマーチャント向け完全ガイド

Shopify Storefront API は公開GraphQL APIで、ヘッドレスストアフロント、モバイルアプリからIoT、AIエージェント統合まで、完全にカスタマイズされた購買体験を構築できます。Shopifyがコマースバックエンドを処理する間、ブラウザとモバイルクライアントから安全に呼び出せるよう設計されています。現在、安定版は 2026-04 で、テスト用の2026-07リリース候補もすでに利用可能です。

重要なポイント

• Storefront APIはクライアント側から安全に呼び出せる公開API。Admin APIはセキュアなサーバーに置く必要があります。
• カート操作(cartCreate, cartLinesAdd, cartBuyerIdentityUpdate)はすべての構築に必要なコア書き込み操作です。
• APIバージョンは四半期ごとのリリーススケジュール: 2026-01, 2026-04, 2026-07, 2026-10。旧2024-10バージョンは2026年10月にサンセットします。
• Hydrogen 2026.4.0ではStorefront APIプロキシが必須になり、バックエンドコンセントモードがデフォルト有効になりました。アップグレード前に監査が必要な破壊的変更です。
• Hydrogen 2026.1.4以降、Oxygen上のすべてのHydrogenストアフロントは /api/mcp でMCPエンドポイントを自動公開し、カスタムコードなしでAIエージェント対応のコマースエンドポイントになります。

Shopify Storefront APIとは

Storefront APIはShopifyの顧客向けGraphQL APIです。商品、コレクション、メタオブジェクト、メニューへの読み取りアクセスと、購入者が実際に行うことである2つの操作への書き込みアクセスを提供します。カート管理と顧客認証です。

Shopify公式ドキュメントはアクセスモデルをこう説明しています。Storefront APIは主に読み取り専用で、認証とカート管理が例外です。この境界線は意図的なものです。シークレット認証情報に一切触れずに、すべての商品詳細を取得し、ライブフィルターUIを構築し、完全なチェックフロー構築ができます。

エンドポイントパターンはシンプルです。

https://{your-store}.myshopify.com/api/2026-04/graphql.json

すべてのリクエストに Shopify-Storefront-Public-Token ヘッダー(またはサーバー側Hydrogenコールの場合はプライベートトークン)が必要です。このトークンはシークレットではなく、ブラウザまたはモバイルコードに埋め込めます。一方、Admin APIキーとパスワードは絶対にクライアント側コードに出現させてはいけません。

Storefront API vs. Admin API: 実際の違い

これはマーチャントとデベロッパーが最初に尋ねる質問で、答えは機能リストではなくアーキテクチャの問題です。

Admin APIはShopifyストアデータへの完全な読み取りと書き込みアクセスを提供します。注文、顧客、商品、在庫、配送、分析など。Storefront APIはこれらの管理機能を意図的に提供しません。注文を変更したり、在庫を管理したり、内部分析にアクセスしたりできません。これは回避する制限ではなく、トークンをReactコンポーネントに安全に埋め込める安全境界です。

一般的な誤り: クライアント側コードでAdmin API認証情報を使用することです。これでストア認証情報が公開されます。常にAdmin APIコールをセキュアなバックエンドサーバーに保ちましょう。ストアデータへのクライアント側アクセスが必要な場合、それがStorefront APIの目的です。

コア機能: 実際に構築できること

商品とコレクションのクエリ

商品タイトル、説明、バリアント価格、在庫ステータス、画像、メタフィールドを取得します。GraphQLでは必要なフィールドのみリクエストできるため、商品カードクエリは膨大なRESTペイロードの代わりにリーン3フィールドの応答を返します。要求したデータのみを取得する効率性と速度により、パフォーマンス重視のアプリケーションに最適です。

重要な最近の変更: GraphQL商品バリアントは商品あたり最大 2,000 をサポートするようになり、前の100バリアント上限から拡張されました。サイズxカラーxマテリアルなどの設定可能な商品を販売する場合、これは重要です。

カート操作

CartオブジェクトはすべてのStorefront API構築の中核です。現在のmutation サーフェスには以下が含まれます。

• cartCreate, 新しいカートを作成してオプションで1回の呼び出しでラインアイテムを追加
• cartLinesAdd, 1つ以上の商品バリアントを既存のカートに追加
• cartLinesUpdate, 既存の行の数量を更新(1回の呼び出しで最大250値)
• cartLinesRemove, IDで行を削除
• cartDiscountCodesUpdate, ディスコードを適用またはクリア(既存のすべてのコードを提供リストで置き換え)
• cartGiftCardCodesAdd / cartGiftCardCodesRemove, ギフトカード償却を管理
• cartBuyerIdentityUpdate, ログイン顧客を関連付け、B2B企業ロケーションを設定、配送方法などのチェックアウト設定を構成
• cartMetafieldsSet, カスタムチェックアウトロジック用に任意のメタフィールドをカートに書き込み

注目すべき最近の追加: CartLine タイプは viewKey フィールドを返すようになり、返された行を cartLinesUpdate と cartLinesRemove に送信された view_key と相互参照できます。オプティミスティックUIアップデートを構築するときに便利です。

プライバシー準拠のコンセント

Storefront APIバージョン2025-10以降、@inContext ディレクティブは visitorConsent 引数を受け入れます。これでコンセント状態をカート作成呼び出しに直接エンコードでき、結果の checkoutUrl に自動的に含まれます。その結果: 個別のクッキー書き込みレイヤーなしのGDPRとCCPA準拠フローです。

メタオブジェクトとトークンゲート付きアクセス

一部の機能には公開アクセストークンを超えたトークンベース認証が必要です。商品タグ、メタオブジェクト、メタフィールド、ストアナビゲーションメニュー、顧客データはすべてトークンスコープアクセスの背後にあります。これらのスコープのリクエストはShopify管理画面でStorefront APIアプリを作成するときに行われます。

APIバージョニング: マーチャントとデベロッパーが追跡すべきこと

Shopify Storefront APIは四半期ごとのリリーススケジュールに従います。バージョンは2026-01, 2026-04, 2026-07, 2026-10です。各バージョンはリリース後12ヶ月間サポートされます。サポートされていないAPIバージョンへの呼び出しはアプリのリストが削除されたり、インストールがブロックされたりします。

現在の重要な日付は以下のとおりです。

• 2026-04 は現在の安定版(最新)です。
• 2026-07 はリリース候補で、Shopifyの Summer 2026 Edition (コードネーム Compass) に関連付けられており、カートと商品クエリ構造への破壊的変更を含む65の商品アップデートが提供されます。
• 2024-10 は2026年10月にサンセットします。 ヘッドレスビルドがまだそのバージョンにある場合、移行までの有限の期間があります。

2026-07の破壊的変更はすべてのヘッドレスビルド、Hydrogen、Next.js Commerce、Nuxt、または完全カスタムに影響します。Shopifyはhydrogenプロジェクト用のコードモッドを提供して、クエリ移行を自動化します。

今すぐアクションを起こすべきかを評価しているマーチャント向け: 2025-04より前の任何バージョンでカスタムヘッドレスビルドを実行している場合、今四半期中にデベロッパーとバージョン監査をスケジュールしてください。バージョン監査の内容については、Shopifyデベロッパーサービスページを参照してください。

Hydrogenの接続: Storefront APIプロキシは必須になりました

Hydrogenはtypescript>Storefront API上に直接構築されたShopify React ベースのフレームワークで、2026年の2つの関係がより密接になりました。

Hydrogen 2026.4.0 (2026年4月17日リリース) は2つの破壊的変更を導入しました。

1. Storefront APIプロキシは常に有効です。 proxyStandardRoutes 設定オプションが削除されました。リクエストハンドラーがロードコンテキストにstorefront インスタンスなしで実行されると、ランタイムエラーがスローされます。プロキシを迂回しったカスタムHydrogenセットアップは更新する必要があります。
2. バックエンドコンセントモードがデフォルトです。 Hydrogenはもはやクライアント側 _tracking_consent クッキーに依存しません。コンセントはStorefront APIプロキシ経由でサーバー設定クッキーで管理されるようになりました。_tracking_consent の document.cookie を読み取るカスタムコンセントバナーは、アップグレード後に空の値を見ます。

これら2つの変更が結合されている理由: バックエンドコンセントモード全体の目的は、プロキシが欠落しているときにコンセント書き込みがサイレント失敗できないことです。プロキシが必須になることは前提条件でした。

カスタムHydrogenセットアップを実行する場合(クリーンな create-hydrogen スケルトンではないプロジェクト)、2026.4.x へのアップグレード前に createRequestHandler コールとコンセントバナーロジックを監査してください。

2026年の最大の変更: ストアフロントがAIエージェントエンドポイントになりました

これはStorefront APIの役割を最も根本的に変える発展です。

Hydrogen 2026.1.4 組み込みStorefront MCP (Model Context Protocol) プロキシサポートを追加しました。Oxygen上のすべてのHydrogenストアは /api/mcp でMCPエンドポイントを公開し、カスタムセットアップは必要ありません。実際の意味: ChatGPT、Perplexity、カスタムショッピングエージェントなどのAIアシスタントは、Storefront APIで提供されるリアルタイムデータを使用して、自然言語で商品を発見し、カートを管理し、購入者をチェックアウトガイドできます。

Shopifyは3つの異なるMCPサーフェスを公開しています。

• Catalog MCP, Shopifyマーチャント全体にわたる グローバル商品検出
• Storefront MCP, マーチャント固有の検索、ポリシー、FAQ
• Checkout MCP, プログラム的カート作成、アップデート、チェックアウト完了

Storefront MCP経由の公開商品検出は追加認証を必要としません。認証されたカート操作は、Hydrogenアプリがすでに送信している既存の Shopify-Storefront-Private-Token ヘッダーを使用します。

プロキシがストアでアクティブかどうかを確認するには: Oxygen デプロイで /api/mcp にヒットします。ShopifyのStorefront MCPサーバーに転送される場合、ライブです。

まだHydrogenにない場合、これは移行を評価する具体的な理由です。Shopify CDN上のLiquidテーマは一貫しているが固定パフォーマンスを提供します。Oxygen上のHydrogenはそのパフォーマンスベースラインにAIエージェント統合を提供し、劣化なしです。AIコマース機能のROI計算はHydrogenに有利にシフトしています。Hydrogen移行に何が関わるかについては、Shopifyヘッドレスデベロッパーページで詳しく学べます。

マーチャントとデベロッパー向け実践的チェックリスト

Hydrogenストアフロントを実行する場合:

• Storefront API 2026-04(現在の最新)にいることを確認してください
• 今では削除された proxyStandardRoutes オプションについて createRequestHandler を監査してください
• コンセントバナーが _tracking_consent ではなくサーバー設定クッキーを読むかを確認してください
• Oxygen デプロイで /api/mcp をテストして、MCPがアクティブかを確認してください
• 今すぐ2026-07リリース候補に対してテストを開始してください。10月まで待たないでください

カスタムヘッドレスビルドを実行する場合(Next.js, Nuxt など):

• 現在のAPIバージョンを特定し、2024-10の2026年10月サンセットに対してマッピングしてください
• カートと商品クエリ構造への破壊的変更について2026-07 チェンジログを確認してください
• 次の Shopify Editions サイクル前にコードモッドまたは手動クエリアップデートを計画してください

標準Liquidテーマを実行する場合:

• クライアント側でそれを呼び出すサードパーティアプリを使用する場合、Storefront APIはまだ関連しています
• これらのアプリが2026-04以降をターゲットにしていることを確認してください
• Hydrogenのエージェント機能が移行評価を正当化するかどうかを検討してください

Storefront APIはもはや単なる「ヘッドレスShopify」APIではありません。これはブラウザ、モバイル、音声、現在ではAIエージェントなど、購入者が使用する可能性のあるあらゆるサーフェスにカタログを接続するデータレイヤーです。バージョンを最新に保ち、Hydrogenセットアップをプロキシとコンセント要件に合わせることは、これらのサーフェスを開いたままにする維持作業です。