coupang
API 文件
商品 API品類 API運輸 / 訂單 API退貨 API物流資訊客服 / 諮詢
PUT/v2/providers/seller_api/apis/api/v1/marketplace/seller-productsv1

商品修改

# 01

簡介

消費者市場：韓國、台灣 修改賣家的商品資訊。 使用 Product Query API 查詢商品後，僅修改欲變更的欄位值，並將完整的 JSON 訊息送出即可快速完成修改。 可在原本用於商品建立的 request body 中，加入 [sellerProductId] 與 [sellerProductItemId] 來進行修改。 - 更新／修改選項：在欲更新的選項項目最上層加入 [sellerProductItemId] 與 [vendorItemId]，修改對應的 [attributeValueName] 後送出請求。

# 02

詳細內容

消費者市場：韓國、台灣

修改賣家的商品資訊。
使用 Product Query API 查詢商品後，僅修改欲變更的欄位值，並將完整的 JSON 訊息送出即可快速完成修改。

可在原本用於商品建立的 request body 中，加入 [sellerProductId] 與 [sellerProductItemId] 來進行修改。
- 更新／修改選項：在欲更新的選項項目最上層加入 [sellerProductItemId] 與 [vendorItemId]，修改對應的 [attributeValueName] 後送出請求。  
- 刪除選項：從 items／options 陣列中刪除欲移除的項目，並在欲保留的項目最上層加入 [sellerProductItemId] 後送出請求。（曾經通過「approved」狀態的選項無法刪除）
- 新增選項：不需輸入 [sellerProductItemId]，直接新增 items 陣列內容後送出請求。

※ 可透過 Product Query API 查詢 [sellerProductItemId]。 
※ 對於已通過審核的商品選項，其售價、庫存數量、販售狀態以及折扣率基準價格，無法透過 Product Modification API 進行修改，必須改用 [Change qty/price/on sale or not/base price for discount rate by item] API 進行變更。

通路

PUT

/v2/providers/seller_api/apis/api/v1/marketplace/seller-products

請求範例端點

https://api-gateway.coupang.com/v2/providers/seller_api/apis/api/v1/marketplace/seller-products

參數需求

請求範例

Name Required Type Description
sellerProductId O Number

Registered product ID

商品建立完成後，系統將顯示已註冊的商品 ID（data）。
displayCategoryCode O Number

Category code displayed

商品註冊完成後，賣家將無法自行修改。
sellerProductName O String

Registered product name

用於 PO（採購訂單）的商品名稱。

最長長度：100 個字元。
vendorId O String

Seller ID

由 Coupang 發放給賣家的唯一代碼。
saleStartedAt O String

Start date of selling

"yyyy-MM-dd'T'HH:mm:ss" style
saleEndedAt O String

End date of selling

"yyyy-MM-dd'T'HH:mm:ss" style, *Can select as long as up to 2099 
displayProductName   String

Product name displayed

實際顯示於 Coupang 上販售的商品名稱。

建議使用以下格式：[brand] + [generalProductName]。

若未填寫此欄位，系統將顯示 [brand] + [generalProductName] 或 [sellerProductName]。

最長長度：100 個字元。
brand   String

Brand 品牌

品牌名稱請輸入標準的中文／英文名稱，且不得包含空白或特殊字元。
generalProductName   String

Product name 商品名稱

商品名稱不得包含購買選項（屬性顯示）資訊，如尺寸、顏色等；可另外輸入型號名稱。
productGroup   String

Product group 商品群組

商品類型；可參考所屬分類中最終層級（最下層）的分類名稱填寫。

若與商品名稱重複（例如 [generalProductName]），則無需填寫。
deliveryMethod O String Delivery method
參數名稱 狀態
SEQUENCIAL 一般配送（依序配送）
 
COLD_FRESH *台灣市場無售。
MAKE_ORDER
AGENT_BUY
VENDOR_DIRECT
deliveryCompanyCode O String Courier code
deliveryChargeType O String Types of shipping fee
參數名稱 狀態
FREE 免運配送
NOT_FREE 付費配送
CHARGE_RECEIVED 到貨付款（運費到付）
CONDITIONAL_FREE 條件式免運

● 設定免運配送時

