用途 该技能用于识别已发起结账但未完成购买的客户，为每位客户生成一个唯一折扣码，并在 Shopify 中为其打标签，以便在后续营销活动中定向触达。它相当于邮件营销应用（如 Klaviyo、Omnisend）中弃购流程功能的替代实现——该技能只负责 Shopify 原生数据层（查询、折扣、打标签）；实际发送邮件需要借助外部工具完成。
使用前提 需要已认证的 Shopify CLI 会话：shopify auth login --store <domain> 所需 API 权限范围：read_checkouts、write_price_rules、write_discount_codes、write_customers
参数
- store（字符串，必填，无默认值）：店铺域名（例如 mystore.myshopify.com）
- format（字符串，可选，默认 human）：输出格式，human 或 json
- dry_run（布尔，可选，默认 false）：仅预览操作，不执行变更
- days_back（整数，可选，默认 7）：弃购结账的回溯时间窗口
- min_cart_value（浮点，可选，默认 0）：纳入处理的最低购物车金额（美元）
- discount_pct（整数，可选，默认 10）：为每位客户创建的折扣百分比
- code_prefix（字符串，可选，默认 RECOVER）：生成的折扣码前缀
- tag（字符串，可选，默认 cart-recovery）：应用于符合条件的客户的标签
安全提示 步骤 2 和步骤 3 会执行变更操作（创建折扣码、给客户打标签）。通过 discountCodeBulkCreate 创建的折扣码无法通过 Admin API 批量删除——必须逐个删除或通过价格规则删除。建议先用 dry_run: true 运行，确认符合条件的客户数量后再正式执行。
工作流步骤
-
OPERATION: abandonedCheckouts —— 查询 输入：first: 250，query: "created_at:>='<NOW - days_back days>'"，分页游标 预期输出：结账对象列表，包含 email、totalPrice、createdAt、lineItems；持续分页直到 hasNextPage: false
-
OPERATION: discountCodeBulkCreate —— 变更 输入：对每个符合条件的客户邮箱，生成唯一折扣码 {code_prefix}-{UUID[:8].toUpperCase()}，百分比折扣 discount_pct，使用次数上限 1，有效期 30 天 预期输出：折扣码创建确认，包含 code 和 priceRule.id；收集 userErrors
-
OPERATION: tagsAdd —— 变更 输入：客户 id（通过结账邮箱查找）、来自 tag 参数的标签字符串 预期输出：更新后的客户标签；收集 userErrors
GraphQL 操作
abandonedCheckouts:query — 已针对 api_version 2025-01 验证
query AbandonedCheckouts($first: Int!, $after: String, $query: String) { abandonedCheckouts(first: $first, after: $after, query: $query) { edges { node { id email totalPrice createdAt lineItems { edges { node { title quantity variant { price } } } } } } pageInfo { hasNextPage endCursor } } }
discountCodeBulkCreate:mutation — 已针对 api_version 2025-01 验证
mutation DiscountCodeBulkCreate($priceRuleId: ID!, $codes: [DiscountCodeInput!]!) { discountCodeBulkCreate(priceRuleId: $priceRuleId, codes: $codes) { bulkCreations { id done } userErrors { field message } } }
tagsAdd:mutation — 已针对 api_version 2025-01 验证
mutation TagsAdd($id: ID!, $tags: [String!]!) { tagsAdd(id: $id, tags: $tags) { node { id } userErrors { field message } } }
会话跟踪 Claude 必须在每个阶段输出以下内容，这是强制要求。
启动时输出： ╔══════════════════════════════════════════════╗ ║ SKILL: Abandoned Cart Recovery ║ ║ Store: <store domain> ║ ║ Started: <YYYY-MM-DD HH:MM UTC> ║ ╚══════════════════════════════════════════════╝
每一步之后输出： [N/TOTAL] <QUERY|MUTATION> <OperationName> → Params: <关键输入的简要概述> → Result: <数量或结果>
如果 dry_run: true，则每个变更步骤前加前缀 [DRY RUN]，并且不执行该步骤。
完成时输出： 当 format 为 human（默认）： ══════════════════════════════════════════════ OUTCOME SUMMARY Checkouts found: <n> Eligible customers: <n> Codes created: <n> Customers tagged: <n> Errors: <n> Output: recovery_list_<date>.csv ══════════════════════════════════════════════
当 format 为 json，输出： { "skill": "abandoned-cart-recovery", "store": "<domain>", "started_at": "<ISO8601>", "completed_at": "<ISO8601>", "dry_run": false, "steps": [ { "step": 1, "operation": "AbandonedCheckouts", "type": "query", "params_summary": "last 7 days, cart >= $0", "result_summary": "<n> checkouts", "skipped": false }, { "step": 2, "operation": "DiscountCodeBulkCreate", "type": "mutation", "params_summary": "<n> codes, 10% off, prefix RECOVER", "result_summary": "<n> created", "skipped": false }, { "step": 3, "operation": "TagsAdd", "type": "mutation", "params_summary": "tag: cart-recovery", "result_summary": "<n> customers tagged", "skipped": false } ], "outcome": { "checkouts_found": 0, "eligible_customers": 0, "codes_created": 0, "customers_tagged": 0, "errors": 0, "output_file": "recovery_list_<date>.csv" } }
输出格式 CSV 文件 recovery_list_<YYYY-MM-DD>.csv，包含列： customer_email, cart_total, abandoned_at, discount_code, discount_pct, tag_applied
错误处理
- THROTTLED：API 速率限制超限；等待 2 秒，最多重试 3 次
- 折扣创建时的 userErrors：价格规则无效或折扣码重复；记录错误，跳过该客户，继续处理
- tagsAdd 时的 userErrors：未找到客户 ID；记录错误，跳过该标签，继续处理
- 结账记录中没有邮箱：访客结账但未提供邮箱；跳过该结账，不计入符合条件
最佳实践
- 先用 dry_run: true 运行并确认符合条件的客户数量——折扣码无法通过 API 批量删除，会一直保留在价格规则中，直到手动删除。
- 设置 min_cart_value 将挽回重点放在高价值购物车上（例如 50 表示 $50 以上）。小额购物车通常挽回意愿较低，可能不值得发放折扣。
- 每次运行使用唯一标签（例如 cart-recovery-2026-04-11），这样可以准确识别每次活动中被定向的客户，避免在后续运行中重复定向。
- code_prefix 应对查阅 Shopify Admin 中折扣码的运营人员有明确含义（例如 CART10 表示 10% 的购物车挽回折扣）。
- 该技能只产出数据层。请使用 Shopify Email、Klaviyo 或其他邮件工具将生成的折扣码发送给客户。