用途
该技能查询所有客户，利用订单历史计算其终身消费金额，并分配消费等级标签（默认 Bronze/Silver/Gold/Platinum）。它无需第三方忠诚度应用即可实现 VIP 分层，用于忠诚度计划、专属优惠和客户体验优先级管理。该技能在现有 loyalty-segment-export 技能基础上增加了写入步骤。
前提条件
已认证的 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+
安全性
⚠️ tagsAdd 会将标签添加到客户记录，员工可见并用于营销细分。如果 remove_old_tiers: true，则在应用新标签前会移除匹配 tag_prefix 的现有等级标签。请使用 dry_run: true 运行，在提交前查看等级分布。
工作流程步骤
操作：customers — 查询 输入：first: 250，选择 id、amountSpent、分页游标 预期输出：所有客户的终身消费；分页直到 hasNextPage: false
根据 amountSpent.amount 与 tiers 阈值，为每位客户分配等级
操作：orders — 查询（可选 — 用于验证消费金额）
操作：tagsAdd — 变更 输入：客户 id，tags: ["<tag_prefix>:<tier>"] 预期输出：更新后的客户标签；userErrors
GraphQL 操作
customers:query — 已针对 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 — 已针对 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 — 已针对 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
错误处理
错误 原因 恢复
THROTTLED API 速率限制超出 等待 2 秒，最多重试 3 次
tagsAdd 上的 userErrors 无效的客户 ID 记录错误，跳过客户，继续
无客户 空店铺 以 0 结果退出
最佳实践
每月运行以保持等级分配最新 — 消费增加的客户将自动升级。
使用 remove_old_tiers: true 确保每位客户在任何时候只有一个等级标签。
根据店铺的 AOV 和 LTV 分布调整 tiers 阈值 — 默认值适用于 AOV 为 $50–100 的店铺。
打标签后，使用标签筛选器创建 Shopify 客户细分，以便在电子邮件营销活动中定位每个等级。