shopify-admin-order-hold-and-release

用途

本技能通过编程方式对履约单（fulfillment order）放置或解除保留（hold），无需在 Shopify 后台手动导航操作。适用于欺诈审核队列、库存短缺或付款核实等工作流。仅对处于 OPEN 状态的履约单有效。

前置条件

登录命令：

shopify auth login --store <domain>

所需 API 权限范围：read_orders、write_merchant_managed_fulfillment_orders

参数

通用参数（store、format、dry_run）以及技能特定参数：

参数	类型	必填	默认值	说明
action	string	是	—	hold 或 release
order_ids	array	否*	—	目标订单 GID 数组，例如 ["gid://shopify/Order/123"]
query_filter	string	否*	—	Shopify 订单搜索查询，用于筛选订单，例如 "tag:fraud-review"
reason	string	否	OTHER	保留原因：AWAITING_PAYMENT、HIGH_RISK_OF_FRAUD、INCORRECT_ADDRESS、INVENTORY_OUT_OF_STOCK、OTHER
reason_notes	string	否	—	履约人员可见的自由文本备注
hold_until	string	否	—	保留自动过期的 ISO 8601 日期（可选）

*order_ids 与 query_filter 必须提供其一。

安全提示

第 2 步会对线上履约单放置或解除保留。保留订单会阻止其履行，可能延迟交付。解除保留则允许立即履行。建议先以 dry_run: true 运行，预览将受影响的订单后再正式提交。

工作流步骤

操作：orders — 查询 输入：order_ids 列表或 query_filter 字符串；获取每个订单的 fulfillmentOrders 以得到履约单 ID 和当前状态。预期输出：履约单 GID 列表及其当前状态；跳过已处于目标状态的订单（已保留／未保留）。

操作：fulfillmentOrderHold — 变更（当 action: hold 时） 输入：id: <fulfillmentOrderId>，fulfillmentHold: { reason, reasonNotes, holdUntilDate }，按履约单逐一传入。预期输出：更新后的 fulfillmentOrder.status: ON_HOLD、userErrors。

或者

操作：fulfillmentOrderReleaseHold — 变更（当 action: release 时） 输入：id: <fulfillmentOrderId>，针对每个已保留的履约单。预期输出：更新后的 fulfillmentOrder.status: OPEN、userErrors。

GraphQL 操作

针对 api_version 2025-01 校验：

# orders:query
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
mutation FulfillmentOrderHold($id: ID!, $fulfillmentHold: FulfillmentOrderHoldInput!) {
  fulfillmentOrderHold(id: $id, fulfillmentHold: $fulfillmentHold) {
    fulfillmentOrder {
      id
      status
    }
    remainingFulfillmentOrder {
      id
      status
    }
    userErrors {
      field
      message
    }
  }
}

# fulfillmentOrderReleaseHold:mutation
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，则在每个变更步骤前加 [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 参数
变更返回 userErrors	权限不足或履约单状态无效	确认 write_merchant_managed_fulfillment_orders 权限

最佳实践

使用 query_filter: "tag:fraud-review" 一条命令即可保留所有被欺诈检测流程打上标签的订单。
设置 hold_until 可在审核窗口期结束后自动解除保留——防止客户订单上的保留被遗忘。
使用 query_filter 时始终先运行 dry_run: true——在一次性保留数十个订单前先确认订单数量。
结合 fulfillment-status-digest 识别被保留的订单，在解决异常后批量解除。
AWAITING_PAYMENT 原因对履约人员可见，可提供订单被暂停的背景信息。