用途
该技能用于评估每个折扣码和自动折扣的真实投资回报。它通过衡量折扣产生的收入、订单数量、使用折扣与不使用折扣时的平均订单价值、归因于折扣的客户获取，以及折扣订单是否蚕食了全价销售，来回答“这个折扣是否值得”的问题。它不同于 discount-hygiene-cleanup（后者用于发现失效或未使用的折扣码）。该技能为只读操作，不执行任何数据变更。
前置条件
需要已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_orders,read_discounts
所需 API 权限：read_orders、read_discounts
参数
store：字符串，必填，无默认值，店铺域名。
days_back：整数，可选，默认 90，回溯窗口。
min_uses：整数，可选，默认 3，折扣被分析所需的最低使用次数。
format：字符串，可选，默认 human，输出格式为 human 或 json。
安全性
该技能为只读技能，不执行任何变更，可随时安全运行。
工作流程
-
OPERATION: discountNodes — 查询。输入：first: 250，选择折扣详情（标题、代码、类型、价值、usageCount、startsAt、endsAt），分页游标。预期输出：所有折扣码和自动折扣。
-
筛选 usageCount >= min_uses 且在回溯窗口内有效的折扣。
-
OPERATION: orders — 查询。输入：query: "created_at:>='<NOW - days_back days>' discount_code:<code>"，对每个有效折扣码使用 first: 250，选择 totalPriceSet、totalDiscountsSet、subtotalPriceSet、customer { id, numberOfOrders }，分页游标。预期输出：使用每个折扣的所有订单。同时查询同一时间段内没有任何折扣的订单，作为基准 AOV 对比。
-
对每个折扣计算：
Total Discount Cost = Σ(使用该代码订单的 totalDiscountsSet)
Revenue Generated = Σ(使用该代码订单的 totalPriceSet)
Discounted AOV = 收入 / 订单数
Baseline AOV = 同一时间段非折扣订单的 AOV
AOV Lift/Drop = 折扣后 AOV - 基准 AOV
New Customer % = customer.numberOfOrders == 1 的订单数 / 总订单数
Gross ROI = (收入 - 折扣成本) / 折扣成本 × 100
Cannibalization Risk = 若折扣后 AOV < 基准 AOV 且新客百分比 < 20%，则风险为高
GraphQL 操作
discountNodes:query — 已针对 api_version 2025-01 验证
query AllDiscounts($after: String) { discountNodes(first: 250, after: $after) { edges { node { id discount { ... on DiscountCodeBasic { title codes(first: 1) { edges { node { code } } } usageLimit asyncUsageCount startsAt endsAt customerGets { value { ... on DiscountPercentage { percentage } ... on DiscountAmount { amount { amount currencyCode } } } } } ... on DiscountCodeFreeShipping { title codes(first: 1) { edges { node { code } } } asyncUsageCount startsAt endsAt } ... on DiscountAutomaticBasic { title asyncUsageCount startsAt endsAt customerGets { value { ... on DiscountPercentage { percentage } ... on DiscountAmount { amount { amount currencyCode } } } } } } } } pageInfo { hasNextPage endCursor } } }
orders:query — 已针对 api_version 2025-01 验证
query OrdersByDiscount($query: String!, $after: String) { orders(first: 250, after: $after, query: $query) { edges { node { id name createdAt totalPriceSet { shopMoney { amount currencyCode } } totalDiscountsSet { shopMoney { amount currencyCode } } subtotalPriceSet { shopMoney { amount currencyCode } } customer { id numberOfOrders } discountCodes } } pageInfo { hasNextPage endCursor } } }
会话跟踪
Claude 必须在每个阶段输出以下内容。这是强制性的。
开始时输出：
╔══════════════════════════════════════════════╗ ║ SKILL: Discount ROI Calculator ║ ║ 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（默认）时：
══════════════════════════════════════════════ DISCOUNT ROI REPORT (<days_back> days) Discounts analyzed: <n> Total discount spend: $<amount> Total attributed rev: $<amount> ───────────────────────────── TOP PERFORMERS (by ROI): "<code>" ROI: <n>% Revenue: $<n> Cost: $<n> New customers: <pct>%
UNDERPERFORMERS: "<code>" ROI: <n>% Revenue: $<n> Cost: $<n> ⚠️ Cannibalization risk
BASELINE COMPARISON: Non-discount AOV: $<n> | Avg discount AOV: $<n> | Δ: $<n>
Output: discount_roi_<date>.csv ══════════════════════════════════════════════
输出格式
CSV 文件 discount_roi_<YYYY-MM-DD>.csv，包含列：discount_id、code_or_title、type、uses、revenue、discount_cost、roi_pct、aov、baseline_aov、aov_delta、new_customer_pct、cannibalization_risk
错误处理
THROTTLED：API 速率限制超出，等待 2 秒后重试，最多 3 次。
自动折扣：没有可供查询的代码，通过订单折扣数据进行匹配。
叠加折扣：一个订单包含多个代码，按比例归因或标记为 "multi-discount"。
最佳实践
ROI < 100% 的折扣成本高于其产生的收益，可考虑停用。
高 New Customer % 且 ROI 为正，是很好的获客工具，可继续运行。
低 New Customer % 且 AOV 提升为负，存在蚕食风险，客户本来也会购买。
可与 discount-ab-analysis 交叉参考以获得拆分测试洞察。
与 discount-hygiene-cleanup 配合使用，发现并移除表现不佳的代码。