Shopify REST APIは今どう使うべきか｜GraphQL移行と業務連携設計

「shopify rest api」で調べる人は、REST Admin APIのエンドポイント一覧だけを知りたいわけではありません。すでに動いている受注連携、商品更新、顧客同期、在庫更新、ERPやkintoneへの連携があり、RESTがlegacyになった影響を確認したい。GraphQL Admin APIへ移すべきだと分かっていても、どこから着手すれば業務を止めずに済むか判断したい。そういう状況が多いはずです。

Shopify公式のREST Admin API referenceでは、REST Admin APIは2024年10月1日時点でlegacy APIであり、2025年4月1日以降の新規public appはGraphQL Admin APIだけで構築する必要があると説明されています。また、公式のRESTからGraphQLへの移行ガイドでは、すべてのappとintegrationはGraphQL Admin APIで構築すべき、という前提が示されています。実装時は必ず公式の現行記載を再確認してください。

この記事では、REST Admin APIの入門ではなく、既存Shopify連携を監査し、RESTを短期維持する範囲、GraphQLへ優先移行する範囲、APIをやめてCSVや手動運用に戻す範囲を分けるための設計を整理します。GraphQL実装そのものはShopify Admin API実装計画やShopify GraphQL設計ガイドで扱っています。

Shopify REST APIの今の実務テーマは、新規にRESTを学ぶことではなく、既存REST連携を棚卸しして、止めずにGraphQLへ移す順番を決めることです。

先に結論：RESTは新規採用ではなく監査対象にする

REST Admin APIがlegacyになったからといって、既存連携を週末に全部GraphQLへ置き換える、という判断は危険です。注文、商品、顧客、在庫、会計、ERP、kintone、WMSが絡む連携では、API方式だけでなく、データ正本、再実行、重複防止、監査ログまで一緒に変わります。

まず作るべきものは、次の台帳です。

台帳	決めること	作らないと起きること
REST利用箇所台帳	どのエンドポイントを、どの頻度で、何のために呼んでいるか	影響範囲が分からず、移行対象を過小評価する
データ正本表	商品、在庫、注文、顧客をShopifyと外部のどちらで正式管理するか	GraphQLへ移しても、上書き競合や二重更新が残る
維持/移行判断表	短期維持、優先移行、停止/CSV化を分ける	重要度の低い連携から着手し、受注や在庫が後回しになる
version/スコープ台帳	API version、deprecation、read/write scopes、トークン発行元	期限切れ、権限不足、過剰権限に気づけない
ID対応表	REST simple ID、GraphQL global ID、外部ID、SKU、注文番号	再実行時に別レコードを更新する
監査ログ設計	成功、失敗、再試行、手動補正、差分検証をどう残すか	移行後に「何がズレたか」を追えない

RESTからGraphQLへの移行は、APIクライアントの差し替えではありません。EC運用のどの台帳を、どのAPIで、どこまで自動更新するかを見直す作業です。

公式情報を運用ルールへ落とす

Shopify仕様は変わるため、記事や古いサンプルではなく公式Docsを起点にします。特に次のページは、移行監査の根拠として確認します。

公式ページ	確認すること	運用ルールへの落とし込み
REST Admin API reference	RESTのlegacy扱い、認証、エンドポイント、rate limit	新規実装でRESTを主軸にしない
REST to GraphQL migration	RESTからGraphQLへ移行する背景	既存連携もGraphQL前提で将来設計する
REST Admin API pagination	RESTのcursor-based pagination、Linkヘッダー、page_info、limit	REST短期維持中の全件取得を監視する
API versioning	四半期version、stable、fall forward、deprecation	version更新日と確認担当を台帳化する
Shopify API limits	入力配列上限、pagination上限、GraphQL query cost、rate limit	RESTとGraphQLで制限の見方を分ける
Simple IDs in REST Admin API	REST simple ID、GraphQL global ID、admin_graphql_api_id、legacyResourceId	移行時のID対応表を作る
Idempotent requests in REST Admin API	冪等キーと安全な再試行	決済、注文、外部登録の重複防止を見直す

公式ページを読んだだけでは実務は変わりません。自社の注文、商品、顧客、在庫、外部連携のどこに影響するかまで落とします。

REST利用箇所を業務単位で棚卸しする

RESTの移行は、エンドポイント一覧から始めると抜け漏れます。業務で何をしているかから逆に見ます。

