库存调整 API 的 reason 填错会留下错账
现象#
脚本按盘点结果调用 inventoryAdjustQuantities 后,库存历史里每条都显示 Correction,收货、退货、盘点的调整混成一片,财务没法按原因汇总。
原因#
- reason 只接受固定枚举值,写成自由文本不会报错,而是被归到通用原因上
- 该 mutation 只做 delta 增减,把盘点绝对值当 delta 传会叠加而不是覆盖
- name 只接受 available、damaged、reserved、safety_stock 等状态
- 不传 referenceDocumentUri 时后台只显示应用名,单据来源无法回溯
处理步骤#
- 按场景选枚举:盘点用
cycle_count_available,收货用received,退货入库用restock - 损伤、质检、预留分别用
damaged、quality_control、reservation_created - 请求体按
changes: [{delta, inventoryItemId, locationId}]组装 - 补
referenceDocumentUri,可用gid://shopify/Order/123或自定义 scheme - 2026-04 起必须带
@idempotent(key: "..."),重试才不会被重复扣减
验收标准#
提交后在 Inventory history 里该条记录显示所选原因与单据引用,数量变化正好等于传入的 delta。
专项深读 · 可复现排查指南
库存调整 API:业务事件必须能够追溯
同步库存之前应确定调整是“将库存设置为多少”,还是“在原库存上增减多少”,二者绝不能混淆。
建议按以下顺序复现和定位
- 记录 SKU、inventoryItemId、Location、库存差值、业务原因与来源单据号。
- 核对当前 Admin GraphQL API 使用的库存 mutation 及其参数结构,避免沿用废弃接口。
- 根据业务决定“绝对量”还是“增量”更新,并建立重复事件去重键。
- 记录 API 返回的 userErrors 和完成结果,失败时进入人工可复查队列。
- 对并发变动与多个仓库分别测试,避免一处回写覆盖另一处库存。
可参考的示例(非真实客户环境)
库存同步数据记录字段(示意)
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 平台能力迭代较快,具体操作路径与字段以官方文档和店铺后台实际版本为准。