[!info] related notes

• 所属 MOC: Shopify MOC
• 前置概念: Shopify 应用
• 并列 API: Shopify Storefront API
• 事件通知: Shopify Webhook
• 问题排查: Shopify API 限流问题排查

Shopify Admin API

一句话定义

Shopify Admin API 是用于管理商店后台数据的接口，提供 GraphQL 和 REST 两种协议，允许应用读写产品、订单、客户、库存等核心数据。

核心机制 / 工作原理

1. 两种 API 协议

GraphQL Admin API（推荐）：

• 一次请求获取多种资源
• 只返回需要的字段
• 类型安全
• 实时文档

REST Admin API：

• 传统的 RESTful 接口
• 每个资源一个端点
• 适合简单查询
• 正在逐步废弃（2025 年后）

2. 认证方式

OAuth 2.0（公开应用）：

1. 用户点击"安装应用"
2. 重定向到 Shopify 授权页面
3. 用户同意授权
4. Shopify 返回 Access Token
5. 应用使用 Token 调用 API

Access Token（自定义应用）：

1. 在 Shopify Admin 创建自定义应用
2. 生成 Admin API Access Token
3. 直接使用 Token 调用 API

最小例子 / 最小场景

GraphQL：获取产品列表

query {
  products(first: 5) {
    edges {
      node {
        id
        title
        handle
        priceRangeV2 {
          minVariantPrice {
            amount
            currencyCode
          }
        }
        totalInventory
      }
    }
  }
}

GraphQL：创建产品

mutation {
  productCreate(input: {
    title: "Blue T-Shirt"
    vendor: "My Brand"
    productType: "Apparel"
  }) {
    product {
      id
      title
    }
    userErrors {
      field
      message
    }
  }
}

REST：获取产品（旧方式）

GET /admin/api/2024-01/products.json

边界与易混淆点

Admin API vs Storefront API

维度	Admin API	Storefront API
用途	管理后台数据	构建店铺前端
权限	完全访问	只读（部分写）
认证	OAuth/Access Token	Storefront Access Token
适用场景	应用开发	无头商务

API 限流

• REST API：每秒 2 次请求（Bucket 算法）
• GraphQL API：基于查询成本计算（每秒 50 个成本点）

超限后：返回 429 错误，需要等待或优化查询

详见：Shopify API 限流问题排查

核心功能

1. 产品管理

• 创建、更新、删除产品
• 管理变体（SKU、价格、库存）
• 上传产品图片
• 设置 SEO 信息

2. 订单管理

• 获取订单列表
• 更新订单状态
• 创建退款
• 发货和物流追踪

3. 客户管理

• 获取客户信息
• 更新客户标签
• 管理客户地址

4. 库存管理

• 查询库存水平
• 调整库存数量
• 管理多地点库存

5. 支付和结账

• 创建订单草稿
• 自定义结账流程
• 管理折扣码

Related notes

• Shopify MOC
• Shopify 应用
• Shopify Storefront API
• Shopify Webhook
• Shopify API 限流问题排查