customer-spend-tier-tagger

用途

该技能查询 Shopify 店铺中的所有客户，利用订单历史计算每位客户的终身消费金额，并为其分配消费层级标签（默认 Bronze/Silver/Gold/Platinum）。它帮助商家在不依赖第三方忠诚度应用的情况下实现 VIP 客户分群，用于忠诚度计划、专属优惠和客户体验优先级排序。该技能在已有的 loyalty-segment-export 技能基础上增加了写入步骤。

主要能力

查询所有客户及其终身消费金额（amountSpent）和订单数量。
根据可配置的消费阈值将客户划分为不同层级。
通过 tagsAdd 变更操作为客户添加层级标签。
支持自定义标签前缀（默认 tier，例如 tier:bronze）。
支持在应用新标签前移除匹配前缀的旧层级标签（remove_old_tiers，默认 true）。
支持 dry_run 预览模式（默认 true），在不执行变更的情况下查看层级分布。
输出人类可读或 JSON 格式的结果摘要。
生成 CSV 文件，包含客户 ID、姓名、邮箱、终身消费、货币、层级、旧标签和新标签。

使用方式

前置条件

已认证的 Shopify CLI 会话：

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

API 权限范围：read_customers、read_orders、write_customers。

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
tiers	object	否	见下方	各层级的消费阈值（以店铺货币计）
tag_prefix	string	否	tier	标签前缀（例如 tier:bronze、tier:silver）
remove_old_tiers	bool	否	true	应用新标签前移除已有的层级标签
dry_run	bool	否	true	预览而不执行变更
format	string	否	human	输出格式：human 或 json

默认层级（店铺货币）：

bronze: $0–$249
silver: $250–$999
gold: $1,000–$4,999
platinum: $5,000+

工作流程

查询客户（customers:query）：每次获取 250 条，选择 id、amountSpent、分页游标，直到 hasNextPage 为 false。
根据 amountSpent.amount 与 tiers 阈值比较，为每位客户分配层级。
可选：查询订单（orders:query）以验证消费数据。
执行 tagsAdd 变更：输入客户 id 和标签 ["<tag_prefix>:<tier>"]，输出更新后的客户标签及 userErrors。

GraphQL 操作

# customers:query — validated against api_version 2025-01
query CustomerSpendLevels($after: String) {
  customers(first: 250, after: $after) {
    edges {
      node {
        id
        displayName
        defaultEmailAddress {
          emailAddress
        }
        amountSpent {
          amount
          currencyCode
        }
        numberOfOrders
        tags
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# orders:query — validated against api_version 2025-01
query CustomerOrderHistory($customerId: String!, $after: String) {
  orders(first: 250, after: $after, query: $customerId) {
    edges {
      node {
        id
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# tagsAdd:mutation — validated against api_version 2025-01
mutation TagsAdd($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      field
      message
    }
  }
}

会话跟踪

Claude 必须在每个阶段输出以下内容（强制要求）：

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Customer Spend Tier Tagger           ║
║  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>

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

完成时输出：

format: human（默认）：

══════════════════════════════════════════════
OUTCOME SUMMARY
  Customers processed:  <n>
  Bronze:    <n>  (<pct>%)
  Silver:    <n>  (<pct>%)
  Gold:      <n>  (<pct>%)
  Platinum:  <n>  (<pct>%)
  Tags applied: <n>
  Errors:       <n>
  Output:       tier_tagging_<date>.csv
══════════════════════════════════════════════

format: json：

{
  "skill": "customer-spend-tier-tagger",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "dry_run": true,
  "tier_distribution": { "bronze": 0, "silver": 0, "gold": 0, "platinum": 0 },
  "tags_applied": 0,
  "errors": 0,
  "output_file": "tier_tagging_<date>.csv"
}

输出格式

CSV 文件 tier_tagging_<YYYY-MM-DD>.csv，列包括： customer_id, name, email, lifetime_spend, currency, tier, previous_tags, new_tags

适用场景

为忠诚度计划建立 VIP 客户分群。
向不同消费层级客户发送专属优惠。
根据消费层级优先处理客户体验。
定期（如每月）更新客户层级，使消费增加的客户自动升级。
在打标签后，使用 Shopify Customer Segments 按标签筛选，针对各层级进行邮件营销。

限制与安全注意事项

⚠️ tagsAdd 会向客户记录添加标签，这些标签对员工可见并被营销分群使用。如果 remove_old_tiers: true，匹配 tag_prefix 的现有层级标签会在应用新标签前被移除。建议先以 dry_run: true 运行，审查层级分布后再提交。
需要有效的 Shopify CLI 认证会话和相应 API 权限。
默认阈值适用于平均客单价（AOV）在 $50–100 的店铺，需根据自身店铺的 AOV 和 LTV 分布调整。
错误处理：THROTTLED（API 速率限制）等待 2 秒重试最多 3 次；tagsAdd 的 userErrors（无效客户 ID）记录错误并跳过该客户继续；无客户（空店铺）以 0 结果退出。
该技能的具体收费、价格、平台兼容性等未在资料中提供。