shopify-admin-chargeback-watchlist-tagger

用途

该技能扫描历史订单中关联的拒付或争议记录，然后为客户记录打上标签（默认 chargeback-history，可配置）。来自这些客户的未来订单可被筛选或暂扣以进行人工审核，从而减少重复拒付损失，同时不会直接封禁客户。默认 dry_run: true。

主要能力

按指定回溯窗口（默认 730 天）查询存在争议的订单。
按客户汇总争议，跳过已带标签的客户。
默认排除胜诉（WON）争议，避免误伤。
通过 customerUpdate 为客户追加标签。
输出 CSV 报告，包含客户 ID、邮箱、姓名、争议数量、最新争议状态、争议金额、现有标签、待应用标签及动作。
支持 human 与 json 两种输出格式。

使用方式

前置条件：已认证的 Shopify CLI 会话，命令为 shopify store auth --store <domain> --scopes read_orders,read_customers,write_customers；API 权限范围：read_orders、read_customers、write_customers。

参数：

store（字符串，必填）：店铺域名，例如 mystore.myshopify.com。
days_back（整数，可选，默认 730）：扫描争议的历史窗口。
watchlist_tag（字符串，可选，默认 chargeback-history）：应用于被标记客户的标签。
include_won_disputes（布尔，可选，默认 false）：若为 false，仅标记争议结果为败诉或仍开放的客户。
dry_run（布尔，可选，默认 true）：预览而不实际应用标签。
format（字符串，可选，默认 human）：输出格式 human 或 json。

工作流程：先通过 orders 查询（query: "created_at:>='<NOW - days_back days>' chargeback_status:*"，first: 250）获取窗口内至少有一个争议的订单；按客户分组争议，跳过全部为 WON 且 include_won_disputes 为 false 的客户，跳过已带 watchlist_tag 的客户，其余加入打标队列；再对队列中每个客户执行 customerUpdate 变更，追加标签。若 dry_run 为 true，则不调用变更，仅报告队列。

GraphQL 操作（已针对 api_version 2025-01 验证）：

# orders:query
query OrdersWithDisputes($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        disputes {
          id
          status
          initiatedAs
          finalizedOn
        }
        customer {
          id
          displayName
          defaultEmailAddress {
            emailAddress
          }
          numberOfOrders
          amountSpent {
            amount
            currencyCode
          }
          tags
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# customerUpdate:mutation
mutation TagChargebackCustomer($input: CustomerInput!) {
  customerUpdate(input: $input) {
    customer {
      id
      tags
    }
    userErrors {
      field
      message
    }
  }
}

会话跟踪：技能在开始、每步之后及完成时输出固定格式的进度信息；若 dry_run 为 true，每个变更步骤前加 [DRY RUN] 前缀且不执行。

输出格式：CSV 文件 chargeback_watchlist_<YYYY-MM-DD>.csv，列包括 customer_id, email, name, dispute_count, latest_dispute_status, latest_dispute_initiated_as, total_disputed_amount, currency, existing_tags, tag_to_apply, action。

适用场景

识别有拒付历史的客户，为后续订单设置人工审核或暂扣规则。
结合 Shopify Flow 或订单路由规则，对带标签客户的新订单进行人工审批。
定期（如每季度）重跑以保持观察名单最新。

限制与安全

customerUpdate 会修改对员工可见且可能驱动分群规则的客户标签；错误打标可能降低客户体验或阻止其订单。建议先以 dry_run: true 运行并审核列表。
默认排除胜诉争议以避免误报。
访客结账的争议无法打标，会在 CSV 中记录为 action: skipped_guest。
状态为 null 的争议（非常新、尚未分类）按开放/非胜诉处理。
遇到 THROTTLED 错误时等待 2 秒并最多重试 3 次；customerUpdate 出现 userErrors（客户不存在或已归档）时记录错误、跳过并继续。
对于多次争议的重复违规者，建议在允许进一步订单前进行人工审核，而非仅依赖标签。

技能介绍

用途

主要能力

使用方式

适用场景

限制与安全