請設定退貨時的初始配送費 [deliveryChargeOnReturn]（單程）以及退貨運費 [returnCharge]（單程）。

● 設定付費配送時

請設定標準配送費 [deliveryCharge] 以及退貨運費（單程）。

● 設定條件式免運配送時

請設定標準配送費及退貨運費（單程）。

● 設定到貨付款（COD）配送時

適用到貨付款配送的商品類別將另行整理，並由賣家客服中心提供相關指引。

※ 使用 [CONDITIONAL_FREE] 時，可自行設定所需的免運條件金額。

deliveryCharge O Number

標準運費

若為付費配送或條件式免運，請輸入單程配送費用金額。
freeShipOverAmount O Number

免運配送門檻金額

● 範例：若要設定消費滿 10,000 韓元即可免運，請將 [deliveryChargeType] 設為「CONDITIONAL_FREE」，並於 [freeShipOverAmount] 輸入 10000。

※ 僅可輸入大於 100 NTD的金額，且須以 100 為單位遞增。

※ 若為免運配送，請輸入 0。
deliveryChargeOnReturn O Number

退貨時的初始配送費用

在免運配送的情況下，退貨運費由顧客負擔。
remoteAreaDeliverable O String * 不使用 TW 市場
unionDeliveryType O String 是否可進行合併配送
參數名稱 狀態
UNION_DELIVERY 可合併配送
NOT_UNION_DELIVERY 不可合併配送

※ 合併配送條件：

出貨地點資訊為必填，僅限出貨地點相同的商品可進行合併配送。

不可限制到貨付款選項。

無法設定以下值：「Cannot set COD（到貨付款）配送」

returnCenterCode O String

退貨地點中心代碼

建立退貨地點後，請輸入所擷取的退貨地點中心代碼。

● 退貨地點可透過 WING 或退貨地點建立 API 建立。

● 若無法建立退貨地點，可輸入「NO_RETURN_CENTERCODE」以直接註冊退貨地點資訊。
returnChargeName O String

退貨地點負責人（所有者）姓名

請於透過 Coupang WING 或退貨地點建立 API 註冊退貨地點後進行確認。
companyContactNumber O String

退貨地點聯絡電話

請於透過 Coupang WING 或退貨地點建立 API 註冊後確認。
returnZipCode O String

退貨地點郵遞區號

請於透過 Coupang WING 或退貨地點建立 API 註冊後確認。
returnAddress O String

退貨地點地址

請於透過 Coupang WING 或退貨地點建立 API 註冊後確認。
returnAddressDetail O String

退貨地點詳細地址

請於透過 Coupang WING 或退貨地點建立 API 註冊後確認。
returnCharge O Number

退貨運費

退貨商品取件時的單程配送費用。
outboundShippingPlaceCode O Number

出貨地點地址代碼

選擇合併配送時為必填欄位，可透過 Shipping Location Query API 查詢。

選擇海外代購（AGENT_BUY）時，僅可輸入海外地址。
vendorUserId O String

實際使用者 ID（Coupang WING ID）

所屬供應商的使用者 ID
requested O Boolean

是否申請自動審核

於商品註冊時，選擇是否同時申請自動審核以進行販售。

● false：僅儲存已填寫的內容。（若要開始販售，需透過 Product Approval Request API 或 WING 另行申請審核）

● true : 儲存內容並自動申請販售審核
items O List List of vendor's product options 供應商商品選項清單 
  sellerProductItemId  O Number

供應商商品選項 ID

註冊完成後，系統會為各選項分配 ID，可透過 Product Query API 查詢。

修改既有選項時此欄位為必填；新增選項時請輸入 Null。
  vendorItemId  O Number

Option ID

值為 Null 表示處於「暫存」狀態；商品審核完成後將顯示該值。
  itemName  O String

Vendor's product option name 供應商商品選項名稱

請確保各選項名稱之間不重複。

選項名稱不會顯示於前台，並可能依實際購買的選項而有所變化。

最長長度：150 個字元
  originalPrice  O Number

Base price for discount rate 折扣率基準價格

用於計算折扣率（%）的折扣前價格。若輸入的價格與售價相同，將顯示為「Coupang 價格（售價）」。審核完成後，如需修改此價格，請使用 [Change base price for discount rate by item] API。
  salePrice O  Number

