Shopify Admin API実装計画｜GraphQLで商品・在庫・注文を安全に扱う設計手順

「shopify admin api」で調べる人は、Admin APIの概要だけを知りたいわけではありません。多くの場合、商品マスタを外部から更新したい、在庫数をWMSから戻したい、注文を基幹や会計へ渡したい、顧客情報やメタフィールドをCRMやPIMと同期したい、という実装直前の課題を抱えています。

Shopify公式のGraphQL Admin API referenceでは、Products、Inventory、Orders、Customers、Metafieldsなど、Shopify管理画面側のデータを扱う広いスキーマが用意されています。2026年7月3日時点のlatestは2026-07です。

ただし、公式リファレンスを読むだけでは「本番運用に入れてよい設計か」は判断できません。この記事では、API種類の選び方を扱ったShopify APIの種類と選び方とは重複させず、GraphQL Admin APIを本番実装する前の計画に絞って整理します。

GraphQL Admin APIの実装計画で最初に決めるべきなのは、どのMutationを使うかではなく、商品・在庫・注文・顧客・メタフィールドごとの読み書き責任です。

先に結論：実装前に6つの台帳を作る

GraphQL Admin APIは強力です。必要なフィールドだけをQueryで取り、Mutationで管理データを更新できます。一方で、権限、スコープ、rate limit、APIバージョン、ID体系、エラー処理を曖昧にしたまま本番に入れると、後から復旧できない連携になります。

本番実装前に、最低でも次の6つを作ります。

台帳	決めること	作らないと起きること
対象データ台帳	商品、バリエーション、在庫、注文、顧客、メタフィールドの読み書き境界	外部DBとShopifyのどちらが正しいか分からなくなる
スコープ台帳	read_products、write_inventoryなど必要最小限のスコープ	本番ストアで権限不足、または過剰権限になる
APIバージョン台帳	利用バージョン、更新周期、変更確認担当	四半期リリース後に非推奨項目で壊れる
ID対応台帳	GraphQL ID、SKU、外部商品ID、注文番号、顧客ID	再実行時に別レコードを作る、または更新対象を誤る
処理方式台帳	通常Query/Mutation、ページネーション、Bulk Operationsの使い分け	夜間バッチがrate limitに当たり続ける
障害復旧台帳	userErrors、再試行、冪等性、手動補正、ログ項目	失敗した注文や在庫を安全に再実行できない

GraphQL Admin APIの実装は、コードより前にこの台帳を作る仕事です。台帳があれば、開発者、EC担当、倉庫、CS、会計担当が同じ前提で運用できます。

GraphQL Admin APIで扱う対象を分ける

Admin APIは「管理側データ」を扱うAPIです。顧客向けの商品表示やカート体験を作るStorefront APIとは目的が違います。受注、在庫、商品、顧客、メタフィールドのように、Shopify管理画面にある業務データを外部と連携する場合に中心になります。

対象データ	読み取りの例	書き込みの例	人手確認を残す境界
商品	商品名、ステータス、SKU、タグ、コレクション	外部PIMから商品属性や公開状態を更新	販売文言、画像、公開判断をEC担当が調整する場合
バリエーション	SKU、価格、JAN、オプション、在庫管理対象	SKU単位の価格やメタフィールドを更新	色・サイズ展開の追加削除を人が確認する場合
在庫	ロケーション別の在庫、InventoryItem、InventoryLevel	WMSから販売可能数を戻す	差異調整、棚卸し、引当異常の判断
注文	支払状態、配送先、明細、割引、税、返金	注文タグ、メタフィールド、フルフィルメント関連の更新	住所不備、高額注文、不正疑い、返金承認
顧客	氏名、メール、タグ、購入履歴、同意状態	顧客タグ、外部CRM ID、社内分類	個人情報、配信同意、重複顧客の統合判断
メタフィールド	商品仕様、出荷条件、外部ID、社内フラグ	metafieldsSetなどで独自項目を更新	namespace/key/typeの追加変更、公開範囲の判断

商品とバリエーションは特に混同しやすいです。商品全体で同じ素材や説明文は商品側、SKUごとに変わるJAN、容量、倉庫連携キーはバリエーション側で扱います。メタフィールド設計はShopifyメタフィールド設計ガイドでも詳しく整理していますが、Admin API実装では「どのownerIdに書くか」まで落とす必要があります。

RESTとの現在地を明確にする

ShopifyのREST Admin APIは、2024年10月1日以降legacy APIです。公式のREST Admin API referenceでも、2025年4月1日以降の新規公開アプリはGraphQL Admin APIだけで構築する必要があると説明されています。

実務上は、既存REST連携をすぐ全停止する話ではありません。判断は次のように分けます。

