跳到主要内容

管理库存

设置并读取商品在各个位置的库存。

适用场景​

新品上架铺货、补货，或在多个位置之间分配库存。

前置条件​

  • 一个已完成 OAuth 授权与 token 存储的公开应用——先完成 开发应用。下面每个请求都带 Access-Token: {token} 头，使用你为每个店铺保存的 token。
  • OAuth 授权时已获得 inventory 访问权限范围。

库存的建模方式​

库存是两个概念的交集：

  • 位置（location）——持有库存的仓库或门店。
  • 库存项（inventory item）——变体背后的可库存单元。

**库存级别（inventory level）**是某个库存项在某个位置的库存数量。要设置库存，你需要变体的 inventory_item_id 和一个 location_id。

为商品变体设置库存​

设置库存分四步：获取变体 id、将其解析为库存项、选定一个位置，再逐个库存项设置库存级别。

1. 获取商品的变体 id

GET /openapi/2026-01/products/{id}

响应：变体 id 位于 data.data.product.variants[].id。完整字段见 获取商品。

2. 将每个变体 id 解析为对应的 inventory_item_id

数组参数须重复键名：variant_ids=a&variant_ids=b。

GET /openapi/2026-01/inventory_items/variant

响应（节选，列表在 data.data.variant_inventory_items）：

{
  "code": "Success",
  "data": {
    "variant_inventory_items": [
      { "inventory_item_id": "626514004247984698", "variant_id": "28ea5ee4-5b1d-4a9d-a92e-e60f0dff3da8" }
    ]
  }
}

完整字段见 按变体列出库存项。

3. 选定位置

复用商品当前库存所在的位置。

GET /openapi/2026-01/products/{id}/inventory

响应（节选，位置 id 在 data.data.variants[].location_items[].location_id）：

{
  "code": "Success",
  "data": {
    "product_id": "4d3e7859-455c-4899-a296-7befe731c585",
    "Stock": 7,
    "variants": [
      {
        "variant_id": "28ea5ee4-5b1d-4a9d-a92e-e60f0dff3da8",
        "location_items": [{ "location_id": "604253696473177059", "stock": 3 }]
      }
    ]
  }
}

完整字段见 获取商品库存。

4. 为每个库存项设置库存级别

POST /openapi/2026-01/inventory_levels/set

请求体：

{
  "inventory_item_id": "626514004247984698",
  "location_id": "604253696473177059", // 64 位整数——须以字符串形式传递
  "stock": 100
}

响应（节选，更新后的库存级别在 data.data.inventory_level）：

{
  "code": "Success",
  "data": {
    "inventory_level": {
      "inventory_item_id": "626514004247984698",
      "location_id": "604253696473177059",
      "stock": 100,
      "updated_at": "2026-07-02T02:58:47Z"
    }
  }
}
注意

location_id 是一个 64 位整数，超出了 JavaScript 的安全整数范围（例如 604253696473177100）。如果按 JavaScript 数字解析，末几位会被静默四舍五入，导致设置库存的调用报错 Location not found（未找到位置）。请始终把 64 位 id 当字符串处理——用支持大整数（big-int）的解析器解析响应，或者像上面示例那样将 location_id 以字符串形式传递。（inventory_item_id 本身返回的就是字符串，不受此影响。）

完整字段见 设置库存级别。

读取商品库存​

GET /openapi/2026-01/products/{id}/inventory

响应（节选）：

{
  "code": "Success",
  "data": {
    "product_id": "4d3e7859-455c-4899-a296-7befe731c585",
    "Stock": 7,
    "variants": [
      {
        "variant_id": "28ea5ee4-5b1d-4a9d-a92e-e60f0dff3da8",
        "location_items": [{ "location_id": "604253696473177059", "stock": 3 }]
      }
    ]
  }
}

完整字段见 获取商品库存。

操作位置​

获取位置列表或默认位置，以决定库存存放在何处。

GET /openapi/2026-01/locations/default

响应：默认位置对象，位于 data.data.location。见 查询默认位置。

如需列出全部位置、修改默认位置、停用某个位置或设置优先级，详见 查询位置列表、修改默认位置、停用位置 和 编辑位置优先级。

更多库存操作​

需要更细控制时，直接操作库存项与库存级别：读取或更新某变体背后的库存项，或按位置列出、创建、更新、删除库存级别。

见 列出库存项、获取库存项、更新库存项；库存级别：列出、创建、更新、删除。

下一步​