refund-and-reorder

用途

refund-and-reorder 用于在不进入 Shopify 管理界面的情况下处理订单退款，并可选择为客户创建替换用的草稿订单。它把退款和可选的替换草稿订单创建合并在同一个工作流中，可替代 Gorgias 等应用中的手动退款流程。

前置条件

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

参数

store（string，必填，无默认值）：店铺域名，例如 mystore.myshopify.com
format（string，可选，默认 human）：输出格式，human 或 json
dry_run（bool，可选，默认 false）：仅预览操作，不执行变更（mutation）
order_id（string，必填，无默认值）：订单 GID，例如 gid://shopify/Order/12345
refund_line_items（array，可选，默认全部可退）：要退款的 {line_item_id, quantity} 数组；若省略，则退款全部可退数量
reason（string，可选，默认 other）：退款原因，可选 customer、fraud、inventory、declined、other
create_replacement（bool，可选，默认 false）：若为 true，则在退款后按相同商品行创建草稿订单
notify_customer（bool，可选，默认 true）：向客户发送退款通知邮件

安全说明

第 2、3 步会执行不可逆的财务变更。refundCreate 无法撤销——一旦处理退款，款项无法重新收取。draftOrderCreate 会创建一个新的草稿订单，必须单独开具发票并收款。建议先以 dry_run: true 运行，确认退款商品行与金额后再正式提交。继续前请核对第 1 步中每个商品行的 refundableQuantity。

工作流步骤

操作：order — 查询
- 输入：id: <order_id>
- 预期输出：包含 displayFinancialStatus、lineItems（含 refundableQuantity）、transactions、customer、shippingAddress 的完整订单；继续前确认订单可退款。
操作：refundCreate — 变更（mutation）
- 输入：input.orderId、input.refundLineItems（来自参数或全部可退项）、input.notify、input.note: <reason>
- 预期输出：refund.id、refund.totalRefundedSet、userErrors
操作：draftOrderCreate — 变更（仅当 create_replacement: true 时）
- 输入：input.lineItems（来自原订单商品行）、input.customerId、input.shippingAddress、input.note: "Replacement for order <name>"
- 预期输出：draftOrder.id、draftOrder.name、draftOrder.invoiceUrl、userErrors

GraphQL 操作（验证于 api_version 2025-01）

order:query：

query OrderForRefund($id: ID!) {
  order(id: $id) {
    id
    name
    displayFinancialStatus
    displayFulfillmentStatus
    totalPriceSet {
      shopMoney { amount currencyCode }
    }
    lineItems(first: 50) {
      edges {
        node {
          id
          title
          quantity
          refundableQuantity
          variant {
            id
            sku
            price
          }
        }
      }
    }
    transactions(first: 10) {
      id
      kind
      status
      amountSet {
        shopMoney { amount currencyCode }
      }
      gateway
    }
    refunds {
      id
      createdAt
      totalRefundedSet {
        shopMoney { amount currencyCode }
      }
    }
    customer {
      id
      email
      firstName
      lastName
    }
    shippingAddress {
      address1
      city
      province
      country
      zip
    }
  }
}

refundCreate:mutation：

mutation RefundCreate($input: RefundInput!) {
  refundCreate(input: $input) {
    refund {
      id
      createdAt
      totalRefundedSet {
        shopMoney { amount currencyCode }
      }
    }
    userErrors {
      field
      message
    }
  }
}

draftOrderCreate:mutation：

mutation DraftOrderCreate($input: DraftOrderInput!) {
  draftOrderCreate(input: $input) {
    draftOrder {
      id
      name
      invoiceUrl
    }
    userErrors {
      field
      message
    }
  }
}

会话跟踪

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

开始时输出：

╔══════════════════════════════════════════════╗ ║ SKILL: refund-and-reorder ║ ║ 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> Refund ID: <id> Amount refunded: <amount> <currency> Replacement draft: <draft order name or "none"> Errors: 0 Output: none ══════════════════════════════════════════════

完成时输出（format: json）：

{
  "skill": "refund-and-reorder",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    { "step": 1, "operation": "OrderForRefund", "type": "query", "params_summary": "order <id>", "result_summary": "<status>", "skipped": false },
    { "step": 2, "operation": "RefundCreate", "type": "mutation", "params_summary": "<n> line items, reason: <reason>", "result_summary": "refund <id>", "skipped": false },
    { "step": 3, "operation": "DraftOrderCreate", "type": "mutation", "params_summary": "<n> line items, customer <id>", "result_summary": "draft <name>", "skipped": false }
  ],
  "outcome": {
    "order_name": "<name>",
    "refund_id": "<id>",
    "amount_refunded": "<amount>",
    "currency": "<currency>",
    "draft_order_name": "<name or null>",
    "draft_order_invoice_url": "<url or null>",
    "errors": 0,
    "output_file": null
  }
}

输出格式

不输出 CSV。会话完成摘要会报告退款 ID 与金额。若 create_replacement: true，输出中会包含草稿订单名称与发票 URL。

错误处理

refundableQuantity 为 0：该商品行已全额退款。恢复方式：检查订单退款历史。
refundCreate 返回 userErrors：退款金额无效或订单不可退款。恢复方式：检查 displayFinancialStatus，必须不为 REFUNDED。
draftOrderCreate 返回 userErrors：商品行或客户无效。恢复方式：确认商品变体仍然存在。
Order not found：订单 GID 无效。恢复方式：使用 order-lookup-and-summary 技能查找正确的订单 ID。

最佳实践

始终先运行 dry_run: true——第 2 步不可逆。提交前核对第 1 步输出中每个商品行的 refundableQuantity。
部分退款时显式指定 refund_line_items——省略它会退款全部可退项，这可能并非本意。
create_replacement 生成的草稿订单不会自动开具发票或履约——请将 invoiceUrl 分享给客户以便付款。
对于不应惊动客户的内部更正，可使用 notify_customer: false。
检查第 1 步的 displayFinancialStatus——若为 REFUNDED，则已无可退款内容。