状況	判断	実装計画でやること
既存REST連携が動いている	短期は保守対象として扱う	エンドポイント、APIバージョン、呼び出し頻度、失敗ログを棚卸しする
新規で商品・在庫・注文連携を作る	GraphQL Admin APIを第一候補にする	REST前提の記事や古いサンプルをそのまま採用しない
外部ベンダーがRESTしか対応していない	期限付きで受け入れる	ベンダーのGraphQL対応予定と移行計画を確認する
RESTの数値IDを外部DBが持っている	GraphQL IDへ橋渡しする	admin_graphql_api_idやlegacyResourceIdを使って対応表を作る

RESTからGraphQLに移ると、IDも設計し直す必要があります。GraphQL Admin APIではgid://shopify/Product/123456789のようなGlobal IDを扱います。外部DB側ではSKU、外部商品ID、注文番号、顧客メールだけに頼らず、GraphQL IDと外部キーの対応を保存します。

認証、アクセストークン、スコープを最小化する

GraphQL Admin APIのリクエストには、有効なShopifyアクセストークンが必要です。公式Docsでも、直接HTTPで呼ぶ場合はX-Shopify-Access-Tokenヘッダーを付けると説明されています。公開アプリやカスタムアプリでは、OAuthやShopify管理画面でのインストールを通じてトークンを得ます。

ここで重要なのは、トークンを得ることではなく、スコープを最小にすることです。Shopify公式のAPI access scopesでは、アプリは認可時に特定のストアデータへのアクセスを要求すると説明されています。

実装対象	主なスコープ候補	注意点
商品・バリエーション	read_products、write_products	商品を読むだけならwriteを付けない。販売文言の上書き範囲を決める
在庫	read_inventory、write_inventory、read_locations	ロケーション単位で更新するため、在庫正本と場所の対応が必要
注文	read_orders、write_orders	60日を超える注文取得や保護された顧客データは追加要件を確認する
フルフィルメント	read_fulfillments、write_fulfillments、FulfillmentOrder系スコープ	WMSや3PLとの責任範囲を間違えると出荷状態がズレる
顧客	read_customers、write_customers	個人情報、配信同意、CRM連携の正本を決める
メタオブジェクト	read_metaobjects、write_metaobjects	Shopify内で構造データを持つ場合のみ付ける

スコープを変更すると、再認可や再インストールが必要になることがあります。開発中に「とりあえず全部付ける」と、本番審査や社内統制で説明できません。逆に最小にしすぎて本番で失敗するのも困るため、対象データ台帳とスコープ台帳をセットで作ります。

APIバージョンを固定し、更新日を運用に入れる

Shopify APIは四半期ごとに新しい安定版が出ます。公式のAPI versioningでは、安定版は最低12か月サポートされ、リクエストでは常にバージョンを指定することが推奨されています。2026年7月3日時点では、GraphQL Admin APIのlatestは2026-07です。

実装では、次のように扱います。

項目	推奨方針
本番利用バージョン	2026-07のような安定版を明示する
エンドポイント	https://{shop}.myshopify.com/admin/api/2026-07/graphql.jsonのように固定する
リリース候補版	本番では使わず、次期検証に限定する
unstable	早期検証だけに使い、本番処理から分離する
更新周期	四半期ごとにDeveloper changelog、API health、非推奨フィールドを確認する
監視	レスポンスのX-Shopify-API-Versionをログに残し、想定と違う場合に検知する

バージョン固定は、古いまま放置するためではありません。いつ、誰が、どのテストで次のバージョンへ上げるかを決めるためです。

QueryとMutationを業務処理に対応させる

GraphQLでは、読み取りをQuery、書き込みをMutationで扱います。Admin API実装では、QueryやMutationの名前だけでなく、業務処理単位に分解します。

業務処理	Queryで読むもの	Mutationで書くもの	設計上の注意
商品マスタ同期	商品ID、バリエーションID、SKU、既存メタフィールド	商品属性、タグ、メタフィールド	Shopifyで編集する項目を外部同期で上書きしない
在庫更新	InventoryItem、Location、現在のInventoryLevel	ロケーション別在庫数量	SKUだけでなくInventoryItemとLocationの対応を保存する
注文連携	注文、明細、支払状態、配送先、顧客、メタフィールド	連携済みタグ、外部連携ID、必要な注文メタフィールド	注文作成直後では支払や不正判定が未確定のことがある
顧客連携	顧客ID、メール、電話、タグ、同意状態	CRM ID、顧客タグ、社内分類	配信停止や保護された顧客データを軽く扱わない
メタフィールド更新	ownerId、namespace、key、type、既存値	metafieldsSetなど	userErrorsを必ず保存し、失敗項目だけ再実行できるようにする

