# 管理库存

> 用 Open API 按位置设置和读取 Shoplazza 商品变体的库存，并理解库存项与位置之间的关系。

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

## 适用场景

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

## 前置条件

- 一个已完成 OAuth 授权与 token 存储的公开应用——先完成 [开发独立应用](/docs/app/getting-started/create-public-app/develop-app)。下面每个请求都带 `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`。完整字段见 [获取商品](/api/product-detail)。

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

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

`GET /openapi/2026-01/inventory_items/variant`

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

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

完整字段见 [按变体列出库存项](/api/inventory-item-variants)。

**3. 选定位置**

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

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

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

```json
{
  "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 }]
      }
    ]
  }
}
```

完整字段见 [获取商品库存](/api/product-inventory)。

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

`POST /openapi/2026-01/inventory_levels/set`

请求体：

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

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

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

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

完整字段见 [设置库存级别](/api/inventory-level-set)。

### 读取商品库存

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

响应（节选）：

```json
{
  "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 }]
      }
    ]
  }
}
```

完整字段见 [获取商品库存](/api/product-inventory)。

### 操作位置

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

`GET /openapi/2026-01/locations/default`

响应：默认位置对象，位于 `data.data.location`。见 [查询默认位置](/api/location-get-default)。

如需列出全部位置、修改默认位置、停用某个位置或设置优先级，详见 [查询位置列表](/api/locations)、[修改默认位置](/api/location-change-default)、[停用位置](/api/location-deactivate) 和 [编辑位置优先级](/api/location-edit-priority)。

## 更多库存操作

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

见 [列出库存项](/api/inventory-items)、[获取库存项](/api/inventory-item)、[更新库存项](/api/inventory-item-update)；库存级别：[列出](/api/inventory-levels)、[创建](/api/inventory-level-create)、[更新](/api/inventory-level-update)、[删除](/api/inventory-level-delete)。

## 下一步

- [创建与更新商品](/docs/app/use-cases/product-merchandising/create-and-update-products)
- [组织商品集合](/docs/app/use-cases/product-merchandising/organize-collections)