2026.10.26 開発

Shopify APIとは：Admin・Storefront・Webhookの使い分けとレート制限をコードで解説

Q: Shopify APIのバージョンはどれを指定すればよいですか？

新規開発では、その時点の最新安定版を指定します。2026年10月時点では 2026-10 で、利用できる期限は2027年10月16日です。バージョンは3か月ごとに出て最低12か月サポートされるため、年に1回は新しい版へ上げ、応答ヘッダー X-Shopify-API-Version で実際に使われた版を確認する運用にします。

Shopify APIとは：Admin・Storefront・Webhookの使い分けとレート制限をコードで解説

Shopify APIとは、ストアの商品・注文・顧客などのデータを外部のシステムやアプリから読み書きするための、Shopify公式のAPI群の総称です。1本のAPIではなく、管理データを扱うGraphQL Admin API、購入者向けの画面を作るStorefront API、変更を通知するWebhookなど、用途ごとに別のAPIが用意されています。本記事では、それぞれが担う範囲と用途別の選び方、curlとNode.jsでの呼び出し例、プラン別のレート制限とクエリコストの測り方、Webhookの署名検証と再試行の仕様を、2026年10月時点の公式ドキュメントに沿って解説します。

まとめ：Shopify APIは用途で選び、上限はクエリコストで見積もる

基幹システムや在庫管理との連携のように、管理画面のデータを読み書きするならGraphQL Admin APIを使います。REST Admin APIは2024年10月1日にレガシーになっており、新規の開発でRESTを選ぶ理由はほぼありません。自前の画面で商品を見せてカートを作るヘッドレス構成ならStorefront API、注文や在庫の変化をすぐ知りたいならWebhookです。

レート制限は「何回呼んだか」ではなく「何ポイント使ったか」で数えます。標準プランは毎秒100ポイント、1回のクエリは1,000ポイントまでで、実際の消費量の確認先は、応答のextensions.costです。数万件を同期するなら、通常のクエリを回し続けずにバルクオペレーションへ切り替えます。

Webhookは届かないことがある前提で、定期的な突き合わせと対で作ります。

Shopify APIの種類とAdmin・Storefront・Webhookの役割の違い

ShopifyのAPI一覧ページには、GraphQL Admin API、Storefront API、Webhook、Shopify Functions、Customer Account APIなど30を超えるAPIとツールが並んでいます。外部システムとの連携で実際に選ぶ対象は、その一部です。

主要なShopify APIの用途・呼び出す場所・レート制限の比較表

連携やヘッドレス構築で検討に上がるAPIを、誰の権限で何を扱うかで並べます。

API	主な用途	呼び出す場所	レート制限の数え方
GraphQL Admin API	商品・注文・在庫・顧客の読み書き	サーバー	クエリコスト（ポイント）
Storefront API	独自画面での商品表示・カート	ブラウザ・アプリ・サーバー	購入者の通信に固定上限なし
Webhook	ストアの変更を外部へ通知	Shopifyから自社サーバーへ	対象外（応答は5秒以内）
Customer Account API	会員の注文履歴・プロフィール	ブラウザ・アプリ	クエリコスト＋毎分3,000回
Ajax API	テーマ内のカート操作	Shopifyホストのテーマ	固定上限なし

実務でまず押さえるのは上の3つです。Admin APIは管理画面と同じ範囲のデータに触れるため、トークンを必ずサーバー側に置きます。Storefront APIは購入者に見せてよい情報だけを扱う設計で、公開用のトークンならブラウザに埋め込んでも構いません。

REST Admin APIは2024年10月にレガシー化、新規はGraphQLで書く

REST Admin APIのリファレンスの冒頭には、2024年10月1日からレガシーのAPIであり、2025年4月1日以降の新規公開アプリはGraphQL Admin APIだけで作らなければならないと書かれています。RESTの上限は、1アプリ・1ストアあたり40リクエストの枠が毎秒2リクエストずつ回復する方式で、Shopify Plusでは10倍です。

ネット上の連携サンプルには/admin/api/2021-10/products.jsonのような古いRESTの呼び方が多く残っているので、写す前にGraphQLへ置き換えます。2つの方式の一般的な違いはREST APIとGraphQLの違いと使い分けを解説した記事で扱っています。

Ajax APIとCustomer Account APIはテーマ内と会員機能で使う