GraphQLは「必要なフィールドだけ取れる」ため便利ですが、クエリに業務判断を詰め込みすぎると保守しにくくなります。出荷対象注文を取るQuery、外部連携IDを書き戻すMutation、失敗分を再実行するMutationを分け、ログ上で追える粒度にします。

ページネーション、query cost、rate limitを処理方式に落とす

ShopifyのAPI limitsでは、GraphQL Admin APIはcalculated query costで制限されます。標準プランでは100 points/second、Advanced Shopifyでは200、Shopify Plusでは1000、Commerce Componentsでは2000 points/secondが目安として示されています。さらに、単一クエリはcost 1,000 pointsを超えられず、配列入力は最大250件です。

この制限を「APIをゆっくり呼ぶ」だけで解決しようとすると、夜間バッチや全件同期で詰まります。

観点	通常Query/Mutationでよいケース	設計で注意すること
少量更新	1注文、1商品、数十件のメタフィールド更新	入力配列250件制限、失敗項目の切り分け
定期差分	更新日時で絞った商品・注文の差分取得	first、after、検索条件、対象件数の見積もり
大量初期同期	数万件の商品、注文、顧客の取得	Bulk Operationsを検討する
管理画面操作	スタッフが押したボタンで1件処理	レスポンス時間、二重クリック、再実行
Webhook後処理	イベントを受けて対象1件を取り直す	Webhook payloadだけで判断せず、必要なら最新状態をQueryする

ページネーションでは、edges、node、pageInfo、endCursorを使って次ページを取得します。毎回全件をなめるのではなく、更新日時やステータスで絞り、1回のQueryで必要以上に深いネストを取らないようにします。

GraphQL Admin APIのrate limit対策は、待機時間を増やすことではなく、重いクエリを作らない設計と、通常処理・差分処理・Bulk処理の分離です。

Bulk Operationsは全件取得の逃げ道ではなく別処理として設計する

大量データを取る場合は、Shopify公式のBulk Operationsを検討します。GraphQL Admin APIのBulk Operationsは、大量データを非同期で取得し、完了後にJSONLファイルとしてダウンロードできる仕組みです。2026-01以降のAPIバージョンでは、bulk query operationを1ストアあたり最大5つまで同時に実行できます。

ただし、Bulk Operationsは通常APIの代替ではありません。

処理	通常API	Bulk Operations
注文作成Webhook後に1注文を処理	向く	向かない
商品1件のメタフィールドを更新	向く	向かない
数万商品の初期棚卸し	場合により重い	向く
過去注文を分析用DBへ投入	場合により重い	向く
管理画面で即時結果を返す	向く	向かない
大量データをストリーミングで処理	通常JSONだとメモリ負荷が高い	JSONLを1行ずつ処理できる

Bulk Operationsを使う場合は、bulkOperationRunQueryで開始し、完了Webhookまたはポーリングで状態を確認し、urlやpartialDataUrlから結果を取得します。JSONLは一括でメモリに載せず、1行ずつ処理します。完了ファイルのURLには有効期限があるため、取得、保存、再実行方針も設計に含めます。

冪等性、再試行、userErrorsを本番仕様に入れる

API実装で最も危険なのは、成功時だけを見て本番投入することです。ShopifyのMutationは、HTTPとして成功しても、レスポンス内のuserErrorsで業務エラーを返すことがあります。field、message、codeを保存しなければ、どの商品・注文・メタフィールドがなぜ失敗したか追えません。

失敗パターン	起きること	実装方針
権限不足	読み取り・書き込み対象にアクセスできない	スコープ台帳と実際のGranted scopesを照合する
ID不一致	商品、バリエーション、InventoryItem、Locationを取り違える	GraphQL IDと外部キーの対応表を持つ
入力値エラー	型不一致、必須項目不足、配列250件超過	validationエラーを項目単位で保存する
rate limit	throttleされて処理が進まない	costを見て待機、分割、Bulk化を判断する
一時障害	ネットワーク、Shopify側一時エラー	exponential backoffで再試行し、上限後に保留へ送る
二重実行	同じ注文や在庫更新を複数回処理する	冪等キー、外部連携ID、処理済み状態を保存する
部分成功	100件中一部だけ失敗する	成功分と失敗分を分け、失敗分だけ再実行する

冪等性は、注文連携と在庫更新で特に重要です。同じWebhookが複数回来ても、同じ注文をWMSへ二重送信しない。同じ在庫更新を再実行しても、差分加算ではなく期待値へのセットとして扱う。外部連携IDや処理キーをメタフィールドまたは連携DBに保存し、再実行しても結果が同じになるようにします。

ログは「開発者向け」ではなく「運用者が復旧できる形」で残す

ログは、HTTPステータスとエラーメッセージだけでは足りません。本番運用では、EC担当やCS担当が「どの注文が止まっているのか」「再実行してよいのか」を判断できる必要があります。

