用途
该技能通过对比不同折扣码的兑换次数与产生的营收，来评估各折扣码的表现。它适合在没有专门分析应用的情况下对促销活动进行 A/B 测试：提供两个或多个折扣码以及一个日期范围，技能会查询 Shopify 获取折扣元数据和订单营收，然后生成并排对比表格。该技能为只读操作，不执行任何变更。
前置条件
已认证的 Shopify CLI 会话：shopify auth login --store <domain>
API 权限范围：read_discounts、read_orders
参数
参数 | 类型 | 必填 | 默认值 | 说明
store | string | 是 | — | 店铺域名（例如 mystore.myshopify.com）
format | string | 否 | human | 输出格式：human 或 json
dry_run | bool | 否 | false | 预览操作而不执行变更
discount_codes | array | 是 | — | 要对比的 2 个或更多折扣码字符串数组（例如 ["SAVE10", "WELCOME15"]）
date_range_start | string | 是 | — | 开始日期，ISO 8601 格式（例如 2025-01-01）
date_range_end | string | 是 | — | 结束日期，ISO 8601 格式（例如 2025-01-31）
工作流程步骤
操作：discountNodes — 查询 输入：first: 50，query: "code:<code>"（discount_codes 中每个折扣码执行一次查询） 预期输出：每个折扣码的折扣元数据：title、code 字符串、asyncUsageCount、status、startsAt、endsAt
操作：orders — 查询（每个折扣码执行一次分页查询） 输入：first: 250，query: "discount_code:<code> created_at:>='<date_range_start>' created_at:<='<date_range_end>'"，分页游标 预期输出：包含该折扣码的订单及其 totalPriceSet；分页直到 hasNextPage: false；聚合：数量、营收总和、计算平均订单价值
GraphQL 操作
discountNodes:query — 已针对 api_version 2025-01 验证
query DiscountNodes($first: Int!, $query: String) { discountNodes(first: $first, query: $query) { edges { node { id discount { ... on DiscountCodeBasic { title codes(first: 10) { edges { node { code asyncUsageCount } } } usageLimit status startsAt endsAt } ... on DiscountCodeBxgy { title codes(first: 10) { edges { node { code asyncUsageCount } } } status } ... on DiscountCodeFreeShipping { title codes(first: 10) { edges { node { code asyncUsageCount } } } status } } } } } }
orders:query（按折扣码）— 已针对 api_version 2025-01 验证
query OrdersByDiscountCode($first: Int!, $after: String, $query: String) { orders(first: $first, after: $after, query: $query) { edges { node { id createdAt totalPriceSet { shopMoney { amount currencyCode } } discountCodes } } pageInfo { hasNextPage endCursor } } }
会话跟踪
Claude 必须在每个阶段输出以下内容。这是强制性的。
开始时，输出：
╔══════════════════════════════════════════════╗ ║ SKILL: discount-ab-analysis ║ ║ Store: <store domain> ║ ║ Started: <YYYY-MM-DD HH:MM UTC> ║ ╚══════════════════════════════════════════════╝
每个步骤之后，输出：
[N/TOTAL] <QUERY|MUTATION> <OperationName> → Params: <brief summary of key inputs> → Result: <count or outcome>
完成时，输出：
对于 format: human（默认）：
══════════════════════════════════════════════ OUTCOME SUMMARY Codes analyzed: <n> Date range: <start> to <end> Errors: 0 Output: none ══════════════════════════════════════════════
对于 format: json，输出：
{ "skill": "discount-ab-analysis", "store": "<domain>", "started_at": "<ISO8601>", "completed_at": "<ISO8601>", "dry_run": false, "steps": [ { "step": 1, "operation": "DiscountNodes", "type": "query", "params_summary": "<n> codes queried", "result_summary": "<n> discount nodes found", "skipped": false }, { "step": 2, "operation": "OrdersByDiscountCode", "type": "query", "params_summary": "date range <start> to <end>", "result_summary": "<n> orders aggregated", "skipped": false } ], "outcome": { "codes_analyzed": 0, "date_range_start": "<start>", "date_range_end": "<end>", "results": [ { "code": "SAVE10", "async_usage_count": 0, "orders_in_range": 0, "total_revenue": "0.00", "avg_order_value": "0.00", "revenue_per_use": "0.00" } ], "errors": 0, "output_file": null } }
输出格式
每个折扣码的对比表格（内联显示）：
Code | Uses (asyncUsageCount) | Orders in Range | Total Revenue | Avg Order Value | Revenue per Use
SAVE10 | ... | ... | ... | ... | ...
WELCOME15 | ... | ... | ... | ... | ...
对于 format: json，results 数组为每个折扣码包含一个对象，键为：code、async_usage_count、orders_in_range、total_revenue、avg_order_value、revenue_per_use。
错误处理
错误 | 原因 | 恢复方式
折扣码未找到 | 折扣码不存在或已被删除 | 在 Shopify 后台验证折扣码
某折扣码未返回订单 | 该日期范围内没有订单使用此折扣码 | 扩大日期范围或验证折扣码在该期间是否有效
discount_codes 少于 2 项 | 只有 1 个折扣码无法进行 A/B 测试 | 提供至少 2 个折扣码
速率限制（429） | 分页订单查询过多 | 等待并重试；缩小日期范围
最佳实践
asyncUsageCount 是折扣对象的生命周期使用次数——orders_in_range 是在你的日期窗口内兑换的次数。两者都会报告以提供完整上下文。
对于使用量高的折扣码，订单查询会进行分页——较大的日期范围可能产生大量 API 调用。考虑缩小日期范围以加快结果。
每次使用营收是用于比较不同使用量折扣码的最佳信号。
在活动周期结束时运行此分析，然后再决定重复哪种折扣策略。
如果某个折扣码的 asyncUsageCount 为 0，请检查该折扣码在日期范围内是否有效并在结账时正确应用。