Ajax APIの解説によると、Ajax APIはテーマ開発用の軽量なREST APIで、トークンは不要です。ただしShopifyがホストするテーマでしか使えず、ヘッドレスの独自画面からは呼べません。テーマのカートにボタン1つ足す程度ならAjax API、独自のフロントを作るならStorefront APIという線引きになります。

Customer Account APIのリファレンスでは、このAPIが認証するのはアプリではなく購入者で、OAuth 2.0の認可コードフロー（公開クライアントはPKCE）を使うと説明されています。会員ログインと注文履歴を独自画面で出すときに組み合わせます。

用途別にShopify APIを選ぶ手順と、組織や認証方式による分岐

使うAPIは「何をしたいか」で、トークンの取り方は「アプリをどこに作るか」で決まります。

基幹連携・ヘッドレス・変更通知の用途ごとに使うAPIを決める判断表

受託開発の相談で多い要件を、使うAPIの組み合わせに落とします。

やりたいこと	使うAPI	補足
受注を基幹・倉庫システムへ渡す	Webhook＋GraphQL Admin API	通知で気づき、Adminで詳細を取る
在庫数を外部から更新する	GraphQL Admin API	大量ならバルクオペレーション
独自デザインのサイトで販売する	Storefront API	会員機能はCustomer Account API
全商品を分析基盤へ毎日書き出す	GraphQL Admin API（バルク）	JSONLで一括取得
テーマのカートに機能を足す	Ajax API	トークン不要・テーマ内のみ

受注連携でWebhookだけに頼るのは避けます。後述のとおり配信は保証されないため、Admin APIで更新日時を条件に読み直す処理と対にする設計が必要です。ヘッドレス構成をCMSと組み合わせる場合の費用と構成はmicroCMSとShopifyを連携したECサイト構築の記事にまとめています。

アクセストークンの取得方法をアプリの置き場所と組織で決める手順

Admin APIのトークンは、アプリを作って初めて手に入ります。アプリ認証の解説では、管理画面に埋め込むアプリはトークン交換、管理画面の外で動くアプリは認可コードグラント、ストアと同じ組織に作るアプリはクライアント認証情報グラントを使います。

連携先がストアと同じ組織のアプリか、開発会社など別組織のアプリかを決める
同じ組織で画面を持たないバッチ連携なら、クライアント認証情報グラントで24時間有効のトークンを取る
別組織のアプリなら、認可コードグラントでストアの承認を得てトークンを保存する
スコープは読む範囲と書く範囲を分け、必要な分だけ付ける

2026年1月から管理画面でカスタムアプリを新規作成できなくなり、作成先はDev Dashboardに移りました。配布方法の選び方とトークン取得のcurl例はShopifyアプリ開発の始め方を解説した記事で扱っています。

GraphQL Admin APIで商品を取得するリクエストとページ送りの実装例

エンドポイントは1本で、URLにAPIバージョンを含めます。GraphQL Admin APIのリファレンスにあるスキーマを見ながら、必要なフィールドだけを指定します。

curlでGraphQL Admin APIの商品一覧を取得しコスト情報を確かめる

環境変数にストアのサブドメインとアクセストークンを入れて、更新日の新しい商品を5件取ります。

curl -s -X POST "https://${SHOP}.myshopify.com/admin/api/2026-10/graphql.json" \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: ${SHOPIFY_ACCESS_TOKEN}" \
  -d '{"query":"{ products(first: 5, sortKey: UPDATED_AT, reverse: true) { nodes { id title totalInventory updatedAt } } }"}'

応答のJSONにはdataとは別にextensions.costが付き、requestedQueryCost（実行前の見積もり）、actualQueryCost（実際の消費）、throttleStatus（残りポイントと回復速度）が入ります。応答ヘッダーのX-Shopify-API-Versionには実際に処理したバージョンが返るので、指定したバージョンと一致しているかを確かめます。

Node.jsでカーソルを使い全件を読む実装と25,000件の上限

一度に取れる件数には限りがあるため、pageInfo.endCursorを次のリクエストのafterに渡して読み進めます。次のコードはNode.js 18以降の標準のfetchで動き、残りポイントが少なくなったら回復を待ちます。

const ENDPOINT = `https://${process.env.SHOP}.myshopify.com/admin/api/2026-10/graphql.json`;
const QUERY = `query Products($cursor: String) {
  products(first: 100, after: $cursor) {
    nodes { id title updatedAt }
    pageInfo { hasNextPage endCursor }
  }
}`;

