> 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.

# 變更紀錄

這裡記錄 OrderUp B2B Open API 文件站台與底層 API 的重要異動——新端點、行為調整、修正。可以依標籤篩選項目，也可以透過 [RSS](./changelog.rss) 訂閱。

## 2026 年 11 月 14 日

這一版統一庫存欄位的命名，並把可組數量從組合品主檔移除。兩項都是破壞性變更，有串接庫存或組合品的整合請在上線前調整。

## ⚠️ 庫存欄位統一改名為 inventoryQuantity

同一個「在庫數」過去在查詢時叫 `inventoryQty`、在批次寫入時叫 `quantity`，現在一律叫 `inventoryQuantity`；可售數也跟著改成 `availableQuantity`。

| 端點                                                              | 舊欄位                           | 新欄位                                     |
| --------------------------------------------------------------- | ----------------------------- | --------------------------------------- |
| `GET /v1/skus`、`GET /v1/skus/{id}`                              | `inventoryQty`                | `inventoryQuantity`                     |
| `GET /v1/skus/{id}/stock`、`GET /v1/bundles/{id}/stock`          | `inventoryQty`、`availableQty` | `inventoryQuantity`、`availableQuantity` |
| `POST /v1/skus/stock/batch`、`POST /v1/bundles/stock/batch` 的每一筆 | `quantity`                    | `inventoryQuantity`                     |

* 批次寫入**不再讀取舊的 `quantity`**。繼續送 `quantity` 不會報錯，而是被當成沒帶：在庫數維持現值、不留異動紀錄；如果該筆也沒帶 `isNegativeStockAllowed`，會回報 failed。請務必改送 `inventoryQuantity`。
* 兩個欄位都沒帶時的錯誤字串由 `quantity or isNegativeStockAllowed is required` 改為 `inventoryQuantity or isNegativeStockAllowed is required`。有比對這個字串的整合需要調整。
* 組合品配方的每組用量（`components[].quantity`）與數量精度（`quantityPrecision`）不是庫存欄位，名稱不變。

## ⚠️ 組合品主檔移除可組數量

`GET /v1/bundles` 與 `GET /v1/bundles/{id}` 的回應不再有 `availableQty`（以目前庫存最多能組出幾份）。組合品主檔現在不回傳任何庫存數字。

* 組合品自身的在庫數與可售數，請改查 `GET /v1/bundles/{id}/stock`。
* API 不再提供可組數量；需要時請用各組成規格的 `GET /v1/skus/{id}/stock` 與配方的每組用量自行計算。

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

## 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 規格」的「組合品庫存」「庫存」「組合品」，錯誤字串見「錯誤碼」。

## 2026 年 11 月 9 日

## 客戶可以用業務代碼指定負責業務

`POST /v1/companies`、`PUT /v1/companies/{id}` 與 `POST /v1/companies/batch` 新增選填欄位 `internalUserOuterSysCode`：用負責業務（內部使用者）的 `outerSysCode` 指定人選，不必先查出他的序號。

* 同時帶 `internalUserId` 與 `internalUserOuterSysCode` 時以 `internalUserId` 為準，代碼完全不會被比對。
* 代碼與貴租戶底下未刪除的內部使用者精準比對，前後空白會被忽略、大小寫敏感；只有空白視同省略。
* 代碼對不到任何人回傳 `400 internal_user_not_found`，對到兩位以上回傳 `400 internal_user_code_ambiguous`。兩種情況都**不會**退回預設業務，也不會寫入任何欄位；批次只有該筆失敗。
* 兩個欄位都省略時行為不變：新增套用預設業務，更新保留現有值。

欄位規則見「API 規格」的「客戶」，新增的錯誤字串見「錯誤碼」。

## 2026 年 11 月 6 日

這一版把規格（SKU）與商品分開：規格與組合品以料號識別，不一定要放在商品底下。其中組合品的識別序號與價格路徑是**破壞性變更**，已經串接組合品的整合需要調整。

## 規格可以只用料號同步

* `POST /v1/skus` 與 `POST /v1/skus/batch` 的 `productId` 改為選填。省略（或帶 0）就建成未加入商品的規格，查詢時 `productId` 為 0。
* 只帶料號、沒有 `id` 時，會在整個租戶內比對料號，**同一料號的每一顆規格都會更新**，所屬商品不變；找不到才新增。只管料號的 ERP 可以重複推送同一份資料，第一次新增、之後都是更新。
* 單筆回應改為 `{ "id": 5001, "ids": [5001] }`，所有批次寫入的逐筆結果也多了 `ids`：列出這一筆新增或更新的每一個序號，`id` 是其中第一個。
* 依 `id` 指定的更新帶 `"productId": 0` 會回傳 400，要保留所屬商品就不要送這個欄位。
* `GET /v1/skus` 會列出未加入商品的規格，`productId=0` 可以只篩出這些規格。
* 移除 `productId is required to create a SKU` 與 `bundle product cannot receive SKUs through this API` 兩個錯誤；料號只屬於組合品時改回 `outerSysCode belongs to a bundle SKU; use /v1/bundles`。

