shopify-admin-return-initiation

用途

在已履约（delivered）的订单上发起正式的 Shopify 退货（Return）——指定要退货的订单行项目、数量与原因。这会在 Shopify 原生退货系统中创建退货记录（区别于单纯发起退款）。客服在客户联系要求退回已交付商品时使用。退货记录支持后续的跟踪、仓库检验以及换货/退款处理。

注意：returnCreate 要求订单处于 FULFILLED 状态。对于尚未发货的订单，应改用 cancel-and-restock；对于已退货但需要退款的商品，应使用 refund-and-reorder。

前置条件

执行 shopify auth login --store <domain>
API 权限范围：read_orders、write_returns

参数

store（string，必填）：店铺域名，例如 mystore.myshopify.com
format（string，可选，默认 human）：输出格式，human 或 json
dry_run（bool，可选，默认 false）：仅预览操作而不执行变更
order_id（string，必填）：订单的 GID，例如 gid://shopify/Order/12345
return_line_items（array，可选，默认全部已履约项）：要退货的数组，每项为 {fulfillment_line_item_id, quantity, reason, reason_note}
return_reason（string，可选，默认 OTHER）：当未按项指定时，所有项目的默认退货原因，可选值：SIZE_TOO_SMALL、SIZE_TOO_LARGE、WRONG_ITEM、NOT_AS_DESCRIBED、DEFECTIVE、STYLE、COLOR、UNWANTED、OTHER
notify_customer（bool，可选，默认 true）：向客户发送退货发起通知邮件

安全提示

第 2 步会执行 returnCreate，创建正式退货记录；若 notify_customer 为 true，还会向客户发送邮件。只有在与客户确认确实需要退货后才应执行。建议先用 dry_run: true 预览退货行项目与数量，再正式提交。

工作流程步骤

OPERATION: order — 查询
- 输入：id: <order_id>
- 预期输出：订单名称、displayFulfillmentStatus（必须为 FULFILLED，否则中止）、fulfillments 及其 fulfillmentLineItems（含 id、quantity、discountedTotalSet）
OPERATION: returnCreate — 变更
- 输入：returnInput.orderId、returnInput.returnLineItems 数组（每项含 fulfillmentLineItemId、quantity、reason、customerNote）
- 预期输出：return.id、return.status: OPEN、userErrors

GraphQL 操作

order 查询（已针对 api_version 2025-01 验证）：

query OrderForReturn($id: ID!) {
  order(id: $id) {
    id
    name
    displayFulfillmentStatus
    displayFinancialStatus
    customer {
      id
      defaultEmailAddress {
        emailAddress
      }
      firstName
      lastName
    }
    fulfillments {
      id
      status
      fulfillmentLineItems(first: 50) {
        edges {
          node {
            id
            quantity
            lineItem {
              title
              variant {
                id
                sku
              }
            }
            discountedTotalSet {
              shopMoney { amount currencyCode }
            }
          }
        }
      }
    }
  }
}

returnCreate 变更（已针对 api_version 2025-01 验证）：

mutation ReturnCreate($returnInput: ReturnInput!) {
  returnCreate(returnInput: $returnInput) {
    return {
      id
      status
      order {
        id
        name
      }
    }
    userErrors {
      field
      message
    }
  }
}

会话跟踪

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

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: return-initiation                    ║
║  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>

若 dry_run: true，则在每个变更步骤前加 [DRY RUN] 前缀，且不执行该步骤。

完成时输出：

format: human（默认）：

══════════════════════════════════════════════
OUTCOME SUMMARY
  Order:               <name>
  Return ID:           <id>
  Line items included: <count>
  Return status:       <status>
  Customer notified:   <yes/no>
  Errors:              0
  Output:              none
══════════════════════════════════════════════

format: json 时输出：

{
  "skill": "return-initiation",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    { "step": 1, "operation": "OrderForReturn", "type": "query", "params_summary": "order <id>", "result_summary": "<status>", "skipped": false },
    { "step": 2, "operation": "ReturnCreate", "type": "mutation", "params_summary": "<n> line items, reason: <reason>", "result_summary": "return <id>", "skipped": false }
  ],
  "outcome": {
    "order_name": "<name>",
    "return_id": "<id>",
    "return_status": "<status>",
    "line_items_count": "<count>",
    "customer_notified": "<true/false>",
    "errors": 0,
    "output_file": null
  }
}

输出格式

无 CSV 输出。会话摘要报告退货 ID 与状态。退货包含的行项目在第 2 步输出中列出。

错误处理

displayFulfillmentStatus 不是 FULFILLED：订单尚未发货。恢复方式：对未履约订单使用 cancel-and-restock。
fulfillmentLineItemId 未找到：行项目 ID 不属于该订单的履约项。恢复方式：重新查询订单以获取正确的履约行项目 ID。
returnCreate 返回 userErrors：数量或原因无效。恢复方式：检查数量不超过 fulfillmentLineItem.quantity。
退货已存在：这些项目已创建过退货。恢复方式：在 Shopify 后台检查订单退货。

最佳实践

始终先运行 dry_run: true——在创建退货记录前确认履约行项目 ID 与数量。
return-initiation 技能只创建退货记录，不发起退款。检验退回商品后，使用 refund-and-reorder 处理退款。
当各商品退货原因不同时，按行项目分别设置 reason——这有助于改进 Shopify 中的退货分析。
对于换货（而非退款），在此创建退货记录，然后使用 refund-and-reorder 并设置 create_replacement: true 生成替换草稿订单。
创建后退货状态为 OPEN——生成退货标签时变为 IN_PROGRESS，处理退款时变为 CLOSED。