Shopify API 概要

Shopify は、コマースプラットフォームのほぼすべての側面を読み取り、書き込み、拡張できる豊富な API セットを公開しています。各タスクに適切な API を選択することは、Shopify 開発における最も重要なスキルの一つです。このレッスンでは、認証、バージョニング、レート制限、および各 API の具体的なユースケースを含む、API 全体のマップを提供します。

API ランドスケープ

Admin API（GraphQL と REST）

Admin API は Shopify エコシステムで最も包括的な API です。ストアデータへの完全な CRUD アクセスを提供し、アプリのほとんどのバックエンドオペレーションに使用されます。

GraphQL vs REST

Shopify は Admin API の GraphQL 版と REST 版の両方を維持していますが、GraphQL が今後の主要な API です。新機能は GraphQL に最初に追加され、一部の機能は GraphQL 専用です。

項目	GraphQL	REST
データ取得	必要なものだけをリクエスト	固定のレスポンス形式
レート制限	コストベース（1,000ポイント/秒）	リクエストベース（40リクエスト/秒）
新機能	最初に追加	遅れる場合や追加されない場合あり
一括オペレーション	サポートあり	サポートなし
ミューテーション	単一エンドポイント	リソース固有のエンドポイント
学習曲線	やや急	緩やか

GraphQL を推奨

Shopify は GraphQL が API プラットフォームの未来であると明確に述べています。metaobjects、markets、fulfillment orders などの新しいリソースは、REST サポートが限定的またはまったくありません。新しいプロジェクトでは常に GraphQL を使用してください。

Admin API 認証

アプリは OAuth 2.0 を介して Admin API で認証します。フローは以下の通りです：

アクセストークンは特定のストアにスコープされ、マーチャントが承認した権限（スコープ）のみを持ちます。一般的なスコープには以下が含まれます：

read_products / write_products -- 商品カタログへのアクセス
read_orders / write_orders -- 注文管理
read_customers / write_customers -- 顧客データ
read_inventory / write_inventory -- 在庫レベル
read_content / write_content -- メタオブジェクトとコンテンツ

最小限のスコープをリクエストする

アプリが実際に必要とするスコープのみをリクエストしてください。過剰なスコープリクエストはインストール率を低下させます -- すべてにアクセスしたがるアプリに対してマーチャントが疑いを持つのは当然です。再認可フローを通じて後から追加のスコープをリクエストすることもできます。

Storefront API

Storefront API は顧客向けアプリケーション用に設計されています。Admin API とは異なり、クライアントサイドのコードに安全に含めることができるパブリックアクセストークンを使用します。

ユースケース

Hydrogen ストアフロント: ヘッドレスストアフロントでのすべてのデータ取得
カスタム商品ピッカー: ストアフロント上の JavaScript ウィジェット
モバイルアプリ: ネイティブ iOS/Android ショッピングアプリ
Buy Button: 外部ウェブサイトへの商品埋め込み
カート操作: アイテムの追加、ディスカウントコードの適用、カート管理

Admin API との主な違い

機能	Admin API	Storefront API
認証	プライベートアクセストークン	パブリックアクセストークン
データアクセス	完全な読み取り/書き込み	読み取り専用 + カートミューテーション
対象	アプリバックエンド	顧客向けクライアント
レート制限	ストア単位	アプリ単位、ストア単位
顧客データ	完全アクセス	認証済み顧客のみ

# Storefront API: コレクションページ用の商品取得
query CollectionProducts($handle: String!, $first: Int!) {
  collection(handle: $handle) {
    title
    products(first: $first) {
      edges {
        node {
          id
          title
          priceRange {
            minVariantPrice {
              amount
              currencyCode
            }
          }
          images(first: 1) {
            edges {
              node {
                url
                altText
              }
            }
          }
        }
      }
    }
  }
}

Payments Apps API

Payments Apps API を使用すると、Shopify Checkout に直接統合する決済ゲートウェイを構築できます。これは決済サービスプロバイダー向けの専門 API です。