## 規格與組合品的狀態可以寫入

規格與組合品的建立、更新與批次寫入新增 `status` 欄位，接受 `Active`（上架）、`Inactive`（下架）、`GiftOnly`（僅供贈品），不分大小寫。省略時，新增為 `Active`、更新保留現有值；其他值回傳 `400 invalid_status`，批次只有該筆失敗。

## 移到另一個商品時比照後台

用 `productId` 把規格或組合品移到另一個商品時，規則與後台相同：排到目標商品的最後一個、客戶價格設定跟著移過去，原商品底下若已經沒有任何規格且狀態是上架或下架-顯示，會自動改為下架。

## 新建的商品一律下架

`POST /v1/products` 與 `POST /v1/products/batch` 新建的商品一律是 `Inactive`，請在後台確認內容後再上架。過去以組合商品建立的商品，現在也是一般商品頁，可以在「商品」端點查詢與更新。

## 庫存可以用料號推送

`POST /v1/skus/stock/batch` 的每一筆可以只帶 `outerSysCode`，租戶內同料號的每一顆規格都會設成同一個在庫數。回應改為一顆規格一列，並帶回請求的 `outerSysCode`，所以列數可能多於請求筆數。

## 新增客戶帳號 API

你現在可以替客戶管理前台登入帳號：`/v1/companies/{id}/users` 提供查詢（單筆與分頁清單）、建立與更新，`GET /v1/company-user-roles` 列出可以指派的角色。規則與在後台維護客戶帳號相同。

* 帳號在整個租戶內不得重複，不只是同一家客戶。新帳號會自動產生邀請碼，並依貴租戶的首次登入設定決定是否要求改密碼。
* 改派角色會讓帳號立即登出並清空購物車；設為 `Inactive` 也會立即登出。沒有刪除端點，停用帳號請用 `status`。
* 每一家客戶至少要保留一個生效中的 Boss 帳號，移除最後一個會回傳 `409 last_active_boss`。
* 網址上的客戶找不到時回傳 `404 company_not_found`，帳號找不到時回傳 `404 not_found`。

端點說明見「API 規格」的「客戶帳號」與「客戶帳號角色」，新增的錯誤字串見「錯誤碼」。

## ⚠️ 組合品改以組合 SKU 序號識別

組合品現在是一顆組合 SKU 加一份配方，可以放在任何商品頁底下，也可以不放。

* `/v1/bundles` 路徑上的 `{id}`、請求的 `id`、回應的 `id`／`ids`，以及 `PUT /v1/bundle-prices/batch` 的 `bundleId`，**全部改為組合 SKU 序號**，不再是商品序號。請重新用 `GET /v1/bundles` 取得序號。
* 回應移除 `skuId`（它就是 `id`）與 `productCategoryId`，新增 `productId`（所在商品頁，0 代表沒有放在商品頁）。
* 請求移除 `productCategoryId`，改為選填的 `productId`。舊版客戶端仍然送 `productCategoryId` 不會被拒絕，會被忽略。
* 只帶料號時與規格一樣比對整個租戶，同料號的每個組合品都會更新。料號屬於一般規格時回傳 `400 product_type_conflict`；商品端點不再回這個代碼。

## ⚠️ 組合品價格改為單數路徑

`GET /v1/bundles/{id}/prices` 改為 `GET /v1/bundles/{id}/price`，與 `GET /v1/skus/{id}/price` 一致。舊路徑沒有保留別名，會回傳 404。`PUT /v1/bundle-prices/batch` 路徑不變。

文件站台的「組合商品」同步改稱「組合品」。各端點的完整規則見「API 規格」，新增與移除的錯誤字串見「錯誤碼」，料號比對規則見「Upsert 與冪等」。

## 2026 年 11 月 4 日

## 客戶可以寫入結帳條件與付款方式

`POST /v1/companies`、`PUT /v1/companies/{id}` 與 `POST /v1/companies/batch` 新增三個欄位：`settlementType`（`Cash` 現結／`Monthly` 月結）、`paymentMethodMode`（`Inherit`／`Specify`）與 `paymentMethods`。這三個欄位原本只能讀取，現在可以由 ERP 直接維護，規則與後台客戶維護相同：

