用途
该技能按可配置的时间桶（日、周、月）计算平均订单价值（AOV），并按新客户与回头客对结果进行分组。它通过追踪 AOV 趋势，帮助衡量追加销售计划、捆绑优惠或免运费门槛调整等措施带来的影响。技能为只读模式，不执行任何数据变更操作。
前置条件
需要已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_orders,read_customers
所需 API 权限范围：read_orders, read_customers
参数
参数 | 类型 | 必填 | 默认值 | 说明
store | string | 是 | — | 店铺域名（例如 mystore.myshopify.com）
days_back | integer | 否 | 90 | 总回溯窗口天数
bucket | string | 否 | week | 时间桶：day、week 或 month
format | string | 否 | human | 输出格式：human 或 json
安全性
ℹ️ 只读技能——不执行任何变更操作，可随时安全运行。
工作流步骤
操作：orders — 查询 输入：query: "created_at:>='<NOW - days_back days>'", first: 250, select totalPriceSet, customer { id, numberOfOrders }, createdAt, 分页游标 预期输出：窗口内所有订单；分页直到 hasNextPage: false
对每个订单进行分类：如果 customer.numberOfOrders == 1 → 新客户订单；否则 → 回头客订单
操作：customers — 查询（可选的队列上下文补充） 输入：近期客户，用于验证新客户与回头客的分组
按时间桶对订单分组；计算每个时间桶及每个客户分组的 AOV
GraphQL 操作
orders:query — 已针对 api_version 2025-01 验证
query AOVData($query: String!, $after: String) { orders(first: 250, after: $after, query: $query) { edges { node { id name createdAt totalPriceSet { shopMoney { amount currencyCode } } customer { id numberOfOrders } } } pageInfo { hasNextPage endCursor } } }
customers:query — 已针对 api_version 2025-01 验证
query NewVsReturningCustomers($query: String!, $after: String) { customers(first: 250, after: $after, query: $query) { edges { node { id numberOfOrders createdAt } } pageInfo { hasNextPage endCursor } } }
会话追踪
Claude 必须在每个阶段输出以下内容。这是强制要求。
开始时，输出：
╔══════════════════════════════════════════════╗ ║ SKILL: Average Order Value Trends ║ ║ 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（默认）：
══════════════════════════════════════════════ AOV TRENDS (<days_back> days, bucket: <bucket>) Orders analyzed: <n> Overall AOV: $<amount> New customer AOV: $<amount> Returning AOV: $<amount>
Period Orders AOV New AOV Returning AOV ──────────────────────────────────────────────────── 2026-W14 <n> $<n> $<n> $<n> Output: aov_trends_<date>.csv ══════════════════════════════════════════════
对于 format: json，输出：
{ "skill": "average-order-value-trends", "store": "<domain>", "period_days": 90, "overall_aov": 0, "new_customer_aov": 0, "returning_customer_aov": 0, "by_period": [], "output_file": "aov_trends_<date>.csv" }
输出格式
CSV 文件 aov_trends_<YYYY-MM-DD>.csv，包含以下列：period, order_count, aov, new_customer_orders, new_customer_aov, returning_orders, returning_aov, currency
错误处理
错误 | 原因 | 恢复方式
THROTTLED | 超出 API 速率限制 | 等待 2 秒，最多重试 3 次
游客结账订单 | 无客户记录 | 计入总数，但不参与新客户/回头客分组
窗口内无订单 | 新店铺或淡季 | 以 0 AOV 退出
最佳实践
免运费门槛提高或捆绑销售推出，应在发布的当周/当月表现为 AOV 提升——使用此报告来衡量影响。
回头客 AOV 通常高于新客户——差距缩小可能表明忠诚度下降。
bucket: week 最适合衡量活动效果；bucket: month 适合追踪长期趋势。
游客结账订单无法按新客户与回头客分组——对于游客结账率较高的店铺，分组会低估新客户数量。