export async function fetchAllProducts() {
  const all = [];
  let cursor = null;
  do {
    const res = await fetch(ENDPOINT, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Shopify-Access-Token": process.env.SHOPIFY_ACCESS_TOKEN,
      },
      body: JSON.stringify({ query: QUERY, variables: { cursor } }),
    });
    const json = await res.json();
    if (json.errors) throw new Error(JSON.stringify(json.errors));

    const { nodes, pageInfo } = json.data.products;
    all.push(...nodes);

    // 残りが次の見積もりを下回りそうなら、回復を待ってから次へ進む
    const { currentlyAvailable, restoreRate } = json.extensions.cost.throttleStatus;
    const need = json.extensions.cost.requestedQueryCost;
    if (currentlyAvailable < need * 2) {
      await new Promise((r) => setTimeout(r, Math.ceil((need * 2 - currentlyAvailable) / restoreRate) * 1000));
    }
    cursor = pageInfo.hasNextPage ? pageInfo.endCursor : null;
  } while (cursor);
  return all;
}

ShopifyのAPI制限の一覧には、配列のページネーションは25,000件まで、入力の配列は250件までと書かれています。商品やバリエーションが数万件あるストアでは、このコードで全件は読み切れません。その場合は次章のバルクオペレーションを使います。

GraphQL Admin APIのレート制限をクエリコストで見積もり回避する方法

Shopifyは呼び出し回数ではなく、クエリの中身から消費ポイントを計算します。

プラン別に毎秒100〜2,000ポイントの回復量と1,000ポイントの単発上限

GraphQL Admin APIのレート制限の解説によると、ポイントの回復量はアプリとストアの組み合わせごとに、ストアのプランで決まります。

ストアのプラン	回復量（毎秒）
Standard	100ポイント
Advanced Shopify	200ポイント
Shopify Plus	1,000ポイント
Shopify for enterprise	2,000ポイント

プランに関係なく、1回のクエリは見積もりで1,000ポイントを超えられません。フィールドの既定コストはスカラーと列挙型が0、オブジェクトが1、ミューテーションが10で、コネクションはfirstやlastの値に応じて膨らみます。first: 250の中にさらにvariants(first: 100)を入れると、それだけで上限に届く計算です。

extensions.costとCost-Debugヘッダーで実コストを測る確認手順

同じ解説では、実行前に見積もりコスト分のポイントが残っているかを確かめ、実行後に見積もりと実際の差額を戻すと説明されています。返ってくる件数が少なければ、実際の消費は見積もりより小さくなります。

本番と同じクエリを開発ストアで1回実行し、requestedQueryCostとactualQueryCostを控える
リクエストヘッダーにShopify-GraphQL-Cost-Debug: 1を付けて再実行し、extensions.cost.fieldsでどのフィールドが重いかを見る
重いコネクションのfirstを減らすか、ネストを分けて別クエリにする
「1件あたりの実コスト×同期件数÷回復量」で、同期にかかる秒数を見積もる

上限に達したときの待ち時間について、制限一覧のページは1秒のバックオフを推奨しています。kintoneやSalesforceのように連携先にも上限がある場合は、同期の頻度を決める基準は、上限が厳しく処理の遅い側です。その具体例はShopifyとkintoneのAPI連携の記事とShopifyとSalesforceの連携方法の記事で扱っています。

数万件の同期はバルクオペレーションに切り替えJSONLで受け取る

バルクオペレーションの解説では、bulkOperationRunQueryにクエリを渡すと、Shopify側で非同期に全件を集め、結果をJSONL（1行1オブジェクト）のファイルで返します。バルクオペレーションには単発クエリの最大コストやレート制限がかかりません。

mutation {
  bulkOperationRunQuery(
    query: """
    {
      products {
        edges {
          node {
            id
            title
            variants { edges { node { sku inventoryQuantity } } }
          }
        }
      }
    }
    """
  ) {
    bulkOperation { id status }
    userErrors { field message }
  }
}

完了はbulk_operations/finishのWebhookか、返ってきたIDのポーリングで知ります。子の行には__parentIdが付きます。制約は、コネクションのネストが2階層まで・1クエリに5個まで、10日以内に完了すること、ダウンロードURLの有効期限が1週間であることです。APIバージョン2026-01以降は、1アプリが1ストアで同時に5件まで実行できます。