業務領域	RESTでよくある処理	監査で見ること	移行時の注意
注文	注文一覧取得、詳細取得、タグ更新、連携済みフラグ更新	支払/出荷状態、返金、過去注文取得、外部送信済み判定	WMS、会計、CSへの二重送信を防ぐ
商品	商品一覧、商品更新、画像、タグ、メタフィールド	販売文言を誰が編集するか、外部PIMやERPの商品正本	外部同期で商品ページを上書きしない
顧客	顧客一覧、顧客タグ、購入履歴、CRM ID	メール変更、重複顧客、配信同意、保護された顧客データ	顧客IDとCRM/kintone IDの対応を残す
在庫	InventoryItem、Location、InventoryLevelの取得/更新	Shopify在庫とWMS在庫のどちらが正本か	差分加算か期待値セットかを決める
ERP/kintone	受注台帳、顧客台帳、在庫台帳、例外処理レコード	外部record ID、再実行状態、手動補正メモ	Shopify IDだけでなく外部IDもログに残す

棚卸しでは、ソースコードだけでなく、GAS、iPaaS、定期バッチ、社内ツール、手動CSV、外部ベンダー連携も対象にします。Shopify管理画面で動いているアプリが、裏側でREST Admin APIを使っていることもあります。社内コードだけを見て「RESTは残っていない」と判断しない方が安全です。

短期維持・GraphQL移行・停止/CSV化を分ける

すべてをGraphQLへ移す方向は正しいとしても、着手順は同じではありません。移行優先度はAPIの古さではなく、業務リスクで決めます。

REST利用箇所	判断	理由	次の作業
注文作成後にWMSへ送る受注連携	GraphQLへ優先移行	売上、出荷、CSに直結し、二重送信や欠損の影響が大きい	Order ID、支払状態、出荷状態、外部WMS IDを対応表化する
WMSからShopifyへ戻す在庫更新	GraphQLへ優先移行	在庫ズレは販売機会損失と売り越しにつながる	InventoryItem、Location、SKU、更新方式を整理する
商品説明や画像の一括更新	条件付きで移行	EC担当が管理画面で編集する項目と競合しやすい	外部正本項目だけをGraphQL mutation対象にする
月1回の商品属性補正	短期はREST維持またはCSV	頻度が低く、手動確認を挟めるなら急がない	期限を決め、CSV差分検証を残す
顧客タグの軽い付与	Flow/既存アプリ/GraphQLを比較	処理が単純ならカスタム移行しない方が保守しやすい	付与条件、削除条件、CRMとの重複を確認する
古い分析用の全注文取得	停止またはBulk/BIへ移行	本番運用に不要ならAPI維持コストが高い	利用者、利用頻度、代替レポートを確認する

RESTを残すかどうかは、技術的に呼べるかではなく、その連携が止まったときに注文・在庫・会計・顧客対応へどれだけ影響するかで決めます。

pagination・rate limits・versioningを運用表にする

REST短期維持中でも、運用ルールは見直します。特に一覧取得、夜間バッチ、全件同期は、paginationとrate limitで詰まりやすい領域です。

観点	REST短期維持中に見ること	GraphQL移行時に見ること
pagination	Linkヘッダーのpage_infoを保存し、limitは最大250を前提に件数と応答サイズを見る	first、after、pageInfo.endCursorを使い、必要fieldsだけ取る
途中再開	page_infoを加工せず、検索条件と一緒にバッチログへ残す	cursor、operation名、variables、最後に成功したIDを残す
rate limit	X-Shopify-Shop-Api-Call-Limit、429、Retry-Afterをログ化し、待機して再試行する	extensions.cost、requested/actual cost、throttleStatusを見る
API version	URLのversion、X-Shopify-API-Version、fall forwardを確認する	四半期ごとのstable version更新とschema変更を確認する
deprecation	API health、Developer changelog、deprecated resourceを確認する	deprecated fields/typesの置き換えを移行タスクに入れる
大量取得	RESTで全件をなめる処理を疑う	通常QueryかBulk Operationsかを分ける

RESTのpaginationでは、page_info付きURLに追加できるパラメータが制限されます。最初の検索条件、返ってきたLinkヘッダー、次回URLを残さないと、途中停止後に正しく再開できません。GraphQLへ移行すると制限の見方はquery costへ変わるため、RESTの呼び出し回数ベースの感覚をそのまま持ち込まない方がよいです。

access scopesとトークンを最小権限で見直す

Shopify公式のAPI access scopesでは、アプリは必要なstore dataへのアクセスを認可される必要があります。RESTからGraphQLへ移行するときは、コードだけでなく、トークンとスコープも棚卸しします。

