Shopify API 概览
Shopify 提供了一套丰富的 API，让你可以读取、写入和扩展商业平台的几乎所有方面。为每项任务选择正确的 API 是 Shopify 开发中最重要的技能之一。本课提供了完整的 API 全景图，涵盖认证、版本管理、速率限制以及每个 API 的具体使用场景。
API 全景
Admin API（GraphQL 和 REST）
Admin API 是 Shopify 生态系统中最全面的 API。它提供对商店数据的完整 CRUD 访问，是你的应用进行大多数后端操作时使用的 API。
GraphQL 与 REST
Shopify 同时维护着 Admin API 的 GraphQL 和 REST 版本，但 GraphQL 是未来的主要 API。新功能会先添加到 GraphQL 中，有些功能仅在 GraphQL 中可用。
| 方面 | GraphQL | REST |
|---|---|---|
| 数据获取 | 精确请求所需数据 | 固定的响应结构 |
| 速率限制 | 基于成本（1,000 点/秒） | 基于请求（40 请求/秒） |
| 新功能 | 优先添加 | 可能滞后或永远不会添加 |
| 批量操作 | 支持 | 不支持 |
| 变更操作 | 单一端点 | 资源特定端点 |
| 学习曲线 | 较陡 | 较缓 |
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-- Metaobjects 和内容
只请求你的应用实际需要的作用域。过多的作用域请求会降低安装率——商家对要求访问所有数据的应用理所当然会持怀疑态度。你总是可以稍后通过重新授权流程请求额外的作用域。
Storefront API
Storefront API 专为面向客户的应用设计。与 Admin API 不同，它使用 公开访问令牌，可以安全地包含在客户端代码中。
使用场景
- Hydrogen 店面：无头店面中的所有数据获取
- 自定义产品选择器：店面上的 JavaScript 小组件
- 移动应用：原生 iOS/Android 购物应用
- Buy Button：在外部网站上嵌入产品
- 购物车操作：添加商品、应用折扣码、管理购物车
与 Admin API 的主要区别
| 特性 | Admin API | Storefront API |
|---|---|---|
| 认证 | 私有访问令牌 | 公开访问令牌 |
| 数据访问 | 完整读写 | 只读 + 购物车变更 |
| 目标受众 | 应用后端 | 面向客户的客户端 |
| 速率限制 | 按商店 | 按应用、按商店 |
| 客户数据 | 完整访问 | 仅已认证客户 |
# Storefront API: Fetch products for a collection page
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 的支付会话流程
- 通过合作伙伴仪表板注册，需要额外审核
大多数开发者永远不会用到此 API。它仅在你构建支付网关或替代支付方式时才有用。如果你只需要接受付款，请使用 Shopify Payments 或现有的支付网关应用。
Customer Account API
Customer Account API 在新的客户账户体验中（2024 年推出）启用客户自助服务功能。它让已认证的客户可以：
- 查看和管理订单
- 更新个人信息
- 管理地址
- 访问忠诚度和奖励计划
- 查看 B2B 公司信息
此 API 使用通过 Shopify 新客户认证系统获取的 客户访问令牌。
Functions API
Functions API 定义了 Shopify Functions 如何接收输入数据并返回输出。它不是传统的 HTTP API——而是你的 WebAssembly 模块与 Shopify 运行时之间的契约。
每个 Function 扩展目标都有特定的输入/输出模式：
# Input query for a Discount Function
query Input {
cart {
lines {
merchandise {
... on ProductVariant {
product {
hasAnyTag(tags: ["vip-discount"])
}
}
}
cost {
totalAmount {
amount
}
}
}
}
}
// Output: Apply a 10% discount to VIP products
{
"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 Triggers 和 Actions API
Shopify Flow 是面向商家的可视化自动化平台。你的应用可以通过提供以下内容与 Flow 集成：
- Triggers：启动 Flow 工作流的事件（例如"新评论已提交"）
- Actions：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.jsonURL 路径
- GraphQL:
- 弃用通知 会在移除前 9 个月出现在 API 响应中
# GraphQL request with explicit version
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响应头跟踪
处理速率限制
// Retry with exponential backoff
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 Triggers & Actions API |
| 导出/导入大型数据集 | Admin API Bulk Operations |
在下一课中，我们将深入研究 GraphQL——驱动最重要的 Shopify API 的查询语言。