Shopify API 概覽

Shopify 提供了一套豐富的 API，讓您可以讀取、寫入和擴展商務平台的幾乎所有面向。為每項任務選擇正確的 API 是 Shopify 開發中最重要的技能之一。本課程提供完整的 API 全景地圖，涵蓋驗證、版本管理、速率限制，以及每個 API 的具體使用案例。

API 全景

Admin API（GraphQL 和 REST）

Admin API 是 Shopify 生態系統中最全面的 API。它提供商店資料的完整 CRUD 存取，是您的應用程式用於大多數後端操作的 API。

GraphQL 與 REST 比較

Shopify 同時維護 GraphQL 和 REST 版本的 Admin API，但 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 購物應用程式
購買按鈕： 在外部網站上嵌入商品
購物車操作： 添加商品、套用折扣碼、管理購物車

與 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 結帳的付款閘道。這是專門為付款服務提供商設計的 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 元件。擴充目標定義了您的介面出現的位置：

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 Triggers and Actions API

Shopify Flow 是商家的視覺化自動化平台。您的應用程式可以透過提供以下內容與 Flow 整合：

觸發器： 啟動 Flow 工作流程的事件（例如「新評論已提交」）
動作： Flow 可以在您的應用程式中呼叫的操作（例如「發送忠誠點數」）

這是一個強大的方式，讓您的應用程式更有用，而無需自行建構完整的自動化介面。

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,000 個成本點數
點數以每秒 50 點的速率恢復（漏桶演算法）
簡單查詢花費 1-10 點；帶有連接的複雜查詢花費更多
回應包含一個 throttleStatus 物件，顯示您的剩餘配額

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

REST 速率限制

REST 使用更簡單的基於請求的模型：

標準方案： 每個商店每秒 40 個請求
Shopify Plus： 每個商店每秒 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（折扣目標）
將介面新增到結帳頁面	Checkout Extensions API
作為閘道處理付款	Payments Apps API
讓客戶管理自己的帳戶	Customer Account API
整合 Shopify Flow 自動化	Flow Triggers & Actions API
匯出/匯入大型資料集	Admin API Bulk Operations

在下一課中，我們將深入探討 GraphQL——驅動最重要的 Shopify API 的查詢語言。

API 全景​

Admin API（GraphQL 和 REST）​

GraphQL 與 REST 比較​

Admin API 驗證​

Storefront API​

使用案例​

與 Admin API 的主要差異​

Payments Apps API​

Customer Account API​

Functions API​

Checkout Extensions API​

Flow Triggers and Actions API​

API 版本管理​

版本管理規則​

速率限制​

GraphQL 速率限制​

REST 速率限制​

處理速率限制​

基於游標的分頁​

GraphQL 分頁​

REST 分頁​

選擇正確的 API​