Selling price

僅能在尚未申請商品審核前，透過 Product Modification API 修改售價。

商品審核完成後，需透過 [Change price by item] API 修改售價。
  maximumBuyCount  O Number

Qty that can be sold 可販售數量

庫存數量

僅能在申請商品審核前，透過 Product Modification API 修改可販售數量。

商品審核完成後，需透過 [Change qty by item] API 修改庫存。
  maximumBuyForPerson  O Number

每人最大購買數量

單一消費者可購買的最大數量

若無限制，請輸入「0」。

範例：若每人限購 100 件，且最大購買期間為 3 天，表示同一人於 3 天內最多可購買 100 件。
  maximumBuyForPersonPeriod  O Number

Maximum purchase period 最大購買期間

設定單一消費者可購買最大數量的時間區間。

設定單一消費者可購買最大數量的時間區間。

範例：若每人限購 100 件，且最大購買期間為 3 天，表示同一人於 3 天內最多可購買 100 件。
  outboundShippingTimeDay  O Number

Vendor lead time (Day) 供應商出貨準備天數（天）

請以「天」為單位，輸入訂單成立日（D-Day）後的預計出貨天數。若預計隔天出貨（D+1），請輸入「1」。
  unitCount O Number

Unit count

unitCount 欄位用於定義單一商品列表中所包含的個別單位數量。
系統會使用這個數值來計算並向使用者顯示「單價」（例如每克、每個或每毫升的價格），以確保在多件或捆綁商品中提供透明的價格資訊。
若商品不需要顯示單價. 針對由單一單位組成的商品，請將此數值設為 1。
重要提示：此數值僅嚴格用於價格計算，請勿使用此數值來定義或設定商品的庫存數量。
  adultOnly O  String 是否限制 18 歲以上
參數名稱 狀態
ADULT_ONLY 僅可販售給 19 歲（含）以上消費者的商品
EVERYONE 不受年齡限制的商品
  taxType O String 是否課稅
參數名稱 狀態
TAX 應稅商品
FREE 免稅商品
  parallelImported O String * 不使用 TW 市場
  overseasPurchased O  String

* 不使用 TW 市場

參數名稱

狀態
  pccNeeded O  Boolean

* 不使用 TW 市場

- default value: not required (false)
  externalVendorSku   String

Seller product code (Vendor product code)

可設定供應商專屬的商品代碼，該值將包含於 PO Query API 的回傳結果中。
  barcode   String

Barcode 條碼

商品上所附的有效且標準的產品條碼
  emptyBarcode   Boolean

No barcode 無條碼

若無條碼，請設為 true
  emptyBarcodeReason   String

無條碼原因

最長長度：100 個字元
  modelNo   String

Model number 型號

販售商品的型號名稱
  extraProperties    

供應商商品（選項）的附加資訊

Key：以鍵值（Key-Value）形式輸入，可依需求重複輸入多次。
    Key   String Value
  certifications   List

認證資訊類型

認證資訊類型
    certificationType   String

認證資訊類型

可透過 Category Meta Data Query API 查詢可註冊的認證類型。

若該分類不需認證，請設為 NOT_REQUIRED。
    certificationCode   String

商品認證資訊代碼

由認證機構（發證單位）核發的代碼
    certificationAttachments   List<Map<String,String>>

認證資訊附件

Map 的 key 固定為以下兩種，僅需擇一使用：

1. vendorPath：圖片非來自 Coupang CDN Server 時使用
 

2. cdnPath：圖片已上傳至 Coupang CDN Server 時使用

Note: 註冊手機商品時，若分類為（displayCategoryCode = 62600，消費性電子 > 手機／平板／配件 > 手機／平板 > 手機 > 未註冊手機），可透過在 attachments 中設定圖片 URL 以上傳所需文件。

1. Mobile communication certification - not use in TW
  searchTags   List

搜尋關鍵字

可依需求重複輸入多個搜尋關鍵字，例如：["search word1","search word2"]。

單一搜尋關鍵字不得超過 20 個字元，最多可輸入 20 個搜尋關鍵字。除 !@#$%^&*-+;:’. 之外，不可使用其他特殊字元。
  images O List

