Shopify Order APIで受注データ連携を設計する｜GraphQL・Webhook・会計同期の実務

Shopifyで受注数が増えると、注文データをERP、kintone、WMS、CRM、会計ソフトへ自動連携したくなります。検索すると、Order APIで注文を取得する実装例はすぐ見つかります。

ただし、本番運用で必要なのはAPI取得ではありません。注文作成時点と支払確定時点の扱い、返金・キャンセル・返品の戻し方、Shopify IDと外部伝票番号の対応、Webhookの重複・順序ずれ・欠損検知まで決めないと、連携はすぐ手作業の補正だらけになります。

この記事では、汎用的なAdmin API解説ではなく、受注データを外部システムへ同期するための設計に絞ります。公式のorders query、Order object、REST Order resource、REST Admin API reference、About webhooks、Verify webhook deliveries、Admin API rate limitsを前提に整理します。

Shopify Order API連携の目的は、注文を取得することではありません。外部システム側で売上・出荷・返金・入金・会計を説明できる受注台帳を作ることです。

先に結論：Order API連携は注文取得ではなく照合できる受注台帳を作る設計

Shopify Order API連携は、次の順番で設計します。

設計テーマ	先に決めること	未設計時の問題
正本	Shopify、ERP、会計、WMSのどれを各項目の正本にするか	出荷済みなのに外部側で未出荷に戻る
受注台帳	注文、明細、税、送料、割引、返金、入金の粒度	会計やCSが差異を説明できない
同期トリガー	Webhook、差分ポーリング、夜間照合の役割	Webhook欠損や順序ずれに気づけない
API方針	GraphQL Admin APIを主軸にし、REST依存を棚卸しする	古いREST前提で新規アプリ設計を進める
復旧	再実行、手動補正、再照合	エラーが手作業で埋もれる

特に重要なのは、REST 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 Admin APIを中心にします。Admin API全体の設計はShopify Admin API実装計画も参照してください。

まずOrder APIで何が取得できるか

GraphQL Admin APIのorders queryは、注文ステータス、顧客、明細などを含む注文リストを返し、pagination、sorting、filteringに対応しています。updated_at、financial_status、fulfillment_status、return_status、risk_level、skuなどは、差分取得や例外抽出に使えます。

Order objectは、顧客情報、商品詳細、決済処理、フルフィルメントをつなぐ中心的なオブジェクトです。実装では、すべてのフィールドを取るのではなく、同期先ごとに必要な項目を選びます。

取得領域	代表項目	利用先	注意
注文識別	id、name、注文番号、作成日時、更新日時	ERP、kintone、会計、CS	nameだけを外部キーにしない
顧客	customer、email、phone、billing/shipping address	CRM、配送、CS	必要最小限にする
明細	line items、SKU、variant、数量、単価	ERP、WMS、分析	SKU変更、セット品、0円明細を想定する
金額	subtotal、total、tax、shipping、discount、currency	会計、BI、入金照合	注文時金額と返金後金額を混ぜない
支払・出荷	financial status、fulfillment status、配送方法	会計、出荷判定、CS	支払済みでも出荷保留にすべき注文がある
返品・返金	refunds、return status、refund discrepancy	会計、CS、在庫戻し	返金、返品、キャンセルを同じ取消処理にしない

REST Order resourceにも注文ID、顧客、住所、タグ、メタフィールドなどはあります。ただし、これから作る項目設計はGraphQL Admin APIのOrder objectを基準にします。

RESTとGraphQL Admin APIの使い分け

Order API連携でよくある失敗は、古いRESTサンプルをそのまま新規設計に採用することです。RESTは分かりやすい一方、今後のShopifyアプリ開発の中心ではありません。