Storefront APIでヘッドレスの商品表示とカートを作るときの設定

Storefront APIは購入者向けの画面を作るためのAPIで、Admin APIとはエンドポイントもトークンも別です。Storefront APIのリファレンスの記載に沿って設定します。

公開トークンと非公開トークンの使い分けとBuyer-IPヘッダーの付与

トークンは2種類あります。ブラウザやモバイルアプリから呼ぶ公開トークンはX-Shopify-Storefront-Access-Tokenヘッダーで送り、購入者に見えても構わない前提です。Hydrogenのバックエンドなどサーバーから呼ぶ非公開トークンはShopify-Storefront-Private-Tokenヘッダーで送り、外に出しません。

サーバーから購入者の代わりに呼ぶときは、Shopify-Storefront-Buyer-IPヘッダーに購入者のIPアドレスを入れます。大文字小文字の区別があるヘッダーです。API制限の一覧では、購入者の通信とは別に、ボットやクローラー向けの制限があるとされています。サーバー経由の構成では、購入者ごとのIPを渡して両者を区別させます。

Storefront APIで商品を取得するfetchの実装例とトークン不要の範囲

ブラウザから公開トークンで商品6件と最安価格を取る例です。エンドポイントは/api/2026-10/graphql.jsonで、Admin APIの/admin/api/とは異なります。

const res = await fetch(`https://${SHOP}.myshopify.com/api/2026-10/graphql.json`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Shopify-Storefront-Access-Token": PUBLIC_STOREFRONT_TOKEN,
  },
  body: JSON.stringify({
    query: `{
      products(first: 6) {
        nodes {
          title
          handle
          priceRange { minVariantPrice { amount currencyCode } }
        }
      }
    }`,
  }),
});
const { data } = await res.json();

商品・コレクション・ページ・ブログ・カートの読み書きなどは、トークンなしでも呼べます。トークン不要のアクセスはクエリの複雑度が1,000までに制限されるため、本番ではトークンを発行して使います。購入者の通信に毎分の固定上限はありません。

Webhookで注文や在庫の変更を受け取る実装と取りこぼし対策

Webhookは、Shopify側で起きた変更を自社のサーバーへ送ってもらう仕組みです。Webhookの解説では、送り先にHTTPSのURL、Google Pub/Sub、Amazon EventBridgeを選べ、購読はshopify.app.tomlかGraphQL Admin APIで登録します。

X-Shopify-Hmac-SHA256の署名を生のリクエスト本文で検証するコード

Webhook配信の検証ガイドの手順は、生のリクエスト本文をアプリのクライアントシークレットでHMAC-SHA256にかけ、Base64にした値とヘッダーの値を比べるものです。JSONとして解析した後の本文では一致しないため、解析前のバイト列を使います。

import express from "express";
import crypto from "node:crypto";

const app = express();

app.post("/webhooks/orders-create", express.raw({ type: "application/json" }), (req, res) => {
  const received = Buffer.from(req.get("X-Shopify-Hmac-SHA256") || "", "utf8");
  const expected = Buffer.from(
    crypto.createHmac("sha256", process.env.SHOPIFY_CLIENT_SECRET).update(req.body).digest("base64"),
    "utf8",
  );
  if (received.length !== expected.length || !crypto.timingSafeEqual(received, expected)) {
    return res.sendStatus(401);
  }
  // 重い処理はキューに回し、ここでは記録だけしてすぐ200を返す
  enqueue({
    webhookId: req.get("X-Shopify-Webhook-Id"),
    topic: req.get("X-Shopify-Topic"),
    triggeredAt: req.get("X-Shopify-Triggered-At"),
    body: req.body.toString("utf8"),
  });
  res.sendStatus(200);
});

express.json()を先に全体へ掛けると、本文が解析済みになり検証が失敗します。署名検証と冪等な受け方の考え方は決済Webhookの署名検証と冪等な処理を解説した記事と共通です。

5秒以内の応答と4時間で8回の再試行、定期突き合わせの必要性

同じ検証ガイドによると、Shopifyは接続に1秒、リクエスト全体に5秒のタイムアウトを設けています。200以外の応答は3XXも含めてエラー扱いで、再試行は4時間のうちに8回です。Admin APIで登録した購読は、8回続けて失敗すると自動で削除されます。