連携	スコープ候補	監査ポイント
商品読み取り/更新	read_products、write_products	商品説明、画像、タグ、メタフィールドのどこまで更新するかを分ける
注文取得/更新	read_orders、write_orders、必要に応じてread_all_orders	60日超の注文や保護された顧客データの要件を確認する
在庫	read_inventory、write_inventory、read_locations	LocationとInventoryItemの対応がないまま更新しない
顧客	read_customers、write_customers	配信同意、個人情報、CRM正本を軽く扱わない
メタオブジェクト	read_metaobjects、write_metaobjects	商品/注文メタフィールドで足りるなら広げない

古い連携では、誰が発行したトークンか、どの環境変数に入っているか、退職者や外部ベンダーの権限が残っていないかが曖昧になりがちです。移行前に、発行元、保管場所、ローテーション、再認可、失効時の影響範囲を台帳化します。

REST simple IDとGraphQL global IDの対応表を作る

REST Admin APIでは、商品や注文などに数値のsimple IDが出ます。一方、GraphQL Admin APIではgid://shopify/Product/123456789のようなglobal IDを使います。公式のSimple IDs in the REST Admin APIでは、多くのREST resourceにadmin_graphql_api_idがあり、多くのGraphQL objectにはlegacyResourceIdがあると説明されています。

対象	RESTで残っているID	GraphQLで使うID	外部側で残すキー
Product	product.id	Product global ID、legacyResourceId	外部商品ID、handle、商品コード
ProductVariant	variant.id	ProductVariant global ID	SKU、JAN、バリエーションコード
Order	order.id	Order global ID	注文番号、WMS注文ID、会計伝票ID
Customer	customer.id	Customer global ID	CRM/kintone顧客ID、メール、電話
InventoryItem/Location	inventory_item_id、location_id	InventoryItem/Location global ID	SKU、倉庫コード
Metafield	metafield.id	Metafield global ID、owner ID	namespace、key、type、外部項目名

SKUやメールは人に分かりやすいキーですが、変更されます。RESTの数値IDだけを外部DBに保存している場合は、GraphQL移行前にadmin_graphql_api_idまたはlegacyResourceIdで橋渡しできるか確認します。

冪等性・再試行・重複防止を先に設計する

RESTからGraphQLへ移すときに最も危険なのは、正常系だけを置き換えることです。注文送信、在庫更新、顧客同期、会計連携は、失敗時と再実行時の仕様が本体です。

失敗パターン	起きること	設計方針
ネットワーク切断	Shopify側で成功したのか、外部側で成功したのか分からない	idempotency key、外部連携ID、処理状態を残してから再試行する
429/rate limit	バッチが途中で止まる	Retry-Afterやcost残量を見て待機し、同じ処理単位で再開する
validation error	入力値、状態、権限、在庫状態が不正	自動再試行せず、項目単位のエラーとして保留する
部分成功	100件中一部だけ失敗する	成功分と失敗分を分け、失敗分だけ再実行する
二重Webhook/二重バッチ	同じ注文をWMSやkintoneへ二重登録する	Shopify ID + 外部システム + 処理種別で一意キーを作る
在庫再実行	差分加算をもう一度かけて在庫がズレる	期待在庫数へのセットか、差分調整かを明示する

RESTのIdempotent requestsは、接続問題でレスポンスを受け取れなかった場合にも重複や競合を避けて安全に再試行する考え方を示しています。GraphQL移行後も、Shopify側の仕組みだけに頼らず、連携DB側で冪等キー、外部ID、処理状態を持ちます。

idempotency_key = shop_domain + resource_type + shopify_id + external_system + action

このキーで、同じ注文をWMSへ二重送信しない、同じkintoneレコードを二重作成しない、同じ会計伝票を二重登録しない、という制約を作ります。

同期失敗と監査ログを運用者が読める形にする

移行監査では、ログを開発者向けのデバッグ情報としてではなく、運用者が復旧できる台帳として設計します。

ログ項目	残す内容	運用での使い道
shop domain/API version	対象ストア、REST/GraphQL version、X-Shopify-API-Version	複数ストアやversion差分を切り分ける
operation/endpoint	REST endpoint、GraphQL operation name	どの処理が失敗したか分かる
Shopify ID/外部ID	simple ID、global ID、WMS ID、kintone record ID、会計伝票ID	再実行時に新規作成か更新か判断する
pagination/rate	page_info、cursor、429、Retry-After、GraphQL cost	途中再開、待機、分割、Bulk化を判断する
エラー/再試行	HTTP status、userErrors、retry count、手動補正メモ	自動再試行か人手対応か分ける

