repeat-purchase-rate

用途

repeat-purchase-rate 是一个面向 Shopify 店铺的只读分析技能，用于计算重复购买率：即在首次购买后的指定时间窗口内，至少再次下单一次的客户占比。该技能还可以按首次购买的商品或商品系列对复购率进行细分，帮助识别哪些商品能驱动最高的复购行为。整个技能为只读，不执行任何数据变更操作。

前置条件

需要已认证的 Shopify CLI 会话：

shopify store auth --store <domain> --scopes read_customers,read_orders

API 权限范围：read_customers、read_orders。

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
days_back	integer	否	90	获取窗口——在此时间段内首次购买的客户
repeat_window	integer	否	90	首次购买后用于查找复购订单的天数
segment_by	string	否	none	按 product 或 none 细分复购率
format	string	否	human	输出格式：human 或 json

安全性

该技能为只读技能，不执行任何变更操作，可随时安全运行。

工作流程

查询获取窗口内新增的客户：

query AdminAcquiredCustomers($query: String!, $after: String) {
  customers(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        createdAt
        numberOfOrders
        defaultEmailAddress {
          emailAddress
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

输入：query: "created_at:>='<NOW - days_back days>'", first: 250, 选取 id、numberOfOrders、createdAt。预期输出：窗口内获取的客户。

查询订单以构建每位客户的购买历史和首购商品映射：

query CustomerOrderHistory($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        createdAt
        customer {
          id
        }
        lineItems(first: 5) {
          edges {
            node {
              product {
                id
                title
              }
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

输入：query: "created_at:>='<NOW - days_back + repeat_window days>'", first: 250, 选取 customer { id }、createdAt、lineItems { product { id, title } }、分页游标。预期输出：用于构建每位客户购买历史和首购商品映射的订单。

对每个获取的客户：若在 repeat_window 天内订单数达到 2 笔或以上，则计为复购客户。
计算整体复购率；若 segment_by 为 product，则按首购商品分组统计。

以上 GraphQL 操作均已对照 api_version 2025-01 验证。

会话跟踪

在每个阶段必须输出会话跟踪信息。开始时输出技能名称、店铺域名和开始时间；每一步之后输出操作类型、操作名称、参数摘要和结果计数；完成时按所选格式输出结果。

输出格式

人类可读格式（默认）会展示获取窗口、复购窗口、获取客户数、复购客户数、复购率，以及按首购商品分组的复购率，并生成 CSV 文件。JSON 格式则输出包含 skill、store、acquisition_days、repeat_window_days、customers_acquired、repeat_purchasers、repeat_rate_pct、by_product、output_file 等字段的对象。

CSV 文件 repeat_purchase_<YYYY-MM-DD>.csv 包含以下列：customer_id、first_order_date、first_product、total_orders、is_repeat、days_to_repeat、total_spent。

错误处理

错误	原因	恢复方式
THROTTLED	超出 API 速率限制	等待 2 秒，最多重试 3 次
Guest checkout customers	无客户记录可关联订单	从分析中排除
Insufficient history	店铺历史短于窗口	分析可用时间段

最佳实践

对于大多数非订阅制电商店铺，90 天内 25%–35% 的复购率是健康基准。
复购率高的商品是您的“入口”商品——在获客活动中优先推广。
使用 segment_by: product 来识别哪些商品能培养忠诚客户，哪些只是一次性购买。
与 customer-cohort-analysis 搭配使用，可更深入地了解长期留存趋势。