Shopify Storefront APIで作るヘッドレスEC設計｜Next.js/Hydrogen実装

「shopify storefront api」で調べる人は、単にAPI概要を知りたいだけではないはずです。Shopifyの商品をNext.jsやHydrogenで表示し、ブランドサイトやメディアに商品検索、カート、チェックアウト導線を組み込みたい段階でしょう。

Shopify公式のStorefront API referenceでは、Storefront APIは商品、コレクション、カート、チェックアウトなどの顧客向け体験を作るGraphQL APIとして説明されています。Storefront APIはGraphQLのみで、ストアフロント向けREST APIはありません。

また、Getting started with the Storefront APIでは、Headless channelでStorefront API access tokenとpermissionsを管理する流れが説明されています。現行記載では、1ショップあたり最大100 active storefronts/access tokensです。実装時は対象ストアと公式Docsで必ず確認します。

この記事では、Storefront APIを「商品を取るAPI」としてではなく、ヘッドレスECを実務システムとして動かす設計に絞ります。外部連携の境界はShopify API連携の設計方法、管理データの読み書きはShopify Admin API実装計画も合わせて見ると判断しやすくなります。

ShopifyヘッドレスECで最初に決めるべきなのは、どのフレームワークを使うかではなく、Storefront APIで公開する購入体験と、Admin API/Webhookで扱う管理業務を分けることです。

Storefront APIとAdmin APIの役割分担

Storefront APIは顧客向けの購入体験を作るAPIです。商品一覧、商品詳細、検索、カート、ログイン済みcheckoutへの引き渡しに使います。注文後の出荷、在庫更新、顧客タグ、返金、会計連携はAdmin API、Webhook、Flow、外部DBの設計です。

観点	Storefront API	Admin API/Webhook	判断ポイント
公開面	ブラウザ、アプリ、外部サイトなど顧客向け	管理画面、連携基盤、バックオフィス	顧客に見せてよいデータか
権限	Headless channelのStorefront API permissions	アプリのadmin scopes、OAuth、カスタムアプリ権限	読み取り/書き込み/顧客データを分ける
読み書き責務	商品、collection、公開metafield、cartを読む/更新する	商品、在庫、注文、顧客、metafieldを管理する	管理データ更新をStorefront APIへ寄せない
価格・在庫	顧客向け価格、販売可否、Markets文脈を表示	価格改定、在庫正本、ロケーション在庫を更新	表示価格と最終checkout価格の差分を説明する
注文作成	cartからShopify checkoutへ引き渡す	注文完了後にWebhookで処理する	カートは注文ではない

Headless channelとアクセストークン設計

ヘッドレス構成では、Headless channelがStorefront APIとCustomer Account APIへのアクセス、商品公開、permissions、credentialsの管理場所になります。実装前には、少なくとも次の台帳を作ります。

設計項目	決めること	決めないと起きること
storefront単位	本番、staging、preview、外部メディアを分けるか	どの導線がどのtokenを使っているか分からない
access token	public/private tokenの用途、保管場所、ローテーション	private tokenをclientへ出す、漏えい時に止められない
permissions	products、metafields、customers、cartなど必要権限	商品は取れるがmetafieldが見えない、または過剰公開になる
公開チャネル	Headless sales channelへの商品公開	管理画面では商品があるのにフロントに出ない
上限管理	100 active storefronts/access tokens per shopの現行上限	検証用tokenを増やしすぎる

Storefront APIのpublic access tokenはAdmin API tokenとは性質が違いますが、公開範囲はpermissionsと公開チャネルに依存します。Next.jsなら公開データをserver component、route handler、edge function、ISR層で扱い、private tokenや顧客固有情報はclient componentへ渡しません。Hydrogenならloader/actionで公開データ、cart mutation、Customer Account APIを分けます。

商品・variant・metafieldを取得するGraphQL設計

Storefront APIの商品取得では、まず「表示に必要な最小fields」を決めます。商品詳細に画像、variant、価格、metafield、selling plan、mediaを全部入れると、ページ速度と保守性が落ちます。

取得対象	Storefront APIで取る候補	設計で見ること
商品一覧	id、handle、title、featured image、価格帯、availability	一覧で購入判断に必要な項目だけにする
商品詳細	description、media、selected/available options、variants、公開metafields	variant選択、在庫表示、SEO情報を分ける
variant	id、selected options、価格、販売可否	SKUや倉庫連携キーを顧客に出す必要があるか
metafield	素材、サイズ表、注意事項、配送温度帯など公開情報	namespace/key/typeと公開範囲を台帳化する
collection/search	handle、title、商品connection、sort/filter条件	検索UX、API負荷、SEO URLを合わせる

Storefront APIで出すmetafieldは、社内管理用メタフィールドとは分けます。原価、仕入先、外部連携ID、社内メモ、WMS向けの細かい出荷指示を顧客向けAPIに出す必要はありません。

Hydrogen/Next.jsでのデータ取得とキャッシュ

Hydrogenの公式Docsでは、Storefront API dataはデフォルトでキャッシュされ、Customer Account API dataは個人別のためキャッシュされないと説明されています。Next.jsでも、キャッシュ単位は「ページ」ではなく「データの性質」で決めます。

データ	キャッシュ方針	理由
コレクション一覧	ISR、edge cache、長めのrevalidate候補	頻繁に変わらず、SEOと速度が重要
商品詳細の基本情報	ISRまたは短めのserver cache	商品更新や公開停止を反映できる余地を残す
価格・販売可否	短めcache、在庫が厳しい商材は都度確認	表示とcheckoutの差分を小さくする
カート	no-store、server action/route handlerで更新	顧客セッションごとに異なる
顧客アカウント	no-store、Customer Account API側で扱う	個人情報をキャッシュしない