観点	GraphQL Admin API	REST Admin API
Shopifyの位置づけ	新規設計の主軸。2025年4月1日以降の新規public appはGraphQL Admin API中心	2024年10月1日からlegacy API
注文取得	orders queryで必要フィールドを選び、filter、pagination、sortを使う	Order resourceで取得する既存実装が多い
項目設計	必要フィールドを明示するため、同期先ごとの過不足を管理しやすい	既存JSONに引きずられ、不要項目まで保存しやすい
レート制限	calculated query costを見て、クエリの重さを管理する	REST側の制限を考慮する必要がある
移行方針	新規のERP・kintone・会計連携は原則こちら	既存連携の棚卸し、短期保守、移行調査に限定する

GraphQL Admin APIでは、必要なフィールドを絞れる反面、クエリが業務設計そのものになります。会計へ不要な配送先住所を送らない、といった切り分けが必要です。API全体の選び方はShopify API連携の設計方法も参照してください。

Order objectで見る主要項目：ステータス・明細・税・送料・割引

受注連携では、注文ヘッダーだけを保存しても足りません。会計、出荷、CS、売上分析で見る粒度が違うため、最低でも「注文」「明細」「金額内訳」「状態履歴」を分けて持ちます。

区分	保存する項目例	使い方	注意点
注文ヘッダー	Shopify Order ID、注文名、作成日時、チャネル、通貨	受注台帳、問い合わせ検索	顧客向け番号とAPI IDを混同しない
ステータス	financial status、fulfillment status、cancelled、risk level	出荷可否、請求可否	表示用ステータスを会計処理の唯一条件にしない
明細	line item ID、SKU、商品名、variant、数量、単価	出荷指示、売上明細、在庫引当	商品名変更後も注文時点の表示名を残す
税・送料	税額、税率、shipping line、配送方法、送料税	会計、税区分、配送分析	税区分、丸め、送料無料キャンペーンを分ける
割引	discount code、discount allocations、キャンペーン	販促分析、会計補助科目	注文全体割引と明細別割引を分ける
メタ情報	tags、note、custom attributes、metafields	CSフラグ、外部連携制御	自由入力を会計ロジックの主キーにしない

会計連携では、注文単位の合計だけでなく、明細単位の売上、税、割引、送料、返金を分けます。kintoneなら、注文、注文明細、同期ログを別アプリにすると扱いやすくなります。

返金・キャンセル・返品を会計に反映する設計

Shopifyの受注連携で一番崩れやすいのは、注文作成後の変化です。返金、キャンセル、返品は似ていますが、会計・在庫・CSでは意味が違います。

イベント	Shopify側で見るもの	会計反映	在庫・出荷	注意
キャンセル	cancelled状態、日時、理由	未計上なら伝票作成しない。計上後なら取消またはマイナス伝票	未出荷なら出荷停止	支払済み注文は返金とセットで確認する
全額返金	refunds、financial status、返金金額	売上取消、返金、手数料調整を記録	返品ありなら在庫戻し、返品なしなら戻さない	返金日と注文日が月をまたぐ場合に注意
部分返金	refund line items、送料返金、調整額	明細別マイナス、送料返金、値引き補正	対象SKUだけ戻すか決める	注文合計だけ見ると差異が出る
返品	return status、返品受付、検品結果	返品確定後に売上戻しまたは引当解除	検品後に良品戻し、不良品廃棄を分ける	返品リクエスト時点で会計確定しない
チャージバック	chargeback status、決済側情報	損失、手数料、未収、戻入を会計方針に合わせる	出荷済みなら在庫は戻らない可能性が高い	Shopify注文だけでなく決済側も確認する

返金・返品の履歴は注文とは別テーブルで残します。決済手数料や入金差異まで含めた月次確認は、Shopifyの決済手数料と入金照合の設計で詳しく扱っています。

Webhookと差分ポーリングの使い分け

Webhookは近リアルタイム同期に有効です。注文作成、注文更新、返金、キャンセルなどを早く検知できます。ただし、Webhookは通知であり完全な台帳ではありません。Shopify公式のVerify webhook deliveriesでは、HMAC検証、重複を無視する設計、キューを使った5秒以内の応答、取りこぼしに備えたreconciliation jobが説明されています。

