order-hold-and-release

用途

本技能用于以程序化方式对履约单（fulfillment orders）进行暂扣或解除暂扣，无需操作 Shopify 后台界面。适用于欺诈审核队列、库存短缺或付款验证等工作流，可替代通过后台 UI 手动管理暂扣或 Shopify Flow 自动化触发的方式。仅对履约单状态为 OPEN 的订单生效。

前置条件

需要先登录：

shopify auth login --store <domain>

所需 API 权限范围：read_orders、write_merchant_managed_fulfillment_orders。

参数

通用参数（store、format、dry_run）之外，本技能特有参数如下：

action：字符串，必填，取值为 hold 或 release。
order_ids：数组，可选（与 query_filter 二选一必填），目标订单 GID 数组，例如 ["gid://shopify/Order/123"]。
query_filter：字符串，可选（与 order_ids 二选一必填），Shopify 订单搜索查询，用于选定订单，例如 "tag:fraud-review"。
reason：字符串，可选，默认 OTHER，暂扣原因，可选值：AWAITING_PAYMENT、HIGH_RISK_OF_FRAUD、INCORRECT_ADDRESS、INVENTORY_OUT_OF_STOCK、OTHER。
reason_notes：字符串，可选，对履约人员可见的自由文本备注。
hold_until：字符串，可选，ISO 8601 日期，暂扣自动到期时间。

order_ids 或 query_filter 必须提供其中一个。

安全说明

第 2 步会对实时履约单执行暂扣或解除暂扣。暂扣订单会阻止其被履约，可能延迟发货；解除暂扣则允许立即继续履约。提交前建议使用 dry_run: true 预览受影响的订单。

工作流步骤

OPERATION: orders — query。输入：order_ids 列表或 query_filter 字符串；获取每个订单的 fulfillmentOrders，以取得履约单 ID 和当前状态。预期输出：履约单 GID 列表及其当前状态；跳过已处于目标状态的记录（已暂扣／未暂扣）。
OPERATION: fulfillmentOrderHold — mutation（当 action 为 hold 时）。输入：每个履约单的 id: <fulfillmentOrderId>、fulfillmentHold: { reason, reasonNotes, holdUntilDate }。预期输出：更新后的 fulfillmentOrder.status: ON_HOLD、userErrors。

或

OPERATION: fulfillmentOrderReleaseHold — mutation（当 action 为 release 时）。输入：每个已暂扣履约单的 id: <fulfillmentOrderId>。预期输出：更新后的 fulfillmentOrder.status: OPEN、userErrors。

GraphQL 操作

orders:query（基于 api_version 2025-01 验证）：

query OrdersForHold($first: Int!, $after: String, $query: String) {
  orders(first: $first, after: $after, query: $query) {
    edges {
      node {
        id
        name
        displayFulfillmentStatus
        fulfillmentOrders(first: 5) {
          edges {
            node {
              id
              status
              requestStatus
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

fulfillmentOrderHold:mutation（基于 api_version 2025-01 验证）：

mutation FulfillmentOrderHold($id: ID!, $fulfillmentHold: FulfillmentOrderHoldInput!) {
  fulfillmentOrderHold(id: $id, fulfillmentHold: $fulfillmentHold) {
    fulfillmentOrder {
      id
      status
    }
    remainingFulfillmentOrder {
      id
      status
    }
    userErrors {
      field
      message
    }
  }
}

fulfillmentOrderReleaseHold:mutation（基于 api_version 2025-01 验证）：

mutation FulfillmentOrderReleaseHold($id: ID!) {
  fulfillmentOrderReleaseHold(id: $id) {
    fulfillmentOrder {
      id
      status
    }
    userErrors {
      field
      message
    }
  }
}

会话追踪

Claude 必须在每个阶段输出指定内容（此为强制要求）。

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: order-hold-and-release               ║
║  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，则在每个 mutation 步骤前加 [DRY RUN] 前缀，且不执行该步骤。

完成时，当 format 为 human（默认）时输出：

══════════════════════════════════════════════
OUTCOME SUMMARY
  Orders targeted:                   <n>
  Fulfillment orders held/released:  <n>
  Skipped (already in target state): <n>
  Errors:                            0
  Output:                            none
══════════════════════════════════════════════

当 format 为 json 时输出：

{
  "skill": "order-hold-and-release",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    { "step": 1, "operation": "OrdersForHold", "type": "query", "params_summary": "<filter or ids>", "result_summary": "<n> fulfillment orders found", "skipped": false },
    { "step": 2, "operation": "FulfillmentOrderHold|FulfillmentOrderReleaseHold", "type": "mutation", "params_summary": "<n> fulfillment orders, action: <hold|release>", "result_summary": "<n> updated", "skipped": false }
  ],
  "outcome": {
    "action": "<hold|release>",
    "orders_targeted": "<n>",
    "fulfillment_orders_affected": "<n>",
    "skipped": "<n>",
    "errors": 0,
    "output_file": null
  }
}

输出格式

无 CSV。内联摘要表：

Order	Fulfillment Order ID	Previous Status	New Status
#1001	gid://...FulfillmentOrder/456	OPEN	ON_HOLD

错误处理

fulfillmentOrder.status 已是 ON_HOLD：订单已暂扣，自动跳过并记录到输出。
fulfillmentOrder.status 不是 OPEN 或 ON_HOLD：订单已完成、已取消或正在处理中，无法暂扣／解除，跳过并报告。
INVENTORY_OUT_OF_STOCK 原因缺少备注：部分店铺对该原因要求提供备注，添加 reason_notes 参数。
mutation 返回 userErrors：权限范围不足或履约单状态无效，核实 write_merchant_managed_fulfillment_orders 权限。

最佳实践

使用 query_filter: "tag:fraud-review" 可通过一条命令暂扣所有由欺诈检测流程打标的订单。
设置 hold_until 以在审核窗口后自动解除暂扣，避免客户订单上的暂扣被遗忘。
使用 query_filter 时始终先执行 dry_run: true，在一次性暂扣数十个订单前确认订单数量。
可与 fulfillment-status-digest 配合，识别已暂扣订单，并在处理完异常后批量解除暂扣。
AWAITING_PAYMENT 原因对履约人员可见，可为订单为何被暂停提供上下文。

限制

资料未说明该技能的具体支持平台范围、收费方式、价格、性能指标或效果数据，暂未提供。