shopify-admin-inventory-adjustment

用途

该技能对特定地点的特定变体应用库存数量修正，相当于在 Shopify 后台手动编辑库存的程序化等价操作。适用场景包括：循环盘点后发现差异、3PL 退货批次延迟入账，或在 multi-location-inventory-audit 技能识别出 Available/Committed 漂移之后进行修正。它替代了在 Shopify 后台逐行手动编辑库存的方式。

前置条件

执行 shopify auth login --store <domain>
API 权限范围：read_products、write_inventory

参数

store（string，必填）：商店域名，例如 mystore.myshopify.com
format（string，可选，默认 human）：输出格式，human 或 json
dry_run（bool，可选，默认 false）：预览操作而不执行变更
adjustments（array，必填）：由 {sku, location_id, delta} 对象组成的数组。delta 为带符号的数量变化（例如 +5 表示增加 5 件，-3 表示减少 3 件）
reason（string，可选，默认 correction）：记录到审计追踪的调整原因，可选值：correction、cycle_count、damaged、received、reservation_created、reservation_deleted、shrinkage
reference_document_uri（string，可选）：链接调整到采购订单、退货或盘点文档的 URI

安全提示

第 2 步执行 inventoryAdjustQuantities 会立即更改实时库存数量。错误的调整可能导致超卖（减少过多）或库存虚高（错误增加）。建议先以 dry_run: true 运行，查看每个 SKU 调整前后的数量再提交。reason 字段会永久记录在 Shopify 的库存活动历史中。

工作流程步骤

OPERATION: productVariants — query
- 输入：对 adjustments 中的每个 {sku}，按 SKU 查找变体以获取其 inventoryItem.id；同时获取当前 inventoryQuantity 用于前后对比
- 预期输出：所有调整目标的 {sku → inventoryItemId, currentQuantity} 映射；若任一 SKU 未找到则中止
OPERATION: inventoryAdjustQuantities — mutation
- 输入：changes 数组，包含 {inventoryItemId, locationId, delta, ledgerDocumentUri}，使用 reason 和 reference_document_uri 参数
- 预期输出：inventoryAdjustmentGroup.changes，含每项的 quantityAfterChange；以及 userErrors

GraphQL 操作

# productVariants:query — validated against api_version 2025-01
query VariantBySku($first: Int!, $query: String) {
  productVariants(first: $first, query: $query) {
    edges {
      node {
        id
        sku
        inventoryQuantity
        inventoryItem {
          id
          tracked
        }
        product {
          title
        }
      }
    }
  }
}

# inventoryAdjustQuantities:mutation — validated against api_version 2025-01
mutation InventoryAdjustQuantities($input: InventoryAdjustQuantitiesInput!) {
  inventoryAdjustQuantities(input: $input) {
    inventoryAdjustmentGroup {
      id
      reason
      changes {
        name
        delta
        quantityAfterChange
        item {
          id
          sku
        }
        location {
          id
          name
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

会话追踪

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

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: inventory-adjustment                 ║
║  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, e.g., "143 records returned">

若 dry_run: true，则在每个 mutation 步骤前加 [DRY RUN] 前缀且不执行。

完成时输出：

format: human（默认）：

══════════════════════════════════════════════
OUTCOME SUMMARY
  SKUs adjusted:        <value>
  Total units added:    <value>
  Total units removed:  <value>
  Errors:               <count, 0 if none>
  Output:               <filename or "none">
══════════════════════════════════════════════

format: json 时，输出符合以下 schema 的 JSON 对象：

{
  "skill": "inventory-adjustment",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    {
      "step": 1,
      "operation": "<OperationName>",
      "type": "query|mutation",
      "params_summary": "<string>",
      "result_summary": "<string>",
      "skipped": false
    }
  ],
  "outcome": {
    "skus_adjusted": 0,
    "total_units_added": 0,
    "total_units_removed": 0,
    "errors": 0,
    "output_file": "<filename|null>"
  }
}

输出格式

CSV 文件 inventory-adjustments-<YYYY-MM-DD>.csv，列包括：sku, product_title, location_name, quantity_before, delta, quantity_after, reason。

错误处理

SKU not found：SKU 在商店中不存在。核对 SKU 拼写；可使用 low-inventory-restock 浏览有效 SKU。
inventoryItem.tracked: false：变体已禁用库存追踪。调整前需在 Shopify 后台启用追踪。
userErrors from mutation：delta 无效、地点无效或权限问题。检查 write_inventory 权限范围并验证地点 GID。
Delta would push quantity below 0：调整移除量超过可用量。确认正确的 delta 值；仅在已知库存移除时使用负 delta。

最佳实践

始终先运行 dry_run: true——前后对比 CSV 预览让你在影响实时库存前确认每项变更。
使用 reason: cycle_count 并配合指向盘点表的 reference_document_uri——这会在 Shopify 库存活动日志中创建永久审计追踪。
将单次盘点会话的所有修正批量放入一条命令，而非逐条应用——审计追踪会将它们归入单个 inventoryAdjustmentGroup。
调整后再次运行 multi-location-inventory-audit 以确认所有差异已解决。
对于 3PL 退货批次，使用 reason: received 并链接退货批次文档 URI——这使与 3PL 发票的对账变得简单。