Shopify GraphQL Admin API

一项用于与 Shopify GraphQL Admin API 交互的综合能力。该能力使 Claude 能够查询和管理 Shopify 商店数据的全部方面。

何时使用此能力

当用户询问以下内容时，请使用此能力：

• 商品（列出、搜索、创建、更新、删除）
• 订单（查看、取消、履约）
• 客户（列出、创建、更新）
• 库存（检查库存水位、调整数量）
• 折扣（创建折扣码、管理促销活动）
• 其他任何 Shopify 商店运营相关操作

需明确授权的关键操作

重要提示：在执行以下任一操作前，必须向用户请求明确许可：

• 退款：创建退款（不可逆的财务交易）
• 订单取消：取消订单（可能触发退款）
• 礼品卡停用：永久禁用礼品卡
• 库存调整：修改库存数量
• 商品删除：永久移除商品
• 折扣启用：更改面向客户的定价

务必先清晰展示即将发生的变更，并等待用户确认后方可执行。

使用方法

1. 使用 shopify_graphql 工具执行查询或变更操作
2. 检查响应中是否存在 errors（GraphQL 语法/执行错误）和 userErrors（业务校验错误）
3. 对大规模结果集使用分页参数：first 和 after
4. 所有 ID 必须格式化为：gid://shopify/Resource/123

可用参考文档

如需详细的操作模式与示例，请参阅以下参考文档：

• products.md — 商品与商品变体管理
• orders.md — 订单操作
• customers.md — 客户管理
• inventory.md — 库存与仓库位置
• discounts.md — 折扣码与促销活动
• collections.md — 商品集合
• fulfillments.md — 订单履约与物流配送
• refunds.md — 处理退款
• draft-orders.md — 草稿订单创建
• gift-cards.md — 礼品卡管理
• webhooks.md — 事件订阅
• locations.md — 门店位置信息
• marketing.md — 营销活动
• markets.md — 多市场配置
• menus.md — 导航菜单
• metafields.md — 自定义元字段
• pages.md — 商店页面
• blogs.md — 博客管理
• files.md — 文件上传
• shipping.md — 配送配置
• shop.md — 商店基本信息
• subscriptions.md — 订阅管理
• translations.md — 内容翻译
• segments.md — 客户细分
• bulk-operations.md — 批量数据操作

快速示例

列出最近的订单

query {
  orders(first: 10, sortKey: CREATED_AT, reverse: true) {
    nodes {
      id
      name
      totalPriceSet {
        shopMoney { amount currencyCode }
      }
      customer { displayName }
    }
  }
}

搜索商品

query {
  products(first: 10, query: "title:*shirt* AND status:ACTIVE") {
    nodes {
      id
      title
      status
    }
  }
}

检查库存

query GetInventory($id: ID!) {
  inventoryItem(id: $id) {
    id
    inventoryLevels(first: 5) {
      nodes {
        quantities(names: ["available"]) {
          name
          quantity
        }
        location { name }
      }
    }
  }
}

错误处理

始终检查响应内容：

• errors 数组：表示 GraphQL 语法或执行层面的问题
• 变更操作（mutation）响应中的 userErrors：表示业务逻辑校验失败

最佳实践

1. 仅请求必需字段，以优化响应体积
2. 对可能持续增长的列表使用分页机制
3. 在所有变更操作（mutation）响应中检查 userErrors
4. 对高风险操作（如删除、退款等）必须事先征得用户许可
5. 以清晰、易读的方式向用户呈现结果
6. 对大规模数据导出/导入任务，优先使用批量操作（bulk operations）
7. 妥善处理速率限制（rate limit），采用指数退避策略重试