クレジットカード、オフサイト、カスタムオンサイトの決済方法をサポート
クレジットカード処理には PCI DSS 準拠が必要
決済セッションに Webhook ベースのフローを使用
パートナーダッシュボードを通じて追加審査のもとに登録

Payments Apps は専門的

ほとんどの開発者はこの API を必要としません。決済ゲートウェイや代替決済方法を構築する場合にのみ関連します。単に決済を受け付ける必要がある場合は、Shopify Payments または既存の決済ゲートウェイアプリを使用してください。

Customer Account API

Customer Account API は、新しいカスタマーアカウントエクスペリエンス（2024年導入）でのカスタマーセルフサービス機能を実現します。認証済みの顧客が以下を行えます：

注文の表示と管理
プロフィール情報の更新
住所の管理
ロイヤルティおよびリワードプログラムへのアクセス
B2B 企業情報の閲覧

この API は、Shopify の新しい顧客認証システムを通じて取得したカスタマーアクセストークンを使用します。

Functions API

Functions API は、Shopify Functions が入力データを受け取り出力を返す方法を定義します。従来の HTTP API ではなく、WebAssembly モジュールと Shopify ランタイム間のコントラクトです。

各 Function エクステンションターゲットには特定の入力/出力スキーマがあります：

# ディスカウント Function の入力クエリ
query Input {
  cart {
    lines {
      merchandise {
        ... on ProductVariant {
          product {
            hasAnyTag(tags: ["vip-discount"])
          }
        }
      }
      cost {
        totalAmount {
          amount
        }
      }
    }
  }
}

// 出力: VIP 商品に 10% ディスカウントを適用
{
  "discounts": [
    {
      "value": {
        "percentage": {
          "value": "10.0"
        }
      },
      "targets": [
        {
          "productVariant": {
            "id": "gid://shopify/ProductVariant/123"
          }
        }
      ],
      "message": "VIP 10% Off"
    }
  ]
}

Checkout Extensions API

Checkout Extensions API を使用すると、Shopify チェックアウト内でレンダリングされる React ベースの UI コンポーネントを構築できます。エクステンションターゲットは UI の表示場所を定義します：

purchase.checkout.block.render -- メインチェックアウトエリアのブロック
purchase.checkout.header.render-after -- チェックアウトヘッダーの後
purchase.checkout.footer.render-before -- チェックアウトフッターの前
purchase.thank-you.block.render -- サンキューページ
purchase.checkout.shipping-option-item.render-after -- 各配送オプションの後

エクステンションは Checkout UI Extensions ライブラリの限定された UI コンポーネントセットを使用します（Polaris ではありません）。

Flow トリガーとアクション API

Shopify Flow はマーチャント向けのビジュアル自動化プラットフォームです。あなたのアプリは以下を提供して Flow と統合できます：

トリガー: Flow ワークフローを開始するイベント（例：「新しいレビューが投稿されました」）
アクション: Flow があなたのアプリで呼び出せるオペレーション（例：「ロイヤルティポイントを送信」）

これは、完全な自動化 UI を自分で構築することなく、アプリをより便利にする強力な方法です。

API バージョニング

Shopify はカレンダーベースのバージョニングシステムを使用しています。新しい API バージョンは四半期ごとにリリースされます：

バージョン	リリース	ステータス
`2025-07`	2025年7月	サポート中
`2025-10`	2025年10月	サポート中
`2026-01`	2026年1月	現在の安定版
`2026-04`	2026年4月	リリース候補

バージョニングルール

各バージョンはリリース後12ヶ月間サポートされます
破壊的変更はバージョン間でのみ発生し、バージョン内では発生しません
API リクエストでバージョンを指定します：
- GraphQL: X-Shopify-API-Version: 2026-01 ヘッダー
- REST: /admin/api/2026-01/products.json URL パス
非推奨通知は削除の9ヶ月前に API レスポンスに表示されます

# 明示的なバージョンを指定した GraphQL リクエスト
curl -X POST "https://your-store.myshopify.com/admin/api/2026-01/graphql.json" \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: your-token" \
  -d '{"query": "{ shop { name } }"}'

最新バージョンを維持する

