loyalty-segment-export

用途

该技能用于识别高终身价值（LTV）客户：按订单数量和终身总消费额进行筛选，在 Shopify 中为其打上标签，并导出可直接用于忠诚度计划报名或 VIP 营销活动的联系名单。它负责数据层处理；管理奖励积分或发送忠诚度邮件需要外部工具完成。

前置条件

已认证的 Shopify CLI 会话：

shopify auth login --store <domain>

API 权限范围：

read_customers, write_customers

参数

参数	类型	是否必填	默认值	说明
store	string	是	—	店铺域名
format	string	否	human	human 或 json
dry_run	bool	否	false	仅预演，不打标签
min_orders	integer	否	3	最低终身订单数
min_spend	float	否	200	最低终身消费额（店铺货币）
tag	string	否	loyalty-vip	应用到符合条件客户的标签

工作流程

操作：customers — 查询

输入：过滤条件 orders_count:>=(min_orders)、total_spent:>=(min_spend)、first: 250，并分页
预期输出：包含 id、defaultEmailAddress { emailAddress }、firstName、lastName、ordersCount、totalSpentV2 的列表；持续分页直到 hasNextPage: false

操作：tagsAdd — 变更

输入：客户 id、来自 tag 参数的标签
预期输出：逐个客户的确认结果；收集 userErrors

GraphQL 操作

# customers:query — 已对照 api_version 2025-04 验证
query LoyaltyCustomers($first: Int!, $after: String, $query: String) {
  customers(first: $first, after: $after, query: $query) {
    edges {
      node {
        id
        defaultEmailAddress {
          emailAddress
        }
        firstName
        lastName
        ordersCount
        totalSpentV2 {
          amount
          currencyCode
        }
        tags
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# tagsAdd:mutation — 已对照 api_version 2025-01 验证
mutation TagsAdd($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node { id }
    userErrors { field message }
  }
}

会话跟踪

Claude 必须在每个阶段输出以下内容。这是强制要求。

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Loyalty Segment Export               ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

每个步骤之后输出：

[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary>
          → Result: <count or outcome>

如果 dry_run: true，在变更步骤前加上 [DRY RUN] 前缀，且不执行。

完成时，若 format 为 human：

══════════════════════════════════════════════
OUTCOME SUMMARY
  VIP customers found:  <n>
  Customers tagged:     <n>
  Errors:               <n>
  Output:               loyalty_segment_<date>.csv
══════════════════════════════════════════════

若 format 为 json，则输出带有 outcome 键的标准 JSON 结构：vip_customers_found、customers_tagged、errors、output_file。

输出格式

CSV 文件 loyalty_segment_<YYYY-MM-DD>.csv，包含列：

customer_id, email, first_name, last_name, orders_count, total_spent, currency, tag_applied

错误处理

错误	原因	恢复方式
THROTTLED	触发速率限制	等待 2 秒，最多重试 3 次
tagsAdd 上的 userErrors	客户 ID 无效	记录、跳过、继续

最佳实践

运行前，检查客户是否已带有 loyalty 标签——在查询过滤条件中加上 NOT tag:loyalty-vip，以跳过已加入的客户。
如果不确定阈值，先导出并查看客户名单再打标签——使用 dry_run: true 查看数量，然后调整 min_orders 和 min_spend 后再正式执行。
与 customer-win-back 结合使用：为高 LTV 的流失客户同时打上 loyalty-vip 和 win-back 标签，以识别优先级最高的再互动目标。

限制

该技能只处理数据层，管理奖励积分或发送忠诚度邮件需要外部工具。