Shopify Admin API 技能用于程序化执行 Shopify 商店运营相关操作。其适用场景是当用户提到 Shopify、在线商店、商品、订单、库存、客户、履约等关键词时，通过 Admin API 完成查询与写入。
认证与配置
所有请求使用来自 Shopify 自定义应用的长期有效 Admin API 访问令牌，通过请求头 X-Shopify-Access-Token: $SHOPIFY_TOKEN 传递。环境变量包括：SHOPIFY_TOKEN（Admin API 访问令牌，以 shpat_ 开头）、SHOPIFY_SHOP（仅商店子域名，例如 acme.myshopify.com 应填 acme）。基础 URL 为 https://$SHOPIFY_SHOP.myshopify.com/admin/api/2025-01。Shopify 每季度发布一个稳定 API 版本，2025-01 为当前稳定版本，可替换为目标版本。
主要能力
REST Admin API（文档：https://shopify.dev/docs/api/admin-rest）支持以下操作：获取店铺信息（/shop.json）、列出商品（/products.json?limit=50）、获取单个商品（/products/<product-id>.json）、创建商品（POST /products.json，示例载荷包含 title、body_html、vendor、product_type、status、tags）、列出订单（/orders.json?status=any&limit=50）、获取单个订单（/orders/<order-id>.json）、列出客户（/customers.json?limit=50）、搜索客户（/customers/search.json，使用 query=email:jane@example.com）、查询某地点的库存水平（/inventory_levels.json?location_ids=<location-id>）。
GraphQL Admin API（文档：https://shopify.dev/docs/api/admin-graphql）端点：POST https://$SHOPIFY_SHOP.myshopify.com/admin/api/2025-01/graphql.json。Shopify 推荐新集成使用 GraphQL：它只返回请求的字段，并采用更高的基于成本的限流。示例查询可获取前 10 个商品的 id、title、status、totalInventory。
分页与限流
REST 端点使用基于游标的分页，通过 Link 头实现；可加 -i 查看响应头，然后原样跟随 rel="next" 的 URL（其中已包含 page_info）。文档：https://shopify.dev/docs/api/usage/pagination-rest。限流方面，REST Admin API 为漏桶限流（标准套餐 2 请求/秒）；GraphQL 使用计算成本模型（1000 点/分钟）。可检查响应头 X-Shopify-Shop-Api-Call-Limit（REST）或 extensions.cost 块（GraphQL）。文档：https://shopify.dev/docs/api/usage/limits。
使用方式与排查
若请求失败，可运行 zero doctor check-connector --env-name SHOPIFY_TOKEN 或 zero doctor check-connector --url "https://$SHOPIFY_SHOP.myshopify.com/admin/api/2025-01/shop.json" --method GET 进行排查。
注意事项
SHOPIFY_SHOP 只填子域名（如 acme），不要填完整的 .myshopify.com URL。始终在路径中固定 API 版本（/admin/api/2025-01/...），Shopify 约 12 个月后弃用旧版本。令牌权限范围在自定义应用安装时固定；出现 403 权限错误意味着商家需以额外权限重新安装应用。读密集型工作流建议优先使用 GraphQL（选择字段成本更低）；简单写入用 REST 即可。当搜索查询包含空格或特殊字符时，使用 -G 配合 --data-urlencode，因为 Shopify 搜索语法使用 field:value 键值对。