shopify-admin-return-reason-analysis

用途

该技能用于查询指定日期窗口内的所有退货请求，并按退货原因代码、产品和 SKU 进行聚合。它能够揭示哪些产品的退货率最高，以及哪些退货原因（如尺码错误、损坏、与描述不符等）最为常见。该技能为只读操作，不会执行任何变更。

主要能力

在指定时间窗口内查询退货请求，支持分页获取全部数据。
按退货原因、产品、SKU 三个维度聚合退货数据。
计算每个聚合桶的退货数量和占总退货量的百分比。
查询同期订单总数，作为计算退货率的分母。
输出退货原因分析摘要，包括总退货数、总订单数、退货率、热门退货原因和退货量最高的产品。
生成 CSV 文件，包含退货 ID、订单名称、产品标题、SKU、数量、退货原因、原因备注和创建时间。
支持 human 和 json 两种输出格式。

使用方式

前置条件

已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_orders,read_returns
API 权限范围：read_orders、read_returns

参数

参数	类型	必填	默认值	说明
store	string	是	—	商店域名（例如 mystore.myshopify.com）
days_back	integer	否	30	退货请求的回溯窗口天数
min_returns	integer	否	3	产品纳入输出的最小退货数量
format	string	否	human	输出格式：human 或 json

工作流程

查询退货：使用 GraphQL 查询 returns，条件为 created_at:>='<NOW - days_back days>'，每次获取 250 条，通过游标分页直到 hasNextPage: false。返回对象包含 returnLineItems，其中包含 returnReason、refundableQuantity 以及 fulfillmentLineItem 下的 lineItem（含产品标题和变体 SKU）。
聚合：按退货原因 → 产品 → SKU 进行聚合，计算每个桶的退货数量和占总退货量的百分比。
查询订单：使用相同日期窗口查询订单，统计总订单数作为退货率计算的分母。

GraphQL 操作

退货查询（针对 api_version 2025-01 验证）：

query ReturnsAnalysis($query: String!, $after: String) {
  returns(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        status
        createdAt
        order {
          id
          name
        }
        returnLineItems(first: 50) {
          edges {
            node {
              id
              quantity
              returnReason
              returnReasonNote
              fulfillmentLineItem {
                lineItem {
                  product {
                    id
                    title
                  }
                  variant {
                    id
                    sku
                    title
                  }
                }
              }
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

订单查询（针对 api_version 2025-01 验证）：

query OrderCountForPeriod($query: String!) {
  orders(first: 1, query: $query) {
    pageInfo {
      hasNextPage
    }
  }
  ordersCount: orders(first: 250, query: $query) {
    edges {
      node {
        id
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪

Claude 必须在每个阶段输出以下内容，这是强制性的。

启动时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Return Reason Analysis               ║
║  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>

完成时输出：

对于 format: human（默认）：

══════════════════════════════════════════════
RETURN REASON ANALYSIS  (<days_back> days)
  Total returns:   <n>
  Total orders:    <n>
  Return rate:     <pct>%

  Top Reasons
  ─────────────────────────────────────────
  Wrong size/fit        <n>  (<pct>%)
  Not as described      <n>  (<pct>%)
  Damaged/defective     <n>  (<pct>%)
  Changed mind          <n>  (<pct>%)
  Other                 <n>  (<pct>%)

  Top Products by Return Volume
  ─────────────────────────────────────────
  <Product Title>   <n> returns  (<SKU>)
  Output: return_reasons_<date>.csv
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "return-reason-analysis",
  "store": "<domain>",
  "period_days": 30,
  "total_returns": 0,
  "total_orders": 0,
  "return_rate_pct": 0,
  "by_reason": [],
  "by_product": [],
  "output_file": "return_reasons_<date>.csv"
}

输出格式

CSV 文件 return_reasons_<YYYY-MM-DD>.csv，包含列：return_id, order_name, product_title, sku, quantity, return_reason, reason_note, created_at。

错误处理

错误	原因	恢复方式
THROTTLED	API 速率限制超出	等待 2 秒，最多重试 3 次
No returns in window	该时段内无退货请求	以摘要退出：0 退货
Missing product/variant on line item	产品已删除	记录为“已删除产品”，计入原因统计

适用场景

分析产品退货模式，识别潜在的质量或 listing 问题。
将高退货产品与其 listing 描述和图片进行交叉比对——“与描述不符”的退货通常表明文案或摄影存在问题。
对于较大的商店，使用 min_returns: 10 以关注具有统计显著性的模式，而非一次性投诉。
每月运行并比较不同时期的数据，以跟踪商品或产品质量改进是否减少了特定的退货原因。
与 exchange-vs-refund-ratio 配合使用，了解高退货产品是否通过换货挽回了收入。

限制

该技能为只读操作，不会执行任何变更。
需要已认证的 Shopify CLI 会话，并具备 read_orders 和 read_returns 权限。
依赖 Shopify GraphQL API，受 API 速率限制影响。
如果产品已被删除，退货行项目中的产品/变体信息可能缺失，将记录为“已删除产品”。
输出结果受 days_back 和 min_returns 参数影响，需根据商店规模调整。