Image list 圖片清單

可依需求重複輸入多筆圖片資訊。
    imageOrder O Number

圖片顯示順序

0,1,2...
    imageType O  String

圖片類型

代表圖片類型

可上傳 3MB 以下的正方形圖片，支援 JPG、PNG 格式（最小 500 × 500px，最大 5000 × 5000px）。

● 必填

REPRESENTATION：正方形圖片；主圖片

● 選填

DETAIL：其他圖片（最多可註冊 9 張）

USED_PRODUCT：二手商品實際狀況圖片（最多可註冊 4 張）
 
    cdnPath O String

Coupang CDN path

若圖片已上傳至 Coupang CDN，請直接輸入；以下兩者擇一必填：vendorPath 或 cdnPath。

僅可使用 80 或 443 連接埠的圖片路徑。

最長長度：200 個字元
    vendorPath O String

Vendor image path

供應商使用的圖片路徑；若路徑以 http:// 開頭，系統將自動下載並上傳至 Coupang CDN。vendorPath 或 cdnPath 需擇一填寫。

最長長度：200 個字元
  notices O List

List of product display info

可透過 Category Meta Data Query API，或下載包含完整分類清單的 Excel 檔案，查詢並選擇所需的顯示資訊欄位／項目。
    noticeCategoryName O  String

商品顯示資訊的分類名稱

請輸入該分類可使用的其中一個商品顯示資訊分類。

可透過 Category Meta Data Query API，或下載包含完整分類清單的 Excel 檔案，查詢並選擇所需的顯示資訊欄位／項目。
    noticeCategoryDetailName O  String 商品顯示資訊的分類名稱
    content O  String 內容
  attributes O  List

開放屬性管理

1. 刪除開放屬性

您現在可以從商品選項中刪除開放屬性。若要刪除開放屬性，只需在 payload 的 attributes 陣列中移除該屬性的完整元素即可。

2. 辨識開放屬性

如需辨識開放屬性，請比對分類中繼資料（Category Metadata）。

Verify Against Category Metadata: Call the Category Metadata Query API. If the attributeTypeName does not exist in the response, it is an open attribute.
    attributeTypeName O  String

選項類型名稱

可透過 Category Meta Data Query API，或下載包含完整分類的 Excel 檔案，查詢並選擇正確的選項類型名稱。

最長長度：25 個字元
    attributeValueName O  String

選項值

請輸入與選項類型名稱 [attributeTypeName] 相對應的值，並包含單位（例如："200ml"）。

最長長度：30 個字元
  contents O   List

內容清單

可依需求重複輸入多筆內容。
    contentsType O   String 內容類型
Parameter Name Status
IMAGE Image
IMAGE_NO_SPACE Image (No Spaces)
TEXT Text
IMAGE_TEXT Image-Text
TEXT_IMAGE Text-Image
IMAGE_IMAGE Image-Image
TEXT_TEXT Text-Text
TITLE Title
HTML HTML
    contentDetails O   List 詳細內容清單
      content O   String 內容
      detailType O   String 詳細類型 
Parameter Name Status
IMAGE image
TEXT text
  offerCondition   String

商品狀態

商品建立完成後，無法變更 。
  offerDescription   String

二手商品詳細說明

請描述二手商品的實際狀況，最多可輸入 700 個字元。

僅當 offerCondition 設為 Used 時才需填寫。
requiredDocuments   List 是否必須提交必要文件
  templateName   String 必要文件範本名稱
  documentPath   String

必要文件的 Coupang CDN 路徑

documentPath 與 vendorDocumentPath 兩者擇一必填。

最長長度：150 個字元
  vendorDocumentPath   String

必要文件的供應商路徑

必要文件的路徑；若路徑以 http:// 開頭，系統將自動下載並上傳至 Coupang CDN。documentPath 與 vendorDocumentPath 兩者擇一必填。

最長長度：150 個字元
extraInfoMessage   String

接單後製作（Made-to-order）訊息

當配送方式選擇為「made-to-order」時，請輸入需傳達給顧客的說明訊息。
manufacture   String

製造商

若無法填寫正確的製造商資訊，可填入 [brand] 欄位中的內容。
bundleInfo   Map<String,String> 組合商品類型 
  bundleType   String