ログ項目	残す理由
shop domain	複数ストア対応時に混同しない
API version	バージョン差分による失敗を切り分ける
operation name	どのQuery/Mutationか分かるようにする
GraphQL ID	Shopify上の対象を特定する
外部キー	SKU、外部商品ID、WMS注文ID、CRM顧客IDと照合する
requested cost / actual cost	重いQueryやrate limit原因を確認する
userErrors	field、message、codeを再実行判断に使う
retry count	自動再試行中か、人手対応が必要か分ける
idempotency key	二重処理ではないか確認する
手動補正メモ	人が対応した理由と結果を残す

ログの見せ方まで含めて設計します。開発者しか読めないログファイルではなく、管理画面、スプレッドシート、Slack通知、チケットなど、運用担当が見る場所へ必要な情報を出します。外部連携全体の設計はShopify API連携の設計方法でも扱っています。

APIを使わない判断も残す

GraphQL Admin APIを使えるからといって、すべてをAPI化する必要はありません。むしろ、本番実装計画では「APIを使わない処理」を明示した方が安全です。

要件	APIを使わない候補	API実装に進む境界
商品ページに注意文を出す	メタフィールド、テーマ、Liquid	外部PIMから継続同期する、承認フローがある
低在庫通知	Shopify Flow、既存アプリ	複数倉庫、売上速度、発注候補まで見る
注文タグ付け	Shopify Flow	複雑な外部DB参照や再実行ログが必要
CSVで月1回更新	管理画面CSV、一括編集	更新頻度が高い、差分追跡や失敗復旧が必要
商品情報の一括整備	管理画面、PIM、既存アプリ	Shopify外の正本から自動反映する必要がある
受注CSV出力	既存アプリ、iPaaS	WMS連携、返金、在庫戻し、監査ログまで必要

APIを使わない判断は、弱い判断ではありません。管理画面、Flow、Liquid、既存アプリ、CSVで安全に回るなら、その方が保守しやすいことがあります。API実装に進むのは、データ正本、権限、再実行、監査、外部システムとの責任分界が必要なときです。

実装前チェックリスト

最後に、GraphQL Admin APIを本番実装する前のチェックリストを置きます。

チェック項目	確認する内容
対象データ	商品、バリエーション、在庫、注文、顧客、メタフィールドの読み書き境界を書いたか
APIを使わない範囲	Flow、Liquid、管理画面、CSV、既存アプリで済ませる処理を分けたか
認証	公開アプリ、カスタムアプリ、管理画面内アプリのどれか決めたか
アクセストークン	保存場所、ローテーション、削除時処理、漏えい時対応を決めたか
スコープ	必要最小限のread/writeスコープにしたか
保護された顧客データ	注文・顧客情報の追加要件を確認したか
APIバージョン	本番利用バージョンを固定し、更新周期を決めたか
ID設計	GraphQL ID、SKU、外部ID、注文番号、顧客IDの対応を保存するか
Query設計	operation name、取得フィールド、ページネーション、検索条件を決めたか
Mutation設計	入力単位、部分失敗、userErrors、再実行範囲を決めたか
cost監視	requested cost、actual cost、throttle状態をログに残すか
Bulk Operations	初期同期や大量棚卸しを通常APIと分けたか
冪等性	同じ処理を再実行しても二重登録・二重送信しないか
再試行	一時エラー、権限エラー、業務エラーを分けたか
運用ログ	EC担当が対象注文・商品・在庫を確認できる形で残すか
手動補正	自動処理できない例外を誰がどう戻すか決めたか

この表を埋められない段階で実装を急ぐと、動くAPI連携にはなっても、運用できるAPI連携にはなりません。

まとめ

Shopify Admin APIは、管理データを扱う強力な入口です。GraphQL Admin APIを使えば、商品、バリエーション、在庫、注文、顧客、メタフィールドを細かく読み書きできます。

しかし、本番運用で必要なのは、APIの呼び方だけではありません。RESTのlegacy化を踏まえたGraphQL前提の設計、認証とアクセストークン、最小スコープ、APIバージョン固定、GraphQL ID、Query/Mutationの業務分解、ページネーション、rate limit/query cost、Bulk Operations、冪等性、再試行、userErrors保存、運用ログ、そしてAPIを使わない判断まで含めて、はじめて安全な実装計画になります。

Bitlightでは、Shopify Admin APIを単なる接続部品として扱わず、EC運用に壊れず組み込むための設計資料から作ります。商品、在庫、注文、顧客、メタフィールドのどこをAPIで扱い、どこを管理画面・Flow・Liquid・既存アプリに残すかを整理したうえで、実装、ログ、再実行、保守まで含めた連携として設計します。