方式	向いている用途	必須設計	不向き
Webhook	注文作成、更新、キャンセル、返金の検知	HMAC検証、重複検知、即時ACK、キュー、処理ログ	過去全件取得、月次照合
差分ポーリング	updated_atなどで一定期間の注文を再取得	cursor、最終同期時刻、重複排除、遅延更新の余白	秒単位のリアルタイム反映
夜間照合ジョブ	Shopifyと外部DBの件数・金額・状態差異を検出	注文件数、売上合計、返金合計、未処理一覧	即時の出荷指示
手動再同期	特定注文の再取得、エラー復旧	管理画面、権限、監査ログ、冪等性	日常処理の代替

Webhookを入れても、差分ポーリングと照合ジョブは不要になりません。むしろWebhookを本番運用するなら、欠損・重複・順序ずれを検知する再取得経路が必須です。

Webhook設計の詳細は、Shopify Webhookの実装設計と合わせて確認してください。受信ログ、キュー、ワーカー、同期台帳、DLQ、再同期を分けるのが基本です。

ページネーション・レート制限・冪等性の実装注意点

GraphQL Admin APIのorders queryでは、first、after、sortKey、queryなどを使ってページネーションや絞り込みを行います。差分同期では、updated_atで取得範囲を切り、cursorでページを進め、処理済みのShopify Order IDと更新時刻を保存します。

実装項目	方針	失敗例
ページネーション	cursorを保存し、ページ単位で処理結果を記録する	途中失敗で同じページを二重投入する
差分範囲	最終同期時刻に数分の余白を持たせ、重複はIDで除外する	遅延更新やタイムゾーン差で注文を取りこぼす
レート制限	GraphQLのcalculated query cost、bucket、restore rateを見る	重いクエリを連発して待機が増える
フィールド選択	同期先に必要な項目だけ取る	PIIや不要明細でcostとリスクが増える
冪等性	Shopify Order ID、line item ID、webhook ID、外部伝票番号をキーにする	同じWebhook再送でkintoneや会計に二重登録される
再実行	処理ステップごとに成功・失敗・外部IDを残す	どこまで終わったか分からず手作業修正になる

Shopify公式のAdmin API rate limitsでは、GraphQL Admin APIはリクエスト数だけでなくcalculated query costで制限されると説明されています。注文、明細、返金、顧客、住所、メタフィールドを一度に深く取りすぎない設計が必要です。

ERP・kintone・会計ソフト同期のデータモデル例

外部同期では、ShopifyのOrder objectをそのまま1レコードに詰め込む設計は避けます。あとから照合するには、注文ヘッダー、明細、返金、同期ログ、外部ID対応を分けます。

データモデル	主キー・外部キー	主な項目	同期先	注意点
受注ヘッダー	Shopify Order ID、注文名、外部受注ID	顧客、チャネル、日時、状態、合計	ERP、kintone、CRM	顧客PIIの保持範囲を決める
受注明細	line item ID、SKU、受注ID	商品名、variant、数量、単価、税、割引	ERP、WMS、会計	SKU変更と注文時点の商品名を分ける
金額内訳	受注ID、内訳区分	商品小計、送料、税、割引、調整額	会計、BI	税区分、丸め、通貨を保持する
返金・返品	refund ID、return ID、受注ID	返金額、対象明細、送料返金、返品状態	会計、CS、WMS	返品受付と返金確定を分ける
同期対応表	Shopify ID、外部システムID	ERP伝票番号、kintoneレコードID、会計仕訳ID	全連携	再実行と照合の中心にする
同期ログ	event ID、処理ID、受注ID	topic、hash、結果、エラー、再実行回数	運用監視	PIIを過剰保存しない

