Shopify 库存与地点

库存调整 API 的 reason 填错会留下错账

现象#

脚本按盘点结果调用 inventoryAdjustQuantities 后,库存历史里每条都显示 Correction,收货、退货、盘点的调整混成一片,财务没法按原因汇总。

原因#

  • reason 只接受固定枚举值,写成自由文本不会报错,而是被归到通用原因上
  • 该 mutation 只做 delta 增减,把盘点绝对值当 delta 传会叠加而不是覆盖
  • name 只接受 available、damaged、reserved、safety_stock 等状态
  • 不传 referenceDocumentUri 时后台只显示应用名,单据来源无法回溯

处理步骤#

  1. 按场景选枚举:盘点用 cycle_count_available,收货用 received,退货入库用 restock
  2. 损伤、质检、预留分别用 damaged、quality_control、reservation_created
  3. 请求体按 changes: [{delta, inventoryItemId, locationId}] 组装
  4. 补 referenceDocumentUri,可用 gid://shopify/Order/123 或自定义 scheme
  5. 2026-04 起必须带 @idempotent(key: "..."),重试才不会被重复扣减

验收标准#

提交后在 Inventory history 里该条记录显示所选原因与单据引用,数量变化正好等于传入的 delta。

专项深读 · 可复现排查指南

库存调整 API:业务事件必须能够追溯

同步库存之前应确定调整是“将库存设置为多少”,还是“在原库存上增减多少”,二者绝不能混淆。

建议按以下顺序复现和定位

  1. 记录 SKU、inventoryItemId、Location、库存差值、业务原因与来源单据号。
  2. 核对当前 Admin GraphQL API 使用的库存 mutation 及其参数结构,避免沿用废弃接口。
  3. 根据业务决定“绝对量”还是“增量”更新,并建立重复事件去重键。
  4. 记录 API 返回的 userErrors 和完成结果,失败时进入人工可复查队列。
  5. 对并发变动与多个仓库分别测试,避免一处回写覆盖另一处库存。

可参考的示例(非真实客户环境)

库存同步数据记录字段(示意)
source_event_id | sku | inventory_item_id | location_id
old_quantity | delta | new_quantity | business_reason
sync_status | request_id | updated_at
注意:不要从页面上显示的“可售库存”直接反推出某仓的实际库存,更不要无审计记录地覆盖多个 Location。

交付与验证记录应该包含什么

选 5 个具有不同 Location 与业务原因的样例,核对接口结果与 ERP/WMS 业务单据一致。

原始技术资料:Shopify / Google 官方文档。本节为根据公开文档整理的排查方法与模拟示例,未宣称来自客户项目或已在您的店铺实测。

本文由 风格技术 技术团队整理,适用于 Shopify 标准版与 Plus 店铺。Shopify 平台能力迭代较快,具体操作路径与字段以官方文档和店铺后台实际版本为准。