Shopify Cart APIの仕組み

はじめに

Ajaxカート（ページを移動せずにカート操作が完結する仕組み）が便利なのは分かったとして、裏側では何がどう動いているのか。外注や社内のエンジニア、あるいはAIエージェント（AIによる開発支援）に実装を任せるにしても、発注する側が全体の流れを把握しているかどうかで、やり取りのスムーズさは大きく変わります。

この記事では、Shopify Storefront API（外部のサイトからShopifyのカートを操作するための窓口）を使ったAjaxカートの仕組みを、コードを一切出さずに解説します。読み終わる頃には、「カートがどういう部品で成り立っていて、どこに注意が要るのか」を自分の言葉で説明できるようになるはずです。

カート操作はAPIへの「お願い」でできている

Storefront APIとGraphQL

ShopifyのStorefront APIは、GraphQL（グラフキューエル。欲しいデータや実行したい操作を指定してサーバーに問い合わせる方式）でやり取りします。フロント側（ユーザーが見ている画面)から「この商品をカートに追加して」とお願いの文面を送ると、Shopifyが処理をして結果を返してくる。カート操作はすべて、このお願いと返事の往復でできています。

5つの基本操作

カートに必要な操作は、次の5つに整理されています。

表の通り、「作る・入れる・変える・外す・見る」の5種類だけ。日常のカート操作は、この組み合わせですべて表現できます。

カートIDという引換券

カートを作ると、Shopifyから「カートID」という識別番号が発行されます。以降の操作はすべて、このIDを添えて「このカートに追加して」とお願いする形になります。クリーニング店の引換券のようなもので、これを失くすとどのカートの話か分からなくなるため、IDの保管がカート実装の要になります。あわせて、購入手続きページへ進むための専用URL（checkoutUrl）も発行され、「購入手続きへ」ボタンの行き先はこのURLです。

カートが動く3つの場面

初回訪問時 — カートを作ってIDを保管する

ユーザーが初めてサイトに来たときは、まだカートが存在しません。そこでcartCreateでカートを作り、発行されたIDをブラウザ内の保存領域（ローカルストレージ）にしまっておきます。

図を一言でまとめると、「カートを作って、引換券をブラウザにしまっておく」流れです。

商品追加時 — 先に画面を更新し、あとで答え合わせ

商品を追加するとき、APIの返事を待ってから画面を変えると、その間ユーザーには何も起きていないように見えます。そこで、お願いを送ると同時に画面を先に更新してしまい、返事が来たら答え合わせをする方式をとります。

図を一言でまとめると、「先に画面を変えておき、失敗したときだけ巻き戻す」流れ。これが楽観的UI更新（Optimistic UI）と呼ばれる考え方で、体感速度を上げる中心的な工夫です。

再訪問時 — 引換券でカートを復元する

ユーザーが後日戻ってきたときは、保管しておいたカートIDを取り出し、cartQueryで中身を取得して画面に反映します。これで「この前カートに入れた商品がちゃんと残っている」状態になります。

図を一言でまとめると、「引換券を出して、預けてあったカートを受け取る」流れです。

画面側でカートの状態をひとつに保つ

状態管理という考え方

カートの中身は、ヘッダーのアイコン、ミニカート、カートページと、画面のあちこちに表示されます。それぞれが別々に情報を持つと食い違いが起きるため、カートの状態はアプリ全体でひとつだけ持ち、どの表示もそこを参照する形にします。この役割を担うのが状態管理と呼ばれる仕組みで、React標準のContextや、より軽量なZustandといった道具が使われます。どれを選ぶかより、「カートの真実がひとつの場所にある」ことが大切です。

AIエージェントに任せた部分

正直、GraphQLのお願いの文面や状態管理の細かい書き方は、AIエージェントに書いてもらいました。こちらで押さえたのは、この記事で書いているような「どの場面で、どの操作を、どの順番で行うか」という設計の部分。流れさえ把握していれば、実装の細部は任せられるという感覚です。

運用で押さえておく点

カートには有効期限がある

Shopifyのカートには有効期限があり、通常は10日間で無効になります。期限切れのカートIDで操作するとエラーが返るので、そのときは新しいカートを作り直す動きをあらかじめ用意しておきます。ユーザーから見れば「カートが空に戻っていた」だけで済むように、静かに作り直すのがポイントです。

よくあるエラーと対処

エラーは起きる前提で、対処をセットで決めておきます。

表の通り、どのエラーも「ユーザーを行き止まりにしない」ことが対処の軸になります。

全体の構成図

図を一言でまとめると、「画面まわりは自作、カートの帳簿と決済はShopifyに任せる」という分担です。

まとめ

Ajaxカートの裏側は、①カートを作ってIDを保管する、②5つの基本操作でお願いを送る、③状態管理でカートの真実をひとつに保つ、④先に画面を更新して失敗時だけ巻き戻す、⑤期限切れやエラー時の動きを決めておく、という5点で成り立っています。

コードが書けなくても、この流れを押さえておけば、実装を任せるときの会話は十分成立します。カートの基本やUXの工夫については、下の記事もどうぞ。