EC担当やCS担当が見るのは、HTTPステータスではありません。「注文#1234がWMSへ送れていない」「SKU ABCの在庫更新が失敗している」「kintone record 456は作成済みだがERP送信だけ失敗している」と分かるログが必要です。外部連携全体の正本や同期イベントは、Shopify API連携の設計方法と合わせて整理するとよいです。

ERP/kintone連携では正本と差分監査を分ける

ShopifyとERP/kintoneをつなぐ場合、kintoneを全データの正本にするのか、例外処理の画面にするのかで設計が変わります。ERPも、商品マスタ、受注、在庫、売上、請求のどれを正本にするかを分けます。

連携先	正本にしやすいもの	Shopifyから渡すもの	監査する差分
ERP	商品コード、原価、仕入、在庫、販売管理	注文、顧客、SKU、数量、金額、返金候補	商品コード未登録、税区分不一致、売上計上漏れ
WMS	倉庫在庫、引当、出荷実績、追跡番号	出荷対象注文、配送先、明細、温度帯、同梱条件	出荷指示漏れ、追跡番号戻し漏れ、在庫差異
kintone	例外処理、対応状況、手動補正、顧客対応	注文台帳、顧客台帳、エラー通知、再実行対象	kintone作成済み/ERP未送信などの段階差分
会計	仕訳、入金消込、月次締め	注文、返金、手数料、送料、税区分候補	Shopify売上と会計計上の差分

kintoneは、Shopifyの全レコードを複製する場所にすると重くなります。受注処理や顧客対応で人が見る台帳、連携失敗の保留リスト、再実行ボタン、手動補正メモの場所として使うと価値が出ます。Webhookを起点にする場合は、Shopify Webhookの実装設計で扱ったように、受信、キュー、重複排除、再同期ジョブまで含めて考えます。

RESTからGraphQLへ移行する監査チェックリスト

最後に、既存REST連携を監査するときのチェックリストを置きます。

チェック項目	確認する内容
REST利用箇所	コード、GAS、iPaaS、外部ベンダー、定期バッチ、手動CSVを含めて洗い出したか
業務重要度	注文、在庫、会計、顧客対応に直結する連携を優先できているか
短期維持	RESTを残す処理に期限、担当、監視、version確認を置いたか
GraphQL移行	Query/Mutation、fields、pagination、query cost、Bulk Operationsの方針を書いたか
停止/CSV化	低頻度でAPI不要な処理を止める、またはCSV確認に戻せるか
API version/deprecation	REST/GraphQLのversion、更新日、deprecation確認日を台帳化したか
access scopes/トークン	read/write scopes、protected customer data、再認可、ローテーションを確認したか
ID対応	REST simple ID、GraphQL global ID、legacyResourceId、外部IDの対応表を作ったか
pagination/rate limit	RESTのLinkヘッダー、page_info、429、Retry-After、GraphQL costをログ化したか
冪等性/再試行	注文、在庫、kintone、ERP、会計で二重登録を防ぐキーを作ったか
監査ログ	Shopify ID、外部ID、エラー、retry count、手動補正メモを運用者が見られるか
差分検証	移行前後で注文件数、在庫数、商品更新、顧客タグ、外部レコード数を突合したか
ロールバック	GraphQL移行後に問題が出たとき、REST短期維持や手動CSVに戻す判断基準があるか

この表を埋める前に移行実装へ入ると、RESTのコードは減っても、受注漏れ、在庫ズレ、顧客重複、会計差分、再実行不能は残ります。移行の成否は、GraphQLへ置き換えた行数ではなく、移行後もEC運用が説明できる状態になっているかで見ます。

まとめ

Shopify REST APIは、これから新規採用する主軸ではありません。REST Admin APIはlegacy APIであり、新規public appはGraphQL Admin API前提です。既存のappやintegrationも、将来設計としてはGraphQL Admin APIへ寄せていくべきです。

ただし、既存連携では「全部すぐGraphQLへ移行」が正解とは限りません。注文、商品、顧客、在庫、ERP/kintone、会計、WMSごとに、REST短期維持、GraphQL優先移行、停止/CSV化を分ける必要があります。pagination、API versioning、deprecation、rate limits、429/Retry-After、access scopes、simple IDとGraphQL global ID、legacyResourceId、冪等性、再試行、重複防止、監査ログまで含めて見直して、はじめて実務で使える移行になります。

Bitlightでは、Shopify REST Admin APIで作られた既存連携を、単なるAPI置き換えとして扱いません。REST利用箇所の棚卸し、GraphQL移行判断、ERP/kintone連携の正本整理、ID対応表、再試行、監査ログ、差分検証まで含めて、EC運用を止めずに移行できる設計資料と実装に落とし込みます。