HydrogenならCacheLong()、CacheShort()、CacheNone()を用途別に使います。Next.jsならfetchのcache/revalidate、CDN/edge cache、tag-based revalidationを設計します。

Storefront APIのキャッシュは、速さの設定ではなく、商品・価格・カート・顧客情報を混ぜないための運用設計です。

カート・buyer identity・checkoutUrl引き渡し

Storefront APIのCart API guideでは、cartCreate、line item更新、buyer identity更新、checkoutUrl取得までの流れが説明されています。

Cart APIは便利ですが、カートは注文ではありません。カート時点のcostは推定であり、checkoutで変更され得ます。国別価格、配送先、割引、税、配送方法、Shop Payなどで最終金額が変わる前提にします。

処理	使うAPI/field	実装で決めること
カート作成	cartCreate	variant ID、数量、初期buyer identity、attributesをどこで渡すか
明細追加/変更	cartLinesAdd、cartLinesUpdate、cartLinesRemove	在庫切れ、販売不可、数量制限のエラー表示
buyer identity	cartBuyerIdentityUpdate	email、phone、countryCode、customerAccessToken、配送希望をいつ反映するか
checkoutUrl	cart { checkoutUrl }	購入直前に取得し、staleなら再取得する
checkout後	Webhook、order status、account page	注文完了、戻る導線、計測、カート破棄を設計する

Cart IDにも注意が必要です。公式Docsでは、cart IDは<token>?key=<secret>形式で、Cart APIではfull IDが必要です。secret部分はshareable links、public pages、client-side codeに含めず、httpOnly cookie、server session、server route/actionで扱います。ログイン済みcheckoutではCustomer Account API referenceも合わせて設計します。

Markets、多通貨、checkout後の状態管理

ヘッドレスECでは、Marketsと多通貨の扱いがテーマより見えにくくなります。地域・言語・通貨をStorefront API queries、cart buyer identity、URL設計へ反映します。

論点	実装で見ること	失敗例
country/language	URLパス、サブドメイン、cookie	自動リダイレクトでSEOやキャッシュが壊れる
価格表示	@inContext、buyer identity、Markets設定	商品ページ価格とcart/checkout価格が説明できない
カート	buyerIdentity.countryCode、配送先、pickup preference	国を変えたのにcart costが古い文脈のまま
checkoutUrl	購入直前に取得、ログイン状態、buyer IP header確認	古いcheckoutUrlでログイン済み体験が崩れる
計測	GA4、広告CV、server-side events	Shopify checkoutとヘッドレス側で二重計測する

チェックアウト自体はShopify側に引き渡すため、checkoutUrl後の戻り先、注文完了表示、広告計測、カート破棄を設計します。チェックアウト本体の制約はShopifyチェックアウトカスタマイズの実装判断ガイドで扱っています。

セキュリティと監視を最初から入れる

Storefront APIのセキュリティは、管理者tokenを出さないだけでは足りません。公開範囲、キャッシュ、ログ、アラートを決めます。

観点	設計内容	監視・運用
token	public/private tokenの用途、env管理、ローテーション	token別の呼び出し元、失効手順、不要token削除
cart secret	full cart IDの保存場所、client露出防止	public pageやログにsecretが出ていないか
顧客情報	Customer Account API、no-store、PIIログ除外	個人情報がcache/CDN/logに残らないか
rate/complexity	query fields、pagination、検索条件	heavy query、429/5xxを検知
cache	公開データと個人データの分離	stale product、price mismatch
checkout	checkoutUrl取得タイミング、stale時再取得	checkout遷移率、失敗率、戻り導線

監視は開発者向けログだけでは足りません。商品取得、cart mutation、checkoutUrl、cache stale、注文後Webhook失敗を分け、誰が見るかまで決めます。

実装前チェックリスト

チェック項目	確認すること
API境界	Storefront API、Admin API、Webhook、Customer Account APIの責務を書いたか
Headless channel	storefront、token、permissions、公開商品、100 active storefronts/access tokens上限を確認したか
token管理	public/private token、env、client露出、rotation、staging分離を決めたか
商品query	商品、variant、metafield、collection、searchのfieldsを最小化したか
Markets	country/language/currency、URL設計、price表示、buyer identityを決めたか
Hydrogen/Next.js	loader/server route/server action/cache層の責務を決めたか
cart	cartCreate、line update、buyer identity、Cart ID secret管理を設計したか
checkoutUrl	購入直前取得、stale時再取得、ログイン済みcheckout、遷移後の戻りを決めたか
監視	GraphQL errors、rate/complexity、cache stale、checkout遷移率、注文後連携失敗を見ているか
QA	PC/スマホ、ログイン/非ログイン、国/通貨、割引、在庫切れ、戻る導線を確認するか

まとめ

Shopify Storefront APIは、商品、variant、公開metafield、カート、buyer identity、checkoutUrlを扱えるGraphQL APIです。ただし本番運用で重要なのは、APIを呼べることではありません。Headless channel、permissions、商品公開、Admin APIとの責務分担、Cart ID secret、Customer Account API、Markets、checkoutUrl後の状態管理、監視まで決めて初めて、ヘッドレスECとして運用できます。

Bitlightでは、Storefront APIをフロント実装の部品ではなく、購入体験と業務運用をつなぐシステムとして設計します。商品取得、カート、ログイン、チェックアウト、キャッシュ、監視、注文後連携まで、どこをShopify標準に任せ、どこをHydrogen/Next.jsで実装し、どこをAdmin API/Webhookへ渡すかを整理します。