SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场shopify-admin-customer-merge

shopify-admin-customer-merge

办公与效率

查看项目

更新于 10-15 10:43

技能介绍

用途

该技能用于解决由 duplicate-customer-finder 识别出的重复客户记录。当 Shopify Admin API 提供 customerMerge（原生合并，可将订单、地址、订阅和元字段迁移到胜者记录）时，直接调用它。当 customerMerge 对给定账户对不可用或失败时，回退到通过 customerUpdate 将可搜索的元数据（标签、备注、营销同意）整合到胜者记录上，然后在败者记录上写入清晰的标注，方便员工在 Shopify 后台手动完成合并。

前提条件

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

参数

  • store（string，必填）：店铺域名，例如 mystore.myshopify.com
  • format（string，可选，默认 human）：输出格式，human 或 json
  • dry_run（bool，可选，默认 true）：仅预览合并计划，不执行变更
  • customer_winner_id（string，必填）：要保留的客户记录 GID，例如 gid://shopify/Customer/12345
  • customer_loser_id（string，必填）：要合并进胜者记录的客户记录 GID
  • use_native_merge（bool，可选，默认 true）：优先尝试 customerMerge；若失败或不可用，回退到通过 customerUpdate 整合
  • merge_tags（bool，可选，默认 true）：将败者的标签并入胜者
  • merge_note（bool，可选，默认 true）：将败者的备注追加到胜者（带时间戳前缀）
  • annotate_loser（bool，可选，默认 true）：在败者记录上写入指向胜者 GID 的备注，供手动清理

安全提示

第 2–4 步会执行修改客户记录的变更。customerMerge 不可逆——一旦订单和地址迁移到胜者，败者记录会被关闭且无法拆分回来。请先用 dry_run: true 确认胜者/败者 GID 和合并计划，默认即为 dry_run: true。提交前务必使用 duplicate-customer-finder 的输出确认两条记录属于同一自然人（邮箱、电话、姓名匹配）。不要合并有活跃订阅或未履约订单的客户，除非确认下游系统会跟随新的所有者 GID。

工作流步骤

  1. customer 查询（胜者和败者各调用一次）：输入 id、select 字段（身份、订单数、消费额、营销同意、地址等）；若任一 GID 无法解析则中止。
  2. customerMerge 变更（仅在 use_native_merge: true 且非 dry_run 时）：输入 customerOneId（胜者）、customerTwoId（败者）、overrideFields（偏好胜者的姓名/邮箱/电话/地区/营销同意）；输出 job.id（异步）和 userErrors。若 userErrors 表示该组合不支持合并（B2B、礼品卡持有人、订阅者等），进入第 3 步回退。
  3. customerUpdate 变更（胜者）——回退路径或 use_native_merge: false 时：输入胜者 id、标签并集（仅当 merge_tags）、备注追加（仅当 merge_note）。
  4. customerUpdate 变更（败者）——仅当 annotate_loser: true：写入备注指向胜者 GID，并添加 duplicate、merged-loser 标签。

GraphQL 操作

customer:query、customerMerge:mutation、customerUpdate:mutation 均已针对 api_version 2025-01 验证。

会话追踪

该技能要求在每阶段输出固定格式的会话信息：开始时输出带店铺和时间的横幅；每步后输出步骤编号、操作名、关键输入和结果；dry_run 时每个变更步骤前加 [DRY RUN] 且不执行。完成时按 format 输出人类可读汇总或 JSON。

输出格式

无 CSV 输出。会话汇总报告合并任务 ID、结果客户 GID 和所走路径。批量合并时，每对运行一次该技能并捕获 JSON 输出。

错误处理

  • THROTTLED：等待 2 秒重试，最多 3 次。
  • customerMerge userError: customer has subscriptions：败者有活跃订阅，先取消或走回退路径。
  • customerMerge userError: B2B customer：公司关联记录，走回退路径，在 Shopify 后台手动合并。
  • customerMerge userError: gift card holder：败者持有礼品卡余额，转移礼品卡或走回退路径。
  • 任一 GID 未找到：ID 错误或客户已删除，重新运行 duplicate-customer-finder。
  • 合并任务待处理：异步未完成，重新查询 Job(id) 确认 done: true。

最佳实践

  • 先运行 duplicate-customer-finder 确认确实是重复，手动误判不可恢复。
  • 谨慎选择胜者：通常选订单更多、邮箱已验证或 createdAt 更早的记录，避免让有营销同意的记录成为败者。
  • 先 dry_run: true，预览会显示两条记录的订单数和消费额，便于提交前检查。
  • 大规模去重时，编写包装脚本从 duplicate-customer-finder 的 CSV 输出逐对调用该技能，切勿在一次调用中批量合并。
  • 原生合并后 job.done: false 是正常的，Shopify 异步处理合并，需重新查询任务 ID 直到完成再认为败者已关闭。
  • 回退路径（仅 customerUpdate 整合）不迁移订单，它通过标签/备注保留可搜索性，让员工在 Shopify 后台（Customers → Merge）完成合并。