案例作品集 浏览精选项目

Shopify Plus 升级月费减免+最高抵扣$4800开发费用 - WesWoo专属优惠

指南

Shopify API 接入指南：选型、认证、限流与 Webhook 验收

发布日期： 编辑复核：2026-08-26

Shopify API 集成先要划清数据边界：后台商品、订单、客户和库存，与店铺前台的商品展示、购物车并不是同一种访问。本文面向跨境独立站和内部系统团队，给出 API 选型、认证、版本、限流、错误和 Webhook 的可复核做法；示例只使用占位符，不包含真实店铺或凭据。

选对 API 数据面

如果应用需要代表商家读取或修改商品、订单、客户、库存等后台数据，优先从 GraphQL Admin API 开始。Shopify 已将 REST Admin API 标记为 legacy（旧版）接口，自 2024 年 10 月 1 日起不应再把 REST 当作新集成的默认方向；自 2025 年 4 月 1 日起，提交到 Shopify App Store 的新公开应用必须只使用 GraphQL Admin API。REST 仍可作为已有连接器的迁移范围，但应先登记依赖、权限和替换计划。

店铺前台或买家账户的需求，应单独评估 Storefront API、Customer Account API 或相应扩展能力。不要把 Admin API 令牌放到浏览器，也不要因为一个接口能读到数据，就把后台访问范围授予前台。Webhook 是事件通知机制，不是另一种万能数据接口；收到事件后仍应按需读取权威记录并完成对账。

需求起点必须先确认
商品、订单、客户、库存或 ERP 同步GraphQL Admin API最小 scopes、游标分页、查询成本、写入幂等
维护已有 REST 连接器版本化 REST Admin APIlegacy 影响、迁移字段、弃用时间和回滚
Headless 前台、商品展示或购物车Storefront API前台令牌边界、缓存、市场和买家数据
订单或商品事件同步Webhook 加 Admin API 读取HMAC、去重、队列、重试和定期对账

认证路径与最小权限

认证方式取决于应用在哪里运行，以及它代表谁访问商店。嵌入式应用通常使用 token exchange；在 Shopify 管理后台之外运行的应用通常使用 authorization code grant；只访问自有 Shopify 组织店铺的服务端集成可以评估 client credentials grant；没有自己后端的扩展应用则按 Direct API access 方式配置。不要把其中一种流程当作所有项目的通用 OAuth 模板。

每个 Admin API 请求都要使用与应用、商店和权限匹配的 access token，并通过 X-Shopify-Access-Token 请求头发送。只申请业务真正需要的 scopes，尤其谨慎处理客户和订单数据。令牌、客户端密钥和回调签名密钥应只保存在服务端的密钥管理系统中；开发、测试和生产凭据分开，日志、截图和仓库不得出现凭据。需要区分 online 与 offline token：前者跟员工会话相关，后者适合 Webhook 和计划任务；如果令牌会过期，应读取响应中的 expires_in，不要永久写死有效期。

一个最小的 Admin GraphQL 请求

先用只读查询验证网络、应用、商店和权限，再实现写入。请求骨架可以写成：POST https://{shop-domain}/admin/api/{api-version}/graphql.json；请求头使用 Content-Type: application/json 和 X-Shopify-Access-Token: ${SHOPIFY_ACCESS_TOKEN}；请求体可从 {"query":"query ShopIdentity { shop { name } }"} 开始。{shop-domain}、{api-version} 和环境变量都是占位符，不要替换成真实令牌后提交到公开代码。

截至 2026 年 8 月 26 日，版本页列出的当前稳定版本是 2026-07。示例中的版本只代表复核日；上线前重新核对支持状态，并同时检查 HTTP 状态、GraphQL 顶层 errors、mutation 返回的 userErrors 和 extensions.cost，不能只看一次 HTTP 200。

版本管理要有时间边界

Shopify 按季度发布 API 版本，每个稳定版本至少支持 12 个月。生产请求应在 URL 中显式指定受支持的稳定版本，不要依赖 latest、unstable 或 release candidate。若请求版本不再可访问，Shopify 会 fall forward 到仍可访问的稳定版本；响应头 X-Shopify-API-Version 会显示实际执行版本。请求版本与响应版本不一致时，应触发升级告警，而不是静默接受。

每个季度查看弃用说明、开发者更新和 API 健康报告，在测试商店验证字段、scopes、Webhook 负载和错误路径，再安排升级。把版本、复核日期、迁移负责人和回滚方式写进集成记录，避免把 2026-07 误写成永久配置。

分页、查询成本与限流

GraphQL Admin API 按计算查询成本限流，容量以每个 app 与 shop 的组合计算，不是每天固定的请求次数。复核日官方表列出的恢复率为：Standard 100 点/秒、Advanced 200 点/秒、Plus 1,000 点/秒、Commerce Components 2,000 点/秒。这些数值会受平台策略和请求形状影响，应作为当前文档参考，而不是对所有商店的永久承诺。