Webhookの解説には、配信は常に保証されるわけではないこと、同じトピック内でも順序は保証されないことも書かれています。products/updateがproducts/createより先に届くこともあり、順番の判断に使う値はX-Shopify-Triggered-Atか本文のupdated_atです。受注連携では、重複をX-Shopify-Webhook-Idで弾き、数時間おきにAdmin APIで更新日時を条件に読み直すジョブを必ず並走させます。

Shopify APIで自社開発する場面と、連携アプリやiPaaSで済ませる場面

保守の負担まで含めて、作るかどうかの線を引きます。

自社開発を見送る条件と、APIで作る価値がある基幹連携の条件

連携先が会計ソフトや主要なCRMで、App Storeに定番の連携アプリがあるなら、まずそれを試します。同期する項目が標準的で、反映が数十分遅れても業務に支障がない場合、APIで自作すると保守費が月額料金を上回りがちです。この条件ではAPI開発を見送ります。

反対に、自社独自の基幹システムや倉庫システムとつなぐ場合、在庫を数分以内に合わせたい場合、複数ストアの注文を1か所に集めたい場合は、APIで作る価値があります。Salesforceのように連携先側の方式選びも絡むときは、Salesforceのシステム連携の方式選定を解説した記事も合わせて確認すると、両側の上限をそろえて設計できます。

開発会社へ依頼する前に決めるAPIバージョン更新と保守の担当者

APIバージョニングの解説では、新しいバージョンが3か月ごとに出て、各安定版は最低12か月使えます。2026年10月26日時点の最新安定版は2026-10で、利用期限は2027年10月16日です。期限切れのバージョンを指定すると、利用できる最も古い安定版で応答され、気づかないうちに挙動が変わります。

納品後に連携が止まる典型は、この更新を誰も担当していないことです。依頼前に、使うAPIと同期の頻度、扱う個人情報の範囲、年1回以上のバージョン更新を誰が行うかを決めておくと、見積もりの前提がそろいます。一創では、Shopifyのストア構築とあわせて、基幹システムや倉庫システムとのAPI連携の開発を受託しています。どのAPIで組むかから相談したい場合は、ECサイト制作・Shopify構築のサービスをご覧ください。ストア構築全体の工程はShopify構築の進め方を解説した記事にあります。

よくある質問

Shopify APIについてよく寄せられる質問をまとめました。

Shopify APIにはどんな種類がありますか？

外部連携でよく使うのは、管理データを読み書きするGraphQL Admin API、独自の購入画面を作るStorefront API、変更を通知するWebhookです。ほかに会員機能のCustomer Account API、テーマ用のAjax API、割引や配送のロジックをShopify内で動かすShopify Functionsなどがあります。

Shopify Admin APIとStorefront APIの違いは何ですか？

Admin APIは管理画面と同じ範囲のデータ（注文、顧客、在庫など）を読み書きでき、トークンはサーバーに置きます。Storefront APIは購入者に見せる商品情報やカートを扱い、公開トークンならブラウザから呼べるAPIです。エンドポイントも/admin/api/と/api/で分かれ、レート制限の考え方も異なります。

Shopify APIのレート制限に達するとどうなりますか？

GraphQL Admin APIでは、残りポイントが見積もりコストに足りないとクエリが実行されず、スロットルのエラーが返ります。ポイントはプランに応じて毎秒100〜2,000ずつ回復するので、待ってから再実行します。公式の制限一覧で推奨されている待機方法は、1秒のバックオフです。大量のデータ取得ならバルクオペレーションに切り替えると、この制限を受けません。

Shopify APIのアクセストークンはどこで発行しますか？

2026年1月以降、新しく作るカスタムアプリはDev Dashboardで作成し、そのアプリの認証方式でトークンを取得します。ストアと同じ組織のアプリならクライアント認証情報グラントで24時間有効のトークンを取得でき、別組織のアプリなら認可コードグラントでストアの承認を得ます。Storefront APIのトークンは、Admin APIとは別に発行するものです。

Shopify APIのバージョンはどれを指定すればよいですか？

新規開発では、その時点の最新安定版を指定します。2026年10月時点では2026-10で、利用できる期限は2027年10月16日です。バージョンは3か月ごとに出て最低12か月サポートされるため、年に1回は新しい版へ上げ、応答ヘッダーX-Shopify-API-Versionで実際に使われた版を確認する運用にします。