用途
聚合指定时间范围内的弃单数据，按购物车金额区间和一天中的小时（UTC）分组统计，帮助识别客户最可能在什么时间、什么价格点放弃结账。范围限于 abandonedCheckouts API 所提供的数据——设备类型和地理位置在该 API 中不可用，因此不报告。
前置条件
已认证的 Shopify CLI 会话：shopify auth login --store <domain>
API 权限范围：read_checkouts
参数
store：字符串，必填，无默认值，店铺域名（例如 mystore.myshopify.com）
format：字符串，可选，默认 human，输出格式：human 或 json
dry_run：布尔值，可选，默认 false，预览操作而不执行变更
date_range_start：字符串，必填，无默认值，ISO 8601 格式的开始日期（例如 2025-01-01）
date_range_end：字符串，必填，无默认值，ISO 8601 格式的结束日期（例如 2025-01-31）
cart_value_buckets：数组，可选，默认 [0, 25, 50, 100, 250]，定义购物车金额分段的阈值数组（例如 [0,25,50,100,250] 生成区间：$0–25、$25–50、$50–100、$100–250、$250+）
工作流程步骤
操作：abandonedCheckouts — 查询 输入：first: 250，query: "created_at:>='<date_range_start>' created_at:<='<date_range_end>'"，分页游标 预期输出：范围内所有弃单及其 totalPrice 和 createdAt；分页直到 hasNextPage: false；然后在内存中聚合：(1) 按购物车金额区间计数，(2) 按一天中的小时（UTC，0–23）计数
GraphQL 操作
abandonedCheckouts:query — 已针对 api_version 2025-04 验证
query AbandonedCheckoutsReport($first: Int!, $after: String, $query: String) { abandonedCheckouts(first: $first, after: $after, query: $query) { edges { node { id createdAt totalPriceSet { shopMoney { amount currencyCode } } customer { defaultEmailAddress { emailAddress } } lineItems { edges { node { title quantity variant { price } } } } } } pageInfo { hasNextPage endCursor } } }
会话跟踪
Claude 必须在每个阶段输出以下内容。这是强制性的。
开始时输出：
╔══════════════════════════════════════════════╗ ║ SKILL: checkout-abandonment-report ║ ║ 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 Total abandoned: <n> Date range: <start> to <end> Errors: 0 Output: none ══════════════════════════════════════════════
对于 format: json，输出：
{ "skill": "checkout-abandonment-report", "store": "<domain>", "started_at": "<ISO8601>", "completed_at": "<ISO8601>", "dry_run": false, "steps": [ { "step": 1, "operation": "AbandonedCheckoutsReport", "type": "query", "params_summary": "<date_range_start> to <date_range_end>", "result_summary": "<n> checkouts", "skipped": false } ], "outcome": { "total_abandoned": 0, "date_range_start": "<date_range_start>", "date_range_end": "<date_range_end>", "by_cart_value": [ { "range": "$0 – $25", "count": 0, "pct": 0.0 } ], "by_hour_utc": [ { "hour": "00:00", "count": 0, "pct": 0.0 } ], "errors": 0, "output_file": null } }
输出格式
内联显示两个表格（无 CSV）：
表 1：按购物车金额区间的弃单
购物车金额范围 | 弃单数 | 占总数的百分比
$0 – $25 | ... | ...
$25 – $50 | ... | ...
$50 – $100 | ... | ...
$100 – $250 | ... | ...
$250+ | ... | ...
表 2：按一天中的小时（UTC）的弃单
小时（UTC） | 弃单数 | 占总数的百分比
00:00 | ... | ...
01:00 | ... | ...
02:00 | ... | ...
...
对于 format: json，by_cart_value 是 {range, count, pct} 对象的数组；by_hour_utc 是 {hour, count, pct} 对象的数组。
注意：设备类型和地理位置在 abandonedCheckouts API 中不可用，本技能不报告这些内容。
错误处理
错误 | 原因 | 恢复方式
未返回弃单 | 日期范围内没有弃单 | 扩大日期范围或验证 read_checkouts 权限
日期格式无效 | 日期不是 ISO 8601 格式 | 使用 YYYY-MM-DD 格式
速率限制（429） | 分页请求过多 | 缩小日期范围或将 first 减少到 100
最佳实践
对于高流量店铺，将日期范围缩小到 7–14 天以获得更快结果；分页 90 天的数据可能产生大量 API 调用。
默认的 cart_value_buckets [0,25,50,100,250] 适用于大多数店铺——调整阈值以匹配你的 AOV 分布。
小时以 UTC 报告——在得出关于弃单高峰时间的结论之前，转换为店铺的本地时区。
每周运行此报告，并将按小时模式与你的促销发送时间进行比较，以发现时机机会。
查询结果中包含 email——结合 abandoned-cart-recovery 技能，根据购物车金额层级对最有可能转化的客户采取行动。