組合商品類型 

● SINGLE : 相同組成的商品（預設值）

● AB : 混合組成的商品

註冊混合組成商品時，無法設定商品選項。新增組合商品資訊後，將無法再修改組合商品的設定值。此行為將視同註冊新商品，並依新商品規則套用。

 

Request Example

{
 "sellerProductId": 309323422,
 "displayCategoryCode": 56137,
 "sellerProductName": "test_潔顏油_修改",
 "vendorId": "A00012345",
 "saleStartedAt": "2017-11-30T00:00:00",
 "saleEndedAt": "2099-01-01T23:59:59",
 "displayProductName": "Happy Bath 皂莓潔顏油",
 "brand": "Happy Bath",
 "generalProductName": "皂莓潔顏油",
 "productGroup": "潔顏油",
 "deliveryMethod": "SEQUENCIAL",
 "deliveryCompanyCode": "KGB",
 "deliveryChargeType": "FREE",
 "deliveryCharge": 0,
 "freeShipOverAmount": 0,
 "deliveryChargeOnReturn": 5000,
 "remoteAreaDeliverable": "N",
 "unionDeliveryType": "UNION_DELIVERY",
 "returnCenterCode": "1000274592",
 "returnChargeName": "退貨地點_1",
 "companyContactNumber": "02-1234-678",
 "returnZipCode": "135-090",
 "returnAddress": "首爾特別市 江南區 三成洞",
 "returnAddressDetail": "333",
 "returnCharge": 5000,
 "outboundShippingPlaceCode": "74010",
 "vendorUserId": "et5",
 "requested": true,
 "items": [
   {
     "sellerProductItemId": 769536471,
     "itemName": "200ml_1入",
     "originalPrice": 13000,
     "salePrice": 10000,
     "maximumBuyCount": 100,
     "maximumBuyForPerson": 0,
     "outboundShippingTimeDay": 1,
     "maximumBuyForPersonPeriod": 1,
     "unitCount": 1,
     "adultOnly": "EVERYONE",
     "taxType": "TAX",
     "parallelImported": "NOT_PARALLEL_IMPORTED",
     "overseasPurchased": "NOT_OVERSEAS_PURCHASED",
     "pccNeeded": false,
     "externalVendorSku": "0001",
     "barcode": "",
     "emptyBarcode": true,
     "emptyBarcodeReason": "商品無法確認_無條碼原因",
     "modelNo": "171717",
     "extraProperties": {
       "coupangSalePrice": 5000,
       "onlineSalePriceForBooks": 10000,
       "transactionType": "manufacturer",
       "businessType": "美容"
     },
     "certifications": [
       {
         "certificationType": "NOT_REQUIRED",
         "certificationCode": ""
       }
     ],
     "searchTags": [
       "搜尋關鍵字1",
       "搜尋關鍵字2"
     ],
     "images": [
       {
         "imageOrder": 0,
         "imageType": "REPRESENTATION",
         "vendorPath": "http://image11.coupangcdn.com/image/product/image/vendoritem/2018/06/25/3719529368/27a6b898-ff3b-4a27-b1e4-330a90c25e9c.jpg"
       },
       {
         "imageOrder": 1,
         "imageType": "DETAIL",
         "vendorPath": "http://image11.coupangcdn.com/image/product/image/vendoritem/2017/02/21/3000169918/34b79649-d625-4f49-a260-b78bf7a573a8.jpg"
       }
     ],
     "notices": [
       {
         "noticeCategoryName": "化妝品",
         "noticeCategoryDetailName": "容量（重量）",
         "content": "請參考詳細頁面"
       },
       {
         "noticeCategoryName": "化妝品",
         "noticeCategoryDetailName": "品質保證標準",
         "content": "如產品異常，將依公平交易委員會公告之消費者爭議解決標準進行補償。"
       }
     ],
     "attributes": [
       {
         "attributeTypeName": "數量",
         "attributeValueName": "1入"
       },
       {
         "attributeTypeName": "單件容量",
         "attributeValueName": "200ml"
       }
     ],
     "contents": [
       {
         "contentsType": "TEXT",
         "contentDetails": [
           {
             "content": "<html><div><img src='http://image11.coupangcdn.com/image/product/content/vendorItem/2018/06/26/196713/738d905f-ed80-4fd8-ad21-ed87b195a19e.jpg' /></div></html>",
             "detailType": "TEXT"
           }
         ]
       }
     ],
     "offerCondition": "NEW",
     "offerDescription": ""
   }
 ],
 "requiredDocuments": [
   {
     "templateName": "其他認證文件",
     "vendorDocumentPath": "http://image11.coupangcdn.com/image/product/content/vendorItem/2018/07/02/41579010/eebc0c30-8f35-4a51-8ffd-808953414dc1.jpg"
   }
 ],
 "manufacture": "愛茉莉太平洋",
 "bundleInfo": {
   "bundleType": "SINGLE"
 }
}

 

