用途 customer-cohort-analysis 用于按顾客首次购买的月份进行分组，并追踪每个群组随时间推移的表现：多少人发生回购、下了多少订单、在后续月份为商家带来多少收入。群组分析是衡量留存率以及订阅或忠诚度计划健康度的常用方法。该技能为只读，不执行任何变更。
主要能力
- 按首次购买月份将客户划分为不同群组（cohort）。
- 对每个群组计算：回购顾客数、回购率、总收入、人均收入，并按月份偏移（month_offset）展开。
- 可配置分析的群组月数（cohort_months，默认 6）与每个群组获取后追踪的月数（follow_months，默认 3）。
- 输出 CSV 文件 cohort_analysis_<YYYY-MM-DD>.csv，列包括 cohort_month、customers_acquired、repeat_purchasers、repeat_rate_pct、total_revenue、revenue_per_customer、month_offset。
- 支持 human 与 json 两种输出格式。
使用方式 前置条件为已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_customers,read_orders。所需 API 权限范围为 read_customers、read_orders。
参数：
- store（字符串，必填）：商店域名，例如 mystore.myshopify.com。
- cohort_months（整数，可选，默认 6）：要分析的群组月数。
- follow_months（整数，可选，默认 3）：每个群组获取后追踪的月数。
- format（字符串，可选，默认 human）：输出格式 human 或 json。
工作流步骤：
- OPERATION: customers — 查询，输入 query 为 created_at 在群组窗口内的客户，first: 250，选取 id、createdAt、numberOfOrders 及分页游标，得到群组窗口内获取的客户。
- OPERATION: orders — 查询，输入 query 覆盖群组窗口加追踪月数的订单，first: 250，选取 customer { id }、createdAt、totalPriceSet 及分页游标，得到用于构建每位客户购买时间线的全部订单。
- 按首次订单月份对客户归组；对每个群组计算第 1、2、3 个月及以后月份的回购率与总收入。
GraphQL 操作为 customers:query 与 orders:query，均针对 api_version 2025-01 校验，查询分别返回 customers 与 orders 的分页结果，字段包括 id、createdAt、numberOfOrders、amountSpent、defaultEmailAddress 以及订单的 totalPriceSet、customer。
安全 该技能为只读，不执行任何变更，可随时安全运行。
适用场景
- 衡量电商商家的留存率与顾客复购行为。
- 评估订阅或忠诚度计划的健康度。
- 结合 customer-spend-tier-tagger：高回购群组的客户可作为升级 Gold/Platinum 等级的候选。
最佳实践
- 健康的电商业务通常在首月客户的 90 天内出现 20%–40% 的回购，可作为基准参考。
- 近期群组回购率下降可能意味着产品质量问题、客户体验摩擦或竞争加剧。
- 对订阅型业务，若回购窗口较长，可使用 follow_months: 6。
限制与错误处理
- THROTTLED：超出 API 速率限制，等待 2 秒后重试，最多 3 次。
- Insufficient history：商店新于群组窗口时，仅分析可用月份。
- Guest checkout orders：无客户记录的访客结账订单，从群组追踪中排除。
- 其他未在资料中说明的功能、收费、价格或平台支持情况暂未提供。