读取连接使用 cursor pagination，并用 first 或 last 控制页面大小；从响应的 extensions.cost 记录 requestedQueryCost、actualQueryCost 和 throttleStatus。把批量同步放进队列，根据可用点数调度；遇到限流、网络失败或 5xx 时使用有限次数的指数退避和随机抖动，写入使用幂等键。单个查询最多 1,000 点，数组输入最多 250 项；更大的导入或导出应评估 bulk operations 和分段任务。

如果只是维护旧 REST 集成，官方规则是每个 app、每个 shop 一个容量为 40 个请求的桶，按每秒 2 个请求恢复，Shopify Plus 的容量和恢复速率提高 10 倍。REST 响应可查看 X-Shopify-Shop-Api-Call-Limit，遇到 429 遵循 Retry-After。这不是每天 40,000 次的配额，也不是新实现继续选择 REST 的理由。

区分认证、限流和业务错误

  • 401 Unauthorized：令牌缺失、错误、过期或与应用和商店不匹配；先核对认证流程与令牌生命周期。
  • 403 Forbidden：通常与 scopes 或员工权限不足有关；不要用扩大权限掩盖数据边界设计问题。
  • 429 Too Many Requests 或 GraphQL THROTTLED：读取限流状态，等待并按退避策略重试，避免并发补发。
  • 5xx、连接失败或超时：记录请求标识，有限次重试并进入告警或死信流程，不要无限循环。
  • GraphQL 即使返回 HTTP 200，也可能在顶层 errors 中报告失败；mutation 还必须检查 userErrors 和返回数据。

日志至少应能按 shop、任务、API 版本、状态、延迟和请求标识定位问题，同时脱敏令牌、客户字段和客户端密钥。对可重试写入保留幂等键和结果状态，让重试不会重复创建订单外部记录或重复扣减库存。

Webhook 的订阅、验签与对账

如果所有安装店铺使用相同主题、地址或筛选条件，应用级订阅（app-specific subscription）应在 shopify.app.toml 中声明；如果每个店铺的配置不同，再通过 GraphQL Admin API 创建店铺级订阅（shop-specific subscription）。每个主题都要确认相应 scopes、API 版本和负载字段，升级时在测试商店重放代表性事件。

HTTPS 接收端必须在解析正文前，使用客户端密钥和原始请求体校验 X-Shopify-Hmac-SHA256。用 X-Shopify-Webhook-Id 做幂等去重，先把事件写入可靠队列，再尽快返回 2xx；Shopify 文档给出的完整请求超时为 5 秒。处理失败应有限重试并保留 dead-letter 记录，定期用 Admin API 对账，覆盖漏投、重复、乱序和人工修正的情况。Webhook 负责及时通知，不能替代完整性校验。

上线前验收清单

  1. 写明每项数据的归属和用途，确认 Admin、Storefront、Customer Account 或扩展的边界。
  2. 按应用形态验收认证流程、最小 scopes、online/offline token、过期处理和撤销路径。
  3. 固定当前稳定版本，记录复核日期；检查 X-Shopify-API-Version，并安排季度升级。
  4. 在测试商店验证游标分页、查询成本、1,000 点查询上限、250 项数组上限和限流退避。
  5. 模拟 401、403、429、THROTTLED、5xx、超时、顶层 errors、mutation userErrors 和重复写入。
  6. 验证应用级或店铺级 Webhook、原始正文 HMAC、去重、快速 2xx、重试、死信和对账。
  7. 检查日志和监控不会泄露令牌或不必要的客户数据，并明确上线后的告警、回滚和责任人。

FAQ

新公开应用还能把 REST Admin API 当默认方案吗？

不应这样做。REST Admin API 已是 legacy；自 2025 年 4 月 1 日起，提交到 Shopify App Store 的新公开应用必须只使用 GraphQL Admin API。已有 REST 连接器应按字段、权限、错误和回滚范围制定迁移计划。

Admin API 和 Storefront API 可以共用令牌吗？

不要共用。两者服务的信任边界和数据用途不同；Admin 令牌应留在服务端，前台只使用与买家体验匹配的公开访问方式，并按官方文档核对权限和数据暴露。

GraphQL 请求返回 HTTP 200 就代表操作成功吗？

不代表。先检查顶层 errors，再检查 mutation 的 userErrors、返回数据和 extensions.cost；只有结果、权限和业务状态都符合预期，才算成功。

Webhook 能代替定期对账吗？

不能。Webhook 适合降低事件发现延迟，但仍可能出现重复、乱序、漏投或人工修正。保留事件 ID 和处理结果，并用 Admin API 定期对账，才能发现差异。

相关内部阅读：Shopify API 开发与跨境电商扩展。

Sources