響應信息

名稱 型別 描述
code String result code
SUCCES/ERROR
message String message
data Long vendor's product ID
vendor's product ID created

響應示例

{    
 "code": "200",    
 "message": "",    
 "data": {    
   "code": "SUCCESS",    
   "message": "",    
   "data": 7770    
 }    
}   

錯誤說明

HTTP status code (error type) 錯誤信息 solution
400 (check parameter requested) Mandatory attribute(s) of the category is missing. 此錯誤發生於缺少必要屬性時。請透過「Category Meta Data Query API」確認必要屬性的值，並正確輸入。

 
400 (check parameter requested) There is an error in the input value. line: 123 請檢查 JSON 訊息中對應的行，確認參數、數值及陣列格式是否正確。
400 (check parameter requested) Input a correct center code for return location. 請使用「Shipping & Return Location Query API」確認是否輸入了正確的中心代碼（Center Code）。
400 (check request parameter)

 Invalid Attribute Value(s).

Invalid purchase option value or unit exists.

Invalid Attribute Value(s).屬性值無效。

The data format or unit value is invalid. Please check the valid value types via the Category Metadata Query API.
400 (check request parameter) The value of attributeValueName is incorrect. Please enter the acceptable values as following the error spec guide.

請確認是否為有效的尿布階段（Diaper Stage）。

 

若為市面上其他既有階段，每個已註冊商品最多僅可新增一個值。

Allowed values:

Stage 1, Stage 2, Stage 3, Stage 4, Stage 5, Stage 6, Stage 7, Newborn (NB), Small (S), Medium (M), Large (L), Extra Large (XL), Jumbo (2XL), Super Jumbo (3XL)
400 (check parameter requested) java.lang.NullPointerException 請檢查請求的 JSON 訊息中是否存在拼寫錯誤。
400 (check parameter requested) Mandatory notification information inputted [example) Manufacturer & Marketing Authorization Holder] is different from that in the Category [example) Cosmetics] 當通知資訊（即顯示資訊）有誤時，會發生此錯誤。 請透過查詢分類中繼資料（Category Meta Data），確認輸入的顯示資訊（"notices": []）是否正確。
400 (check parameter requested) If the shipping fee type is conditional free shipping w/ threshold of 19800 won or higher, then Conditional Free is 19800 won and initial shipping fee is 0 won.  當設定 freeShipOverAmount 為 19800 時，請確認初始運費（deliveryChargeOnReturn）是否設為「0」。
400 (check parameter requested) Check [Courier Code] → 當配送地點設定為離島或山區時，僅可使用已註冊且允許偏遠地區配送（remoteAreaDeliverable: "Y"）的物流公司。

 
400 (check parameter requested) UNAUTHORIZATION 此錯誤是由於驗證資訊不正確所造成。請確認是否已正確完成身分驗證。
400 (check request parameter) Please check the delivery method. 若選擇海外代購（AGENT_BUY），請確認配送地址是否為海外地址。無法選擇韓國國內的配送地址。
400 (check request parameter) If the delivery method is a purchasing agent(AGENT_BUY), Coupang makes it mandatory for customers to enter PCCC for delivery. 若選擇海外代購（AGENT_BUY），請確認 pccNeeded 參數已設為 true。
400 (check request parameter) bundleInfo cannot be changed. bundleInfo 在初次註冊後不可變更。若需修改，將視為新商品，必須重新進行商品註冊。