shopify-admin-abandoned-cart-recovery

用途

该技能用于识别已发起结账但未完成购买的客户，为每位客户生成唯一折扣码，并在 Shopify 中为其打标签，以便在后续营销活动中定向触达。它处理 Shopify 原生数据层（查询、折扣、打标签）；实际发送邮件需要外部工具完成。

主要能力

• 查询最近 N 天内被放弃的结账记录（abandonedCheckouts）。
• 为每位符合条件的客户生成唯一折扣码（discountCodeBulkCreate）。
• 为客户打标签（tagsAdd），便于再营销。
• 支持 dry_run 预览，不执行变更即可核对符合条件的客户数量。
• 支持按最低购物车金额过滤、自定义折扣比例、代码前缀与标签。
• 输出 CSV 文件 recovery_list_<YYYY-MM-DD>.csv，列为 customer_email, cart_total, abandoned_at, discount_code, discount_pct, tag_applied。
• 支持 human 与 json 两种输出格式，并在各阶段输出会话跟踪信息。

前置条件

• 已认证的 Shopify CLI 会话：shopify auth login --store <domain>
• API 权限范围：read_checkouts, write_price_rules, write_discount_codes, write_customers

参数

• store（string，必填）：店铺域名（例如 mystore.myshopify.com）。
• format（string，可选，默认 human）：输出格式，human 或 json。
• dry_run（bool，可选，默认 false）：预览操作而不执行变更。
• days_back（integer，可选，默认 7）：放弃结账的回溯窗口。
• min_cart_value（float，可选，默认 0）：纳入的最低购物车总额（USD）。
• discount_pct（integer，可选，默认 10）：为每位客户创建的折扣百分比。
• code_prefix（string，可选，默认 RECOVER）：生成折扣码的前缀。
• tag（string，可选，默认 cart-recovery）：应用于符合条件客户的标签。

使用方式

工作流包含三个步骤：

1. OPERATION: abandonedCheckouts — query。输入 first: 250、query: "created_at:>='<NOW - days_back days>'"、分页游标。预期输出为包含 email、totalPrice、createdAt、lineItems 的结账对象列表；分页直到 hasNextPage: false。
2. OPERATION: discountCodeBulkCreate — mutation。对每个符合条件的客户邮箱：唯一代码 {code_prefix}-{UUID[:8].toUpperCase()}、百分比折扣 discount_pct、使用次数限制 1、有效期 30 天。预期输出为代码创建确认（含 code 与 priceRule.id）；收集 userErrors。
3. OPERATION: tagsAdd — mutation。输入客户 id（通过结账邮箱查找）与 tag 参数中的标签字符串。预期输出为更新后的客户标签；收集 userErrors。

技能在各阶段输出会话跟踪信息：开始时输出技能名称、店铺域名与开始时间；每步之后输出步骤编号、操作类型与名称、参数摘要与结果；dry_run 为 true 时，每个变更步骤前加 [DRY RUN] 前缀且不执行；完成时按 human 或 json 格式输出结果摘要。

适用场景

• 针对放弃购物车的客户开展折扣召回活动。
• 按购物车金额筛选高价值客户，集中召回资源。
• 为每次活动打上唯一标签，区分不同批次的定向客户，避免重复触达。

限制与安全

• 步骤 2 和 3 会执行变更（创建折扣码、为客户打标签）。通过 discountCodeBulkCreate 创建的折扣码无法通过 Admin API 批量删除，必须逐个删除或通过 price rule 删除。建议先以 dry_run: true 运行，确认符合条件的客户数量后再提交。
• 该技能只产出数据层，需使用 Shopify Email 或其他邮件工具将生成的折扣码发送给客户。
• 错误处理：THROTTLED（API 速率超限）等待 2 秒并最多重试 3 次；折扣创建 userErrors（无效 price rule 或重复代码）记录错误、跳过该客户并继续；tagsAdd userErrors（客户 ID 未找到）记录错误、跳过标签并继续；结账无邮箱（无邮箱的访客结账）跳过该结账，不计为符合条件。
• 最佳实践：先以 dry_run: true 运行确认符合条件客户数量；设置 min_cart_value 聚焦高价值购物车（例如 50 表示 $50 以上）；每次运行使用唯一标签（例如 cart-recovery-2026-04-11）以识别本次定向的客户并避免后续重复触达；code_prefix 应对在 Shopify Admin 中审核折扣码的运营人员有意义（例如 CART10 表示 10% 购物车召回折扣）。