checkout-abandonment-report

用途

该技能聚合放弃结账数据，并按购物车金额区间（cart value bucket）与一天中的小时（UTC）进行拆分统计。其目的在于帮助识别顾客在什么时段、什么价格点最有可能放弃结账。统计范围限定为 abandonedCheckouts API 所提供的数据：该 API 不提供设备类型和地理位置，因此本技能不报告这两项。该技能可替代 Littledata 或 Google Analytics 等分析应用的结账漏斗报告，用于购物车金额与时段维度分析。

前置条件

已通过认证的 Shopify CLI 会话：shopify auth login --store <domain>
API 权限范围（scope）：read_checkouts

参数

参数	类型	必填	默认值	说明
store	string	是	—	商店域名（例如 mystore.myshopify.com）
format	string	否	human	输出格式：human 或 json
dry_run	bool	否	false	预览操作而不执行变更
date_range_start	string	是	—	起始日期，ISO 8601 格式（例如 2025-01-01）
date_range_end	string	是	—	结束日期，ISO 8601 格式（例如 2025-01-31）
cart_value_buckets	array	否	[0, 25, 50, 100, 250]	定义购物车金额区间的阈值数组（例如 [0,25,50,100,250] 生成区间：$0–25、$25–50、$50–100、$100–250、$250+）

工作流程步骤

OPERATION：abandonedCheckouts — query

输入：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 — validated against 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 {
          email
        }
        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：按购物车金额区间的放弃情况

Cart Value Range	Abandoned Checkouts	% of Total
$0 – $25	...	...
$25 – $50	...	...
$50 – $100	...	...
$100 – $250	...	...
$250+	...	...

表 2：按一天中的小时（UTC）的放弃情况

Hour (UTC)	Abandoned Checkouts	% of Total
00:00	...	...
01:00	...	...
02:00	...	...
...

对于 format: json，by_cart_value 是 {range, count, pct} 对象数组；by_hour_utc 是 {hour, count, pct} 对象数组。

注意：abandonedCheckouts API 不提供设备类型和地理位置，本技能不报告这两项。

错误处理

错误	原因	恢复方式
No checkouts returned	日期范围内没有放弃结账	扩大日期范围或验证 read_checkouts 权限
Invalid date format	日期不是 ISO 8601 格式	使用 YYYY-MM-DD 格式
Rate limit (429)	分页请求过多	缩小日期范围或将 first 减少到 100

最佳实践

对于高流量商店，将日期范围缩小到 7–14 天可获得更快结果；对 90 天数据分页可能会产生大量 API 调用。
默认的 cart_value_buckets [0,25,50,100,250] 适用于大多数商店——可根据你的 AOV 分布调整阈值。
小时以 UTC 报告——在得出关于放弃高峰时段的结论之前，先转换为商店的本地时区。
每周运行此报告，并将 by-hour 模式与你的促销发送时间进行比较，以发现时机机会。
查询结果中包含 email——可结合 abandoned-cart-recovery 技能，根据购物车金额层级对最有可能转化的客户采取行动。