用途 在已送达（已履约）的订单上发起正式的 Shopify 退货。指定要退回的行项目、数量和原因，在 Shopify 原生退货系统中创建退货记录（区别于直接发放退款）。客服人员在客户联系要求退回已送达商品时使用。退货记录可支持后续的跟踪、仓库检查以及换货/退款处理。注意：returnCreate 要求订单处于 FULFILLED 状态。尚未发货的订单请改用取消并回补库存；已退回商品需要退款时，请使用退款重下单流程。
前提条件 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 预览退货行项目与数量。
工作流步骤 操作：order — 查询 输入：id: <order_id> 预期输出：订单名称、displayFulfillmentStatus（必须为 FULFILLED，否则中止）、fulfillments 及其 fulfillmentLineItems（含 id、quantity、discountedTotalSet）
操作：returnCreate — 变更 输入：returnInput.orderId、returnInput.returnLineItems 数组（每项含 fulfillmentLineItemId、quantity、reason、customerNote） 预期输出：return.id、return.status: OPEN、userErrors
GraphQL 操作
order:query — 已针对 api_version 2025-01 校验
query OrderForReturn($id: ID!) { order(id: $id) { id name displayFulfillmentStatus displayFinancialStatus customer { id email firstName lastName } fulfillments { id status fulfillmentLineItems(first: 50) { edges { node { id quantity lineItem { title variant { id sku } } discountedTotalSet { shopMoney { amount currencyCode } } } } } } } }
returnCreate:mutation — 已针对 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：订单尚未发货。恢复方式：未履约订单请使用取消并回补库存。 fulfillmentLineItemId 未找到：行项目 ID 不属于该订单的履约项。恢复方式：重新查询订单以获取正确的履约行项目 ID。 returnCreate 返回 userErrors：数量或原因无效。恢复方式：检查数量不超过 fulfillmentLineItem.quantity。 退货已存在：这些商品已创建过退货。恢复方式：在 Shopify 后台检查订单退货。
最佳实践 始终先运行 dry_run: true —— 在创建退货记录前确认履约行项目 ID 与数量。 return-initiation 技能只创建退货记录，不发放退款。检查退回商品后，使用退款重下单流程处理金额退款。 当各商品退货原因不同时，按行项目分别设置 reason —— 这有助于改进 Shopify 中的退货分析。 对于换货（非退款），先在此创建退货记录，再使用退款重下单流程并设 create_replacement: true 生成替换草稿订单。 创建后退货状态为 OPEN —— 生成退货面单时变为 IN_PROGRESS，处理退款后变为 CLOSED。