在电商库存管理中，大多数平台的库存模型是相对扁平的——一个SKU对应一个可售数量，开发者只需关注“总库存”与“已占用”的差值。小米有品接口则呈现出一套显著不同的库存架构：库存被拆分为多个具有不同业务属性的层级，开发者在调用库存修改接口之前，必须首先理解每一层库存的业务含义和扣减规则，否则极易引发超卖或库存冻结错误。

一、库存列表接口揭示的多层结构

小米有品接口的库存列表（/mtop/aftersale/openapi/inventory/list）返回的SkuInventoryDetail对象，包含了至少六个维度的库存字段。youpinOnSaleInventory 表示有品仓在售库存，即由有品仓发货的商品的可售数量；youpinNoSaleInventory表示有品仓不可售库存，对应的是该SKU在自发货渠道有实物库存的情形。merchantFreeInventory 是商家仓可支配库存，开发者可以不经审批直接扣减；而merchantBindInventory 是商家仓不可支配库存，扣减此类库存需要在商家工作台提交申请，由供应链审批后方可执行。此外，merchantOrderCountOnYoupin 和merchantOrderCountOnVmi 分别记录商家仓在有品渠道和非有品渠道（VMI）的订单占用数量。

这套分层设计的核心意图是：将“物理库存”与“可自由调度的库存”解耦。一个SKU可能在商家仓有大量实物，但其中一部分已被有品渠道的订单占用，另一部分可能属于不可支配的锁定状态。如果开发者简单地用“总库存 - 已售”来计算可售量，必然导致超卖或错误扣减不可支配库存。

二、可售量的正确计算公式

小米有品接口的官方文档明确给出了商家可以直接扣减的库存口径：商家可以直接扣减的数量 = 商家仓可支配库存（merchantFreeInventory） − 商家仓有品渠道订单占用（merchantOrderCountOnYoupin） 。这个公式的含义是，可支配库存中已经被有品渠道订单锁定但尚未完成出库的部分，不能再被新的同步操作重复扣减。

对于有品仓发货的SKU，可售量的计算则需要以youpinOnSaleInventory为基础，同时考虑订单占用和不可售库存的影响。开发者在设计库存同步逻辑时，应在本地维护一个库存分层映射表，将中央库存系统中的每一种库存状态映射到小米有品的对应字段，而不是将所有库存笼统地视为一个数字。

三、库存修改接口的增量与全量语义

小米有品接口的库存修改（/mtop/aftersale/openapi/inventory/update）支持两种更新模式，由type字段控制：type=0或不传时为增量更新，changeCount为正数表示补库存，负数表示扣减库存，但只能扣减商家仓可支配库存；type=1时为全量覆盖，且覆盖数量不能少于商家仓不可支配库存。

这里有两个需要特别注意的约束：其一，增量扣减无法触碰不可支配库存，如果ERP系统试图扣减这部分库存，接口会拒绝或产生不符合预期的结果。其二，全量覆盖时如果设置的目标值低于merchantBindInventory，同样会被接口拒绝。这意味着开发者在设计库存同步任务时，不能简单地用“目标库存”做全量覆盖，而必须在覆盖前将不可支配库存纳入计算，确保写入值不低于这个下限。

四、跨渠道共享库存的架构建议

对于同时在小米有品、淘宝、京东等多渠道经营同一批实物库存的商家，建议以ERP的中央库存为唯一可信源，但为小米有品单独维护一个“渠道可售量”视图。这个视图的计算不应简单地复制中央库存的可用量，而应遵循小米有品的分层规则：可售量 = 商家仓可支配库存 − 有品渠道订单占用（对于自发货SKU），或 有品仓在售库存 − 已锁定数量（对于有品仓发货SKU）。在每次向小米有品同步库存之前，先查询库存列表接口获取最新的分层数据，再进行计算和写入，而非依赖本地缓存的过期快照。