> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.orderupb2b.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.orderupb2b.com/_mcp/server.

# 2026 年 11 月 11 日

這一版讓組合品有自己的庫存額度，並新增組合品庫存 API。既有組合品的庫存行為會改變，已經串接組合品的整合請先看最後一節。

## 組合品有自己的庫存額度

組合品要能下單，現在兩關都要過：組合品自身的額度，以及各組成規格的庫存。

* `isNegativeStockAllowed` 為 `true` 時，組合品自身**不限量**，只看組成規格，與過去相同。
* 為 `false` 時，組合品自身的可售數（在庫數扣掉未出貨訂單佔用）用完就不能再下單，即使組成規格還有庫存。適合限量禮盒這類情境。
* 出貨時組合品自身的在庫數會跟著扣減，出貨後取消會回補，與一般規格相同。
* 組合品自身的額度不會產生預購數量，預購只由允許負庫存的組成規格計算。

## 新增組合品庫存 API

* `GET /v1/bundles/{id}/stock` 查詢組合品自身的 `inventoryQty`、`availableQty` 與 `isNegativeStockAllowed`。id 指向一般規格時回傳 `404 not_found`。
* `POST /v1/bundles/stock/batch` 以絕對值設定組合品自身的在庫數，每一筆用 `bundleId`（組合 SKU 序號）指定；`quantity` 與 `isNegativeStockAllowed` 都是選填，省略的欄位維持現值。`bundleId` 不存在或指向一般規格時，該筆回報 `bundle not found`，不影響其他筆。

兩支端點與規格庫存使用同樣的庫存讀取／寫入權限。

## 規格庫存可以設定是否允許負庫存

* `GET /v1/skus/{id}/stock` 的回應新增 `isNegativeStockAllowed`。
* `POST /v1/skus/stock/batch` 的每一筆可以選填 `isNegativeStockAllowed`，省略時維持現值；用料號命中多顆規格時，每一顆都套用同一個值。

## ⚠️ 庫存批次的 quantity 改為選填，沒帶不再壓成 0

`POST /v1/skus/stock/batch` 與 `POST /v1/bundles/stock/batch` 的 `quantity` 改為選填。過去 `POST /v1/skus/stock/batch` 沒帶 `quantity` 會被當成 0、把在庫數蓋成 0；現在沒帶就維持現有在庫數，也不留異動紀錄，所以只想改 `isNegativeStockAllowed` 時可以只帶它。`quantity` 與 `isNegativeStockAllowed` 都沒帶時，該筆回報 `quantity or isNegativeStockAllowed is required`，不影響其他筆。

## 組合品主檔新增 isNegativeStockAllowed

`POST /v1/bundles`、`PUT /v1/bundles/{id}`、`POST /v1/bundles/batch` 可以帶 `isNegativeStockAllowed`，查詢結果也會帶出。新增時省略為 `true`（不限量）；更新時省略保留現有值。組合品自身不限量以外時，`GET /v1/bundles/{id}` 的 `availableQty` 也不會超過組合品自身的可售數。

## ⚠️ 既有組合品與錯誤字串的異動

* **過去透過本 API 建立的組合品，`isNegativeStockAllowed` 都是 `false`、在庫數為 0。** 這一版上線後，這些組合品會因為自身額度為 0 而無法下單。要維持過去「只看組成規格」的行為，請用 `PUT /v1/bundles/{id}` 或 `POST /v1/bundles/stock/batch` 把 `isNegativeStockAllowed` 設為 `true`；要限量就用 `POST /v1/bundles/stock/batch` 設定在庫數。
* `POST /v1/skus/stock/batch` 的 `skuId` 指向組合 SKU 時，錯誤字串由 `bundle SKU stock cannot be set through this API` 改為 `bundle SKU stock must be set through /v1/bundles/stock/batch`。有比對這個字串的整合需要調整。

各端點的完整規則見「API 規格」的「組合品庫存」「庫存」「組合品」，錯誤字串見「錯誤碼」。