用途
该技能用于取消未发货或部分发货的订单，并提供可配置的库存恢复、退款和客户通知选项，无需手动进入 Shopify 后台操作。适用于欺诈异常处理、缺货取消，或客户在发货前请求取消等场景。无法取消已完全发货的订单。
前置条件
需要已认证的 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）：仅预览操作而不执行变更
order_id（string，必填）：订单的 GID，例如 gid://shopify/Order/12345
reason（string，可选，默认 OTHER）：取消原因，可选 CUSTOMER、DECLINED、FRAUD、INVENTORY、STAFF、OTHER
restock（bool，可选，默认 true）：是否为取消的订单行项目恢复库存
refund（bool，可选，默认 true）：是否为已捕获的付款发起退款
notify_customer（bool，可选，默认 true）：是否向客户发送取消邮件
staff_note（string，可选）：记录在取消操作上的内部备注
安全性
第 2 步执行 orderCancel，该操作不可逆。已取消的订单无法重新打开。若 refund: true，任何已捕获的付款会被自动退款。若 restock: true，库存数量会立即恢复。建议先以 dry_run: true 运行，确认订单状态可取消后再提交。
工作流程步骤
操作 1：order — 查询 输入：id: <order_id> 预期输出：订单名称、displayFulfillmentStatus、displayFinancialStatus、cancelledAt（必须为 null）、fulfillmentOrders.status（必须为 OPEN 或 ON_HOLD——若任一履约单为 IN_PROGRESS 或 CLOSED 则中止）
操作 2：orderCancel — 变更 输入：orderId、reason、restock、refund、notifyCustomer、staffNote 预期输出：orderCancelUserErrors——成功时为空；订单现已被取消并带有 cancelledAt 时间戳
GraphQL 操作
order:query — 已针对 api_version 2025-01 验证
query OrderForCancel($id: ID!) { order(id: $id) { id name displayFulfillmentStatus displayFinancialStatus cancelledAt totalPriceSet { shopMoney { amount currencyCode } } lineItems(first: 50) { edges { node { id title quantity variant { id sku inventoryQuantity } } } } fulfillmentOrders(first: 5) { edges { node { id status } } } customer { id defaultEmailAddress { emailAddress } firstName lastName } } }
orderCancel:mutation — 已针对 api_version 2025-01 验证
mutation OrderCancel( $orderId: ID! $reason: OrderCancelReason! $restock: Boolean! $refund: Boolean! $notifyCustomer: Boolean! $staffNote: String ) { orderCancel( orderId: $orderId reason: $reason restock: $restock refund: $refund notifyCustomer: $notifyCustomer staffNote: $staffNote ) { orderCancelUserErrors { field message } userErrors { field message } } }
会话跟踪
Claude 必须在每个阶段输出以下内容，此为强制要求。
开始时输出：
╔══════════════════════════════════════════════╗ ║ SKILL: cancel-and-restock ║ ║ 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> Cancellation reason: <reason> Restocked: <true|false> Refund issued: <true|false> Customer notified: <true|false> Errors: 0 Output: none ══════════════════════════════════════════════
format: json 时，输出：
{ "skill": "cancel-and-restock", "store": "<domain>", "started_at": "<ISO8601>", "completed_at": "<ISO8601>", "dry_run": false, "steps": [ { "step": 1, "operation": "OrderForCancel", "type": "query", "params_summary": "order <id>", "result_summary": "<status>", "skipped": false }, { "step": 2, "operation": "OrderCancel", "type": "mutation", "params_summary": "reason: <reason>, restock: <bool>, refund: <bool>, notifyCustomer: <bool>", "result_summary": "cancelled at <timestamp>", "skipped": false } ], "outcome": { "order_name": "<name>", "reason": "<reason>", "restocked": true, "refund_issued": true, "customer_notified": true, "errors": 0, "output_file": null } }
输出格式
无 CSV 输出。会话摘要会内联报告取消结果。若 restock: true，则列出已恢复的变体 SKU 和数量。
错误处理
错误：cancelledAt 不为 null——原因：订单已被取消——恢复：无需操作
错误：履约单状态为 IN_PROGRESS——原因：订单正在拣货/打包——恢复：联系仓库停止——一旦 IN_PROGRESS 便无法通过程序取消
错误：orderCancelUserErrors——原因：订单已完全发货——恢复：改用 refund-and-reorder 技能
错误：订单未找到——原因：订单 GID 无效——恢复：使用 order-lookup-and-summary 技能查找正确的 ID
最佳实践
始终先运行 dry_run: true——在提交取消前检查 displayFulfillmentStatus 和履约单状态。
对高风险订单设置 reason: FRAUD——该原因会记录在 Shopify 的欺诈分析中。
若订单已被捕获（状态 PAID），设置 refund: true——未退款的取消会导致客户争议。
对于大批量取消（例如缺货事件），使用 format: json 循环处理订单 ID，以捕获每个结果用于审计日志。
若仓库已开始拣货，不要通过 API 取消——直接联系仓库，仅在其确认未开始实际工作后再取消。