用途
该技能对 Shopify 某个集合或标签下的所有商品变体，在单个自动化流程中应用百分比或固定金额的价格调整，无需在后台手动逐个操作商品、导出 CSV、编辑再重新导入。适用场景包括：全店或集合级促销、促销结束后恢复价格、传导供应商成本上涨，或统一某类商品的定价。
主要能力
- 按集合（collection_id）或标签（tag）筛选目标商品，二者必选其一。
- 支持两种调价方式：百分比（percent）或固定金额（fixed）。调整值为正表示涨价，为负表示降价；例如 percent 下 -10 表示打九折。
- 支持最低价（min_price，默认 0）和最高价（max_price，可选）约束，确保变体价格不被设置到区间之外。
- 自动分页：集合商品超过 250 个时自动翻页，CSV 会包含全部变体。
- 支持 dry_run 预览模式，仅生成变更清单而不执行实际修改。
- 输出 CSV 文件 price_changes_<YYYY-MM-DD>.csv，列为 product_id、variant_id、sku、title、old_price、new_price。
- 支持 human 与 json 两种输出格式，并在各阶段输出会话跟踪信息。
使用方式
前置条件：
- 已认证的 Shopify CLI 会话：shopify auth login --store <domain>
- API 权限范围：read_products、write_products
参数：
- store（字符串，必填）：店铺域名，例如 mystore.myshopify.com
- format（字符串，可选，默认 human）：输出格式，human 或 json
- dry_run（布尔，可选，默认 false）：预览操作而不执行变更
- collection_id（字符串，可选*）：目标集合的 GID，例如 gid://shopify/Collection/123
- tag（字符串，可选*）：用于筛选的商品标签（collection_id 的替代项）
- adjustment_type（字符串，必填）：percent 或 fixed
- adjustment_value（浮点数，必填）：调整量。正数为涨价，负数为降价。percent 下 -10 表示 10% 折扣
- min_price（浮点数，可选，默认 0）：价格下限，任何变体不会被设置到低于此值
- max_price（浮点数，可选）：价格上限，任何变体不会被设置到高于此值
*collection_id 与 tag 必须提供其中一个。
工作流程：
- products 查询：输入 first: 250、query: "collection_id:'<id>'" 或 query: "tag:'<tag>'"、分页游标；输出包含全部变体 ID、当前价格、SKU 的商品列表，翻页直到 hasNextPage: false。
- productVariantsBulkUpdate 变更：对每个商品传入 productId 与 {id, price} 数组（已按 min_price/max_price 约束计算新价格）；输出每个变体的更新价格与 userErrors 数组，收集所有批次中的错误。
GraphQL 操作（已针对 api_version 2025-01 验证）：
# products:query
query ProductsForPriceAdjustment($first: Int!, $after: String, $query: String) {
products(first: $first, after: $after, query: $query) {
edges {
node {
id
title
tags
variants(first: 100) {
edges {
node {
id
title
price
compareAtPrice
sku
}
}
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
# productVariantsBulkUpdate:mutation
mutation ProductVariantsBulkUpdate($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
productVariantsBulkUpdate(productId: $productId, variants: $variants) {
productVariants {
id
price
compareAtPrice
}
userErrors {
field
message
}
}
}
适用场景
- 运行全店或集合级促销。
- 促销结束后恢复价格。
- 传导供应商成本上涨。
- 统一某类商品的定价。
限制与安全注意事项
- 第 2 步会执行 productVariantsBulkUpdate 变更，立即修改线上价格。价格变更无法通过 API 批量撤销，每个变体必须单独恢复。
- 务必先以 dry_run: true 运行，审阅完整变更集后再提交；提交前核对 dry_run 输出的 CSV 是否符合预期。
- 建议将 min_price 设为成本下限，防止百分比折扣时变体价格低于成本。
- 提交后、公布促销前，应在 Shopify 后台抽查部分价格；userErrors 会被记录但不会中止执行。
错误处理：
- 未提供 collection_id 或 tag：两者均为空，需提供其中之一。
- 变更响应中出现 userErrors：价格无效或变体未找到，按变体记录错误，继续处理其余变体，并在结果中报告。
- 集合中未找到商品：collection_id 错误或集合为空，需在 Shopify 后台核对集合 GID。
- 速率限制（429）：短时间内变更过多，减小批次大小并以指数退避重试。