ERPでは受注登録、出荷指示、売上計上、返品伝票が別APIになっていることがあります。Shopifyの1注文をどのERP伝票に分解するか、会計ではどの時点で仕訳を作るかを先に決めます。

PII・権限・監査ログのセキュリティ設計

注文データには、氏名、メール、電話、住所、購入商品、決済関連情報が含まれます。便利だから全項目を保存する、という設計は避けます。

観点	設計方針	実装例
権限スコープ	必要なscopeだけ要求する	読み取り中心ならread_ordersを基本にする
過去注文	60日を超える注文アクセスが必要か確認する	過去全件分析が必要な場合だけ追加scopeの正当性を整理する
PII保存	同期先ごとに必要最小限の個人情報だけ保存する	会計には氏名不要、WMSには配送先必要、BIには匿名化IDを使う
ログ	payload全文保存を避け、hash、ID、状態、エラーを中心にする	raw payload保管が必要な場合は期限と暗号化を決める
監査	誰が再同期・手動補正したか残す	管理画面操作ログ、再実行理由、変更前後の外部IDを記録

注文アクセスにはread_ordersなどのscopeが関係し、古い注文へのアクセスには追加の権限が必要になる場合があります。ERP、kintone、会計、BI、ログ基盤ごとに、保存してよい項目を明示してください。

照合・失敗時リカバリ・再実行フロー

受注連携は、失敗しない設計ではなく、失敗しても戻せる設計にします。Shopify、外部DB、kintone、ERP、会計、決済、銀行入金のどこかで必ず差異は出ます。

チェック項目	確認内容	頻度	復旧アクション
注文件数	Shopifyの注文数と外部受注台帳の件数が一致するか	日次	欠損注文を差分ポーリングで再取得
金額合計	商品小計、税、送料、割引、返金後合計が一致するか	日次・月次	金額内訳を再計算し、会計投入前に保留
Webhook処理	受信、キュー投入、処理済み、失敗の件数	常時	DLQから再実行
外部ID対応	Shopify IDとERP/kintone/会計IDが紐づいているか	日次	対応表を補正し、二重登録を防ぐ
返金・返品	返金済み注文が会計・在庫に反映されているか	日次・月次	返金伝票、返品伝票、在庫戻しを再作成
入金照合	決済レポート、会計、銀行入金の差異	月次	手数料、返金、チャージバック、入金日差を確認

再実行フローは、WebhookをHMAC検証して受信ログに保存し、Shopify Order IDで最新状態をGraphQL Admin APIから取得し、外部用の受注ヘッダー、明細、返金に変換し、ERP、kintone、会計へ冪等に登録する流れにします。

同じ注文を再実行しても、ERP、kintone、会計に二重登録されないことが最低条件です。

まとめ

Shopify Order APIで受注データを取得すること自体は難しくありません。GraphQL Admin APIのorders queryとOrder objectを使えば、注文、顧客、明細、金額、支払状態、出荷状態、返金、返品に関するデータを取得できます。既存REST連携の保守でOrder resourceを読む場面もあります。

しかし、2024年10月1日以降REST Admin APIはlegacy APIであり、2025年4月1日以降の新規public appはGraphQL Admin API中心という公式前提があります。これから設計する受注連携では、RESTのサンプルコードを主軸にせず、GraphQL Admin API、Webhook、差分ポーリング、照合ジョブ、同期ログを組み合わせるべきです。

Webhookは近リアルタイム同期に有効ですが、HMAC検証、重複検知、順序ずれ対策、キュー、差分ポーリング、照合ジョブが必要です。返金、キャンセル、返品、入金差異まで扱える台帳を作らなければ、外部側で数字が崩れます。

Shopifyの受注連携は、API実装ではなく業務システム設計です。どの項目を持つか、どの状態で会計へ送るか、どのエラーを誰が直すか、どの数字を月次で照合するか。ここまで決めてからコードを書く方が、後から現場を止めずに済みます。