/v2/providers/seller_api/apis/api/v1/marketplace/seller-products/inventories2609170000批次查詢商品庫存資訊
簡介
批次查詢商品庫存資訊
詳細內容
適⽤買家市場：台灣
批次查詢多個已註冊商品的詳細資訊，包含商品基本資料、選項資訊、庫存數量、銷售價格及銷售狀態。
此 API 允許您一次查詢最多 50 個商品，所有商品必須屬於同一個賣家（vendorId） 。適合需要同時監控多個商品庫存狀態的場景。
技術規格注意事項
- 批次限制： 單次請求（Request）最多可查詢 50 個商品 ID。
- 賣家限制： 所有查詢的商品必須屬於同一個賣家編號（vendorId）。
- 效能建議： 請根據實際需求控制查詢數量，避免過於頻繁的大量調用，以維持系統效能。
- 資料一致性： API 回傳的庫存資訊為查詢當下的即時（Real-time）資料。
- 錯誤處理： 若請求中部分商品不存在，API 將僅回傳現有的商品資訊，不會因單一報錯而中斷整個請求。
路徑
範例端點
https://api-gateway.coupang.com/v2/providers/seller_api/apis/api/v1/marketplace/seller-products/inventories請求內容
請求參數
請求內容參數
| Name | Type | Description |
|---|---|---|
| sellerProductIds* | integer[] | 已註冊商品 ID 列表 • 所有商品必須屬於同一個賣家（vendorId） • 最少 1 個，最多 50 個元素 • 商品建立後顯示的商品 ID |
{
"sellerProductIds": [
1234567890,
1234567891,
1234567892
]
}回應內容
回應訊息
| Name | Type | Description |
|---|---|---|
| code | string | SUCCESS/ERROR
|
| message | string | 結果訊息
|
| data | object[] | 查詢到的商品資訊列表
|
| sellerProductId data[].sellerProductId | integer | 註冊商品 ID
|
| sellerProductName data[].sellerProductName | string | 註冊用商品名稱 訂購單上使用的商品名稱 |
| displayProductName data[].displayProductName | string | 顯示用商品名稱,實際顯示在 Coupang 商品詳情頁的商品名稱
|
| generalProductName data[].generalProductName | string | 商品名稱 不含購買選項資訊（如尺寸、顏色等）的商品名稱 |
| vendorId data[].vendorId | string | 賣家 ID, Coupang 核發給賣家的唯一代碼
|
| items data[].items | object[] | 商品選項列表
|
| sellerProductItemId data[].items[].sellerProductItemId | integer | 賣家商品選項 ID
|
| vendorItemId data[].items[].vendorItemId | integer | 選項 ID 給予賣家商品的唯一編號 |
| itemName data[].items[].itemName | string | 選項名稱
|
| externalVendorSku data[].items[].externalVendorSku | string | 外部賣家 SKU 賣家自定義的商品識別碼 |
| amountInStock data[].items[].amountInStock | integer | 剩餘庫存數量
|
| salePrice data[].items[].salePrice | integer | 銷售價格
|
| onSale data[].items[].onSale | boolean | 選項銷售狀態 true/false |
Response Example
{
"code": "SUCCESS",
"message": "查詢成功",
"data": [
{
"sellerProductId": 1234567890,
"sellerProductName": "測試商品A",
"displayProductName": "【品牌名稱】測試商品A",
"generalProductName": "測試商品A",
"vendorId": "A00123456",
"items": [
{
"sellerProductItemId": 1271845813,
"vendorItemId": 4279191317,
"itemName": "200ml_1個",
"externalVendorSku": "SKU-A-001",
"amountInStock": 100,
"salePrice": 10000,
"onSale": true
},
{
"sellerProductItemId": 1271845814,
"vendorItemId": 4279191318,
"itemName": "200ml_2個",
"externalVendorSku": "SKU-A-002",
"amountInStock": 50,
"salePrice": 18000,
"onSale": true
}
]
},
{
"sellerProductId": 1234567891,
"sellerProductName": "測試商品B",
"displayProductName": "【品牌名稱】測試商品B",
"generalProductName": "測試商品B",
"vendorId": "A00123456",
"items": [
{
"sellerProductItemId": 1271845815,
"vendorItemId": 4279191319,
"itemName": "標準款",
"externalVendorSku": "SKU-B-001",
"amountInStock": 0,
"salePrice": 15000,
"onSale": false
}
]
}
]
}錯誤碼
| HTTP | 代碼 | 訊息 |
|---|---|---|
| 400 | HTTP_400 | Bad Request |
錯誤說明
| HTTP | 類型 | 錯誤訊息 | 解決方案 |
|---|---|---|---|
| 400 | 400 (檢查請求參數） | Request body cannot be empty | 請求內容不可為空，請提供 sellerProductIds 列表 |
| 400 | 400 (檢查請求參數） | sellerProductIds is required | 必須提供 sellerProductIds 欄位 |
| 400 | 400 (檢查請求參數） | sellerProductIds must be a list | sellerProductIds 必須是陣列格式 |
| 400 | 400 (檢查請求參數） | sellerProductIds cannot be empty | sellerProductIds 陣列不可為空，至少需要 1 個商品ID |
| 400 | 400 (檢查請求參數） | Maximum 50 sellerProductIds allowed | 最多只能查詢 50 個商品，請減少查詢數量 |
| 400 | 400 (檢查請求參數） | Invalid sellerProductId format: [1234abc] | 商品 ID 格式錯誤， 必須為數字格式 |
| 400 | 400 (檢查請求參數） | Products belong to different vendors | 提供的商品必須屬於同一個賣家（vendorId） |
| 403 | 403 (權限驗證) | Seller[A00123456] cannot query products of another seller[A00789012] | 無法查詢其他賣家的商品資訊，請確認商品 ID 是否正確 |
| 404 | 404 (資源不存在) | No data found for products: [1234567890, 1234567891] | 找不到指定的商品資訊，請確認商品 ID 是否正確 |
| 404 | 404 (資源不存在) | Seller[A00123456] has no products matching the provided IDs | 您的帳戶下找不到符合的商品，請確認商品 ID 是否屬於您的帳戶 |
| 500 | 500 (伺服器錯誤) | Internal server error. Please try again later | 伺服器內部錯誤，請稍後再試或聯繫技術支援 |
| 503 | 503 (服務暫時不可用) | Service temporarily unavailable. Please retry after some time | 務暫時無法使用，請稍後重試 |