* 省略時，新增的客戶為 `Monthly`、`Inherit`、空清單；更新時保留現有值。
* `paymentMethodMode` 與 `paymentMethods` 須成對寫入：`Inherit` 會清空清單，`Specify` 必須在同一個請求帶非空清單。
* `Specify` 實際生效的是清單與租戶目前已啟用付款方式的交集。
* 驗證失敗回傳 400 加上對應的錯誤字串，整筆不寫入；批次寫入則是那一筆回報 `failed`。

欄位規則見「API 規格」的「客戶」，錯誤字串見「錯誤碼」。

## 新增付款方式清單

新增 `GET /v1/payment-methods`，列出貴租戶可以指派給客戶的付款方式，包含租戶在後台自訂、key 由 OrderUp 產生的線下付款方式。寫入客戶的 `paymentMethods` 之前，先從這裡取得合法的 key。清單不分頁，建議查一次後在你端快取。端點說明見「API 規格」的「付款方式」。

## 新增客戶總部 API

新增 `/v1/company-groups` 共五支端點，可以查詢、建立、更新與刪除客戶總部，也就是一家總部客戶加上它底下的子客戶。成員以客戶序號或 ERP 端的客戶代碼指定。客戶回應（`GET /v1/companies` 與 `GET /v1/companies/{id}`）同時新增唯讀的 `companyGroupId`，標示客戶所屬的群組。

* ⚠️ 群組決定資料可見範圍：總部客戶的 Boss 角色使用者看得到群組內所有成員的資料。把客戶加進群組，總部的人就看得到這家客戶的資料；移出客戶或刪除群組則會立即收回。
* 更新時只給 `subCompanyIds: []` 會移除所有子客戶；兩個子客戶欄位都省略才是不動。
* 同一租戶的群組寫入請一次送一筆，避免並行請求把同一家子客戶加進兩個群組；也不要與該租戶的客戶寫入同時進行。

端點說明見「API 規格」的「客戶總部」，新增的錯誤字串見「錯誤碼」。

## 2026 年 11 月 3 日

## 後台使用者支援批次更新

新增 `PUT /v1/internal-users/batch`，可以用 ERP 端的使用者代碼（`outerSysCode`）或使用者序號（`id`）一次更新多位後台使用者，不必先存下 OrderUp 的序號：

* 每一筆有 `id` 就用 `id` 找出要更新的使用者，沒有 `id` 才用 `outerSysCode`；其餘欄位的部分合併規則與 `PUT /v1/internal-users/{id}` 相同。
* 同時帶 `id` 與 `outerSysCode` 時，`outerSysCode` 會被寫入成這位使用者的新代碼，可以順便把 ERP 代碼綁上既有使用者。
* 只更新、不新增；只帶 `outerSysCode` 時，代碼只是用來找人的鍵，不會被改寫。
* 同租戶內有兩位以上的使用者用同一個代碼時，該筆回報 `ambiguous_outer_sys_code` 且不寫入，其他筆照常處理。

逐筆結果的形狀與錯誤字串見「批次 API」與「錯誤碼」。

## 後台使用者清單支援 outerSysCode 篩選

`GET /v1/internal-users` 新增 `outerSysCode` 查詢參數，大小寫不敏感的子字串比對，用法與 `name`、`email` 篩選相同。

## 2026 年 9 月 9 日

## 文件站台首次發布

OrderUp B2B Open API 文件站台正式發布，涵蓋 12 個資源家族、共 36 支 `/v1` 端點：

* **客戶**——查詢清單、查詢單筆、建立、更新、批次寫入
* **點數額度**——查詢、批次同步
* **合約額度**——查詢、批次同步
* **商品分類**——查詢分類樹（唯讀）
* **商品**——查詢清單、查詢單筆、建立、更新、批次寫入
* **規格（SKU）**——查詢清單、查詢單筆、建立、更新、批次寫入
* **規格（SKU）價格**——查詢、批次更新
* **組合商品**——查詢清單、查詢單筆、建立、更新、批次寫入
* **組合商品價格**——查詢、批次更新
* **庫存**——查詢單一規格庫存、批次更新庫存
* **後台使用者**——查詢清單、查詢單筆、建立、更新
* **後台角色**——查詢清單（唯讀，不分頁）

所有端點都需要 HMAC-SHA256 簽章驗證，詳見「驗證與簽章」。

## 導覽頁

首批導覽頁涵蓋：

* 開始使用
* 驗證與簽章
* 分頁與篩選
* Upsert 與冪等
* 批次 API
* 錯誤碼