四半期ごとに API バージョンを更新するカレンダーリマインダーを設定しましょう。バージョンの更新が遅れると、新機能を逃し、最終的に非推奨の壁に突き当たります。Shopify CLI とパートナーダッシュボードは、古いバージョンを使用している場合に警告を表示します。

レート制限

レート制限はプラットフォームを保護し、ストア上のすべてのアプリに公平なアクセスを保証します。

GraphQL レート制限

GraphQL はコストベースのシステムを使用します：

各ストアはアプリに1秒あたり1,000コストポイントを付与します
ポイントは1秒あたり50ポイントで回復します（リーキーバケットアルゴリズム）
シンプルなクエリは1〜10ポイント；コネクションを含む複雑なクエリはそれ以上のコストがかかります
レスポンスには残りの予算を示す throttleStatus オブジェクトが含まれます

{
  "extensions": {
    "cost": {
      "requestedQueryCost": 12,
      "actualQueryCost": 8,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 992,
        "restoreRate": 50
      }
    }
  }
}

REST レート制限

REST はよりシンプルなリクエストベースのモデルを使用します：

スタンダードプラン: ストアあたり1秒40リクエスト
Shopify Plus: ストアあたり1秒80リクエスト（一部のエンドポイントはさらに高い）
X-Shopify-Shop-Api-Call-Limit レスポンスヘッダーで追跡

レート制限の処理

// 指数バックオフ付きリトライ
async function shopifyRequest(query, retries = 3) {
  for (let attempt = 0; attempt < retries; attempt++) {
    const response = await admin.graphql(query);

    if (response.status === 429) {
      const retryAfter = parseFloat(
        response.headers.get("Retry-After") || "1"
      );
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }

    return response.json();
  }
  throw new Error("Rate limit exceeded after retries");
}

カーソルベースページネーション

GraphQL と REST の両方が、リストエンドポイントにカーソルベースページネーションを使用します。これは同時データ変更を正しく処理するため、オフセットベースのページネーションよりも信頼性が高くなります。

GraphQL ページネーション

query Products($first: Int!, $after: String) {
  products(first: $first, after: $after) {
    edges {
      cursor
      node {
        id
        title
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

次のページを取得するには、endCursor の値を after 変数として渡します。hasNextPage が false になるまで続けます。

REST ページネーション

REST API は Link ヘッダーでページネーションリンクを返します：

Link: <https://store.myshopify.com/admin/api/2026-01/products.json?page_info=abc123&limit=50>; rel="next"

rel="next" の URL を解析し、次のリクエストに使用します。

ページ番号を使用しない

Shopify は数年前にページ番号ベースのページネーションを非推奨にしました。常にカーソルベースのページネーションを使用してください。?page=2 を使用している古いチュートリアルを見つけた場合、それらは古くなっており動作しません。

適切な API の選択

やりたいこと	使用する API
アプリバックエンドから商品、注文、顧客を管理	Admin API (GraphQL)
カスタムストアフロントに商品を表示	Storefront API
Hydrogen でヘッドレスストアフロントを構築	Storefront API
チェックアウトでディスカウントロジックをカスタマイズ	Functions API（ディスカウントターゲット）
チェックアウトページに UI を追加	Checkout Extensions API
ゲートウェイとして決済を処理	Payments Apps API
顧客がアカウントを管理できるようにする	Customer Account API
Shopify Flow 自動化と統合	Flow トリガー & アクション API
大規模データセットのエクスポート/インポート	Admin API 一括オペレーション

次のレッスンでは、最も重要な Shopify API を動かすクエリ言語である GraphQL を詳しく見ていきます。

API ランドスケープ​

Admin API（GraphQL と REST）​

GraphQL vs REST​

Admin API 認証​

Storefront API​

ユースケース​

Admin API との主な違い​

Payments Apps API​

Customer Account API​

Functions API​

Checkout Extensions API​

Flow トリガーとアクション API​

API バージョニング​

バージョニングルール​

レート制限​

GraphQL レート制限​

REST レート制限​

レート制限の処理​

カーソルベースページネーション​

GraphQL ページネーション​

REST ページネーション​

適切な API の選択​