v2.product.add_item｜快工助手

stable本次发布有变化全部展示

来自 Shopee 官方资料快照 · 2026-09-06 12:14:12

打开官方原文 ↗

当前资料结构化阅读页
固定快照已留存，可追溯
官方原文可核对

查看技术与溯源信息

平台 / profile: Shopee / profile.shopee.api_reference
语言: en-US
发布版本: cn-20260909-2
标签: zhuge/sourceplatform/shopeeaudience/developercategory/api_doctopic/apitopic/developer

资料正文

§1 v2.product.add_item

Add a new item.

§2 Overview

Overview

Field	Value
Module	Product
API type	Shop
HTTP method	POST
Path	/api/v2/product/add_item
Production URL	https://partner.shopeemobile.com/api/v2/product/add_item
Sandbox URL	https://partner.test-stable.shopeemobile.com/api/v2/product/add_item
Rate limit	[0, 0, 0]
Permission	ERP System; Seller In House System; Product Management; Swam ERP

§3 Request parameters

Request parameters

Name	Type	Required	Sample	Description
original_price	float	Yes		Item price
description	string	Yes	item description test	if description_type is normal , Description information should be set by this field.
weight	float	Yes		The weight of this item, the unit is KG.
item_name	string	Yes	Item Name Example	Item name
item_status	string	No	UNLIST	Item status, could be UNLIST or NORMAL
dimension	object	No		The dimension of this item.
dimension.package_height	int32	Yes		The height of package for this item, the unit is CM.
dimension.package_length	int32	Yes		The length of package for this item, the unit is CM.
dimension.package_width	int32	Yes		The width of package for this item, the unit is CM.
logistic_info	object[]	Yes		Logistic channel setting
logistic_info.size_id	int32	No		Size ID, If specify logistic fee_type is SIZE_SELECTION size_id is required.
logistic_info.shipping_fee	float	No		Shipping fee, Only needed when logistics fee_type = CUSTOM_PRICE.
logistic_info.enabled	boolean	Yes	true	Whether channel is enabled for this item
logistic_info.logistic_id	int32	Yes		ID of the channel
logistic_info.is_free	boolean	No	false	Whether cover shipping fee for buyer
attribute_list	object[]	No		This field is optional(expect Indonesia) depending on the specific attribute under different categories. Should call shopee.item.GetAttributes to get attribute first. Must contain all all mandatory attribute.
attribute_list.attribute_id	int32	Yes		ID of attribute
attribute_list.attribute_value_list	object[]	No
attribute_list.attribute_value_list.value_id	int32	Yes	32142	Value ID. In the following cases, the value id needs to be uploaded as 0, and original_value_name is mandatory, needs to be filled in customized value. (1) AttributeInputType is TEXT_FILED; (2) AttributeInputType is COMBO_BOX or MULTIPLE_SELECT_COMBO_BOX, and the seller want to fill in a customized value.
attribute_list.attribute_value_list.original_value_name	string	No	Brand	Value name. original_value_name from product.get_attributes api. If value id=0, this field is required. If AttributeType is DATE_TYPE or TIMESTAMP_TYPE, you can upload timestamp(string type) as the original_value_name.
attribute_list.attribute_value_list.value_unit	string	No	kg	Unit of attribute value (quantitative attribute only).
category_id	int32	Yes		ID of category
image	object	Yes		Item images
image.image_id_list	string[]	Yes		ID of image
image.image_ratio	string	No		Ratio of image, OptionalAllowed ratios : "1:1" (default) "3:4"; only applicable to whitelisted seller.
pre_order	object	No		Pre order setting
pre_order.is_pre_order	boolean	Yes	false	Whether item is pre order
pre_order.days_to_ship	int32	No	3	The guaranteed days to ship orders. Please get the days_to_ship range from get_dts_limit api
item_sku	string	No		SKU tag of item
condition	string	No	NEW	Condition of item, USED、Used and used will be mapped to Used; NEW、New and new will be mapped to New. Required for BR.
wholesale	object[]	No		Wholesale setting
wholesale.min_count	int32	Yes	1	Minimum count of this tier
wholesale.max_count	int32	Yes	100	Maximum count of this tier
wholesale.unit_price	float	Yes	28.3	Unit price of this tier
video_upload_id	string[]	No	["sg_f4bde9bc-ff3c-485e-a6dd-3161dab4b942_000000"]	Video upload ID returned from video uploading API. Only accept one video_upload_id.
brand	object	No
brand.brand_id	int32	Yes	0	Id of brand.
brand.original_brand_name	string	Yes	nike	Original name of brand( No Brand if not brand).
item_dangerous	int32	No	0	This field is only applicable for local sellers in Indonesia and Malaysia. Use this field to identify whether a product is a dangerous product. 0 for non-dangerous product and 1 for dangerous product. For more information, please visit the market's respective Seller Education Hub.
tax_info	object	No		Tax information
tax_info.ncm	string	No		Mercosur Common Nomenclature, it is a convention between Mercosur member countries to easily recognize goods, services and productive factors negotiated among themselves. (BR region); NCM must have 8 digits, OR, if your item doesn't have a NCM enter the value "00"
tax_info.same_state_cfop	string	No		Tax Code of Operations and Installments for orders that seller and buyer are in the same state. It identifies a specific operation by category at the time of issuing the invoice.(BR region)
tax_info.diff_state_cfop	string	No		Tax Code of Operations and Installments for orders that seller and buyer are in different states. It identifies a specific operation by category at the time of issuing the invoice.(BR region)
tax_info.csosn	string	No		Code of Operation Status – Simples Nacional, code for company operations to identify the origin of the goods and the taxation regime of the operations.(BR region)
tax_info.origin	string	No		Product source, domestic or foreig (BR region).; \|0 - National, except for those indicated in codes 3, 4, 5, and 8\| \|1 - Foreign: Direct import, except for that indicated in code 6\| \|2 - Foreign: Acquired in the domestic market, except for that indicated in code 7\| \|3 - National: Goods or products with Import Content greater than 40% and less than or equal to 70%\| \|4 - National: Produced in compliance with the basic production processes outlined in the legislations cited in the Agreements\| \|5 - National: Goods or products with Import Content less than or equal to 40%\| \|6 - Foreign: Direct import, without a national equivalent, listed by CAMEX and natural gas\| \|7 - Foreign: Acquired in the domestic market, without a national equivalent, listed by CAMEX and natural gas\| \|8 - National: Goods or products with Import Content greater than 70%\|
tax_info.cest	string	No		Tax Replacement Specifying Code (CEST), to separate within the same NCM products that do or do not have ICMS tax substitution. (BR region) CEST must have 7 digits, OR, if your item doesn't have a CEST enter the value "00".
tax_info.measure_unit	string	No		(BR region); The value must be provided in uppercase and must match one of the supported units below: AMPOLA, BALDE, BANDEJ, BARRA, BISNAG, BLOCO, BOBINA, BOMB, CAPS, CART, CENTO, CJ, CM, CM2, CX, CX2, CX3, CX5, CX10, CX15, CX20, CX25, CX50, CX100, DISP, DUZIA, EMBAL, FARDO, FOLHA, FRASCO, GALAO, GF, GRAMAS, JOGO, KG, KIT, LATA, LITRO, M, M2, M3, MILHEI, ML, MWH, PACOTE, PALETE, PARES, PC, POTE, K, RESMA, ROLO, SACO, SACOLA, TAMBOR, TANQUE, TON, TUBO, UN, VASIL, VIDRO.
tax_info.tax_type	int32	No		tax_type only for TW whitelist shop. Shopee will referred Tax type when substitute sellers for issuing e-receipts to buyers. All variations share the same tax type. The meaning of value: 0: no tax type; 1: tax-able; 2: tax-free
tax_info.pis	string	No		Only for BR shop.; PIS - Programa de Integração Social (Social Integration Program). It is a government tax to collect resources for the payment of unemployment insurance and other employee related rights.; PIS % - the tax applied to this product
tax_info.cofins	string	No		Only for BR shop.; COFINS – Contribuição para Financiamento da Seguridade Social (Contribution for Social Security Funding). It is a government tax to collect resources for public health system and social security.; COFINS % - the tax applied to this product
tax_info.icms_cst	string	No		Only for BR shop.; ICMS - Imposto sobre Circulação de Mercadorias e Serviços (Circulation of Goods and Services Tax).; CST - Código da Situação Tributária (Tax Situation Code) is represented by a combination of 3 numbers with the purpose of demonstrating the origin of a product and determining the form of taxation that will apply to it. Therefore, each digit in the CST Table has a specific meaning: the first digit indicates the origin of the operation, the second digit represents the ICMS taxation on the operation and the third digit provides additional information about the form of taxation.
tax_info.pis_cofins_cst	string	No		Only for BR shop.; The CST PIS/Cofins is a code on the Electronic Invoice (NF-e) that identifies the tax situation of PIS (Programa de Integração Social) and Cofins (Contribuição para o Financiamento da Seguridade Social) in sales of goods.
tax_info.federal_state_taxes	string	No		Only for BR shop.; Enter the total percentage of the combination of federal, state, and municipal taxes, using up to two decimals.
tax_info.operation_type	string	No		Only for BR shop.; 1: Retailer; 2: Manufacturer
tax_info.ex_tipi	string	No		Only for BR shop.; The EXTIPI field in the NF-e (Nota Fiscal Eletrônica) is used to indicate if there's an exception to the IPI (Imposto sobre Produtos Industrializados) tax rate for a specific product.
tax_info.fci_num	string	No		Only for BR shop.; The FCI Control Number is a unique identifier assigned to each import FCI (Import Content Form). It's mandatory on the corresponding NF-e (electronic invoice) to ensure compliance with Brazilian import tax regulations.
tax_info.recopi_num	string	No		Only for BR shop.; RECOPI NACIONAL is a Brazilian government system that facilitates the registration and management of tax-exempt operations involving paper destined for printing books, newspapers, and periodicals (known as "papel imune" in Portuguese).
tax_info.additional_info	string	No		Only for BR shop.; Include relevant information to display on Invoice.
tax_info.group_item_info	object	No		Only for BR shop.; Required if the item is a group item.
tax_info.group_item_info.group_qtd	string	No		Example: The package contains 6 soda cans. Whether you are selling a pack of 6 cans (fardo) or a single can (unit), enter 6.
tax_info.group_item_info.group_unit	string	No		Example: The package contains 6 soda cans. Whether you are selling a pack of 6 cans (fardo) or a single can (unit), enter UNI for the individual can.
tax_info.group_item_info.group_unit_value	string	No		Example: The package contains 6 soda cans. Whether you are selling a pack of 6 cans (fardo) or a single can (unity), enter the value of the individual can.
tax_info.group_item_info.original_group_price	string	No		Example: The item is a package that contains 6 soda cans. Enter the price of the whole package.
tax_info.group_item_info.group_gtin_sscc	string	No		Example: The item is a package that contains 6 soda cans. Please inform the GTIN SSCC code for the package.
tax_info.group_item_info.group_grai_gtin_sscc	string	No		Example: The item is box, that contain 6 packages. Each package contains 6 soda cans. Please inform the GRAI GTIN SSCC code for the Box.
tax_info.export_cfop	string	No	7101	[BR region]; 7101 - for sales of self-produced goods; 7102 - resale of third-party goods
complaint_policy	object	No		Complaint Policy for item. Only required for local PL sellers, ignored otherwise.
complaint_policy.warranty_time	string	No		Value should be in one of ONE_YEAR TWO_YEARS OVER_TWO_YEARS.
complaint_policy.exclude_entrepreneur_warranty	boolean	No		Whether to exclude warranty complaints for entrepreneurs.If True means "I exclude warranty complaints for entrepreneur"
complaint_policy.complaint_address_id	int64	No		Address for complaint. Fetch available addresses using v2.logistics.get_address_list, and use address_id returned from it.
complaint_policy.additional_information	string	No		Additional information for warranty claim. Should be less than 1000 characters.
description_info	object	No		New description field. Only whitelist sellers can use it. If you use the field, please upload the description_type=extended otherwise api will return error. If you don't use this field, you don't need to upload the description_type or upload description_type=normal
description_info.extended_description	object	No		If description_type is extended , Description information should be set by this field.
description_info.extended_description.field_list	object[]	No		Field of extended description.
description_info.extended_description.field_list.field_type	string	No		Type of extended description field ：values: See Data Definition- description_field_type (text , image).
description_info.extended_description.field_list.text	string	No		If field_type is text， text information will be set by this field.
description_info.extended_description.field_list.image_info	object	No		If field_type is image，image url will be set by this field.
description_info.extended_description.field_list.image_info.image_id	string	No		Image id.
description_type	string	No		Values: See Data Definition- description_type (normal , extended). If you want to use extended_description, this field must be inputed
seller_stock	object[]	No		seller stock（Please notice that stock(including Seller Stock and Shopee Stock) should be larger than or equal to real-time reserved stock）
seller_stock.location_id	string	No		location id
seller_stock.stock	int32	Yes		stock
gtin_code	string	No		- GTIN is an identifier for trade items, developed by the international organization GS1. - They have 8 to 14 digits. The most common are UPC, EAN, JAN and ISBN. - GTIN will help boost positioning in online marketing channels like Google and Facebook. - That incorporation with GTIN will also aid in Search and Recommendation in Shopee itself allowing buyers to have higher likelihood of finding one's listing.; Note: If you want to set “Item without GTIN”, please pass the gtin_code as "00". The validation rule is based on the value return in gtin_validation_rule" field in v2.product.get_item_limit API; - Mandatory: This field is required and must contain a correctly formatted GTiN number.; - Flexible: This field is required and must contain either a correctly formatted GTlN number or "00" to declare that the item/model has no valid GTlN. - Optional: This field is optional and can contain a correctly formatted GTiN number, "00" or be omitted entirely.
ds_cat_rcmd_id	string	No		category recommendation service id
promotion_images	object	No		Promotion Image Currently only allow one promoton image You could set promotion image only if the product images' ratio is 3:4
promotion_images.image_id_list	string[]	No		Promotion Image
compatibility_info	object	No
compatibility_info.vehicle_info_list	object[]	Yes
compatibility_info.vehicle_info_list.brand_id	int64	Yes	1234	ID of the brand.
compatibility_info.vehicle_info_list.model_id	int64	Yes	2345	ID of the model.
compatibility_info.vehicle_info_list.year_id	int64	No	3456	ID of the year.
compatibility_info.vehicle_info_list.version_id	int64	No	4567	ID of the version.
scheduled_publish_time	timestamp	No	1733590920	Scheduled publish time of this item: 1) Can only set scheduled_publish_time for item with UNLIST status; 2) Can only set the time from current time +1hour to current time +90days, and the time is only allowed to be accurate to the minute
authorised_brand_id	int64	No		ID of authorised reseller brand.
size_chart_info	object	No
size_chart_info.size_chart	string	No		ID of size chart image. If you want to remove the image size chart of the item, please pass the "size_chart" empty.; You only need to fill out either the image or template. If both are filled, only the template will be kept.; Notes: Both CB shops and local shops are supported to set "size_chart".
size_chart_info.size_chart_id	int64	No		ID of template size chart. If you want to remove the template size chart of the item, please pass the "size_chart_id" as 0.; You only need to fill out either the image or template. If both are filled, only the template will be kept.; Notes: Only local shops are supported to set "size_chart_id", for CB shops please use "size_chart".
certification_info	object	No		For PH product certification input Required for some category and attribute option
certification_info.certification_list	object[]	No		Array of certification records for the product, each containing type, certificate number, permit ID, and proof documents.
certification_info.certification_list.certification_no	string	Yes		Certification No.
certification_info.certification_list.permit_id	int64	Yes		Permit ID, get from v2.product.get_product_certification_rule
certification_info.certification_list.expiry_date	int32	No	1610000000	Expiry timestamp. Required for PH, but not needed for TW.
certification_info.certification_list.certification_proofs	object[]	Yes		An array of proof documents for the certification; each element represents one proof file.<path></path>
certification_info.certification_list.certification_proofs.file_name	string	Yes		The name of the uploaded certification proof file.
certification_info.certification_list.certification_proofs.image_id	int32	Yes		The unique image ID of the certification proof, returned by the image upload API.
certification_info.certification_list.certification_proofs.ratio	float	Yes		image weight/ image height Will be optional in the future; can input 0.75 by default
purchase_limit_info	object	No		purchase limit info
purchase_limit_info.min_purchase_limit	int32	No		minimum purchase count for each order
purchase_limit_info.max_purchase_limit	object	No
purchase_limit_info.max_purchase_limit.purchase_limit	int32	No		maximum purchase limit for each order.
medicine_id	int64	No		[Only for ID local sellers] as a unique identifier for each standardized medicine, the medicine id can only be obtained offline

§4 Response parameters

Response parameters

Name	Type	Required	Sample	Description
message	string	Yes		Indicate error details if hit error. Empty if no error happened.
warning	string	Yes		Indicate waring details if hit waring. Empty if no waring happened.
request_id	string	Yes	98eae35efff24dd0974c21a847127184	The identifier for an API request for error tracking
response	object	Yes
response.description	string	Yes	description	Description of item
response.weight	float	Yes	1.1	The weight of this item, the unit is KG.
response.pre_order	object	Yes		Pre order setting
response.pre_order.days_to_ship	int32	Yes		The guaranteed days to ship orders.
response.pre_order.is_pre_order	boolean	Yes	false	Whether this item is pre order
response.item_name	string	Yes	Hello Product	Item name
response.images	object	Yes		Item images
response.images.image_id_list	string[]	Yes		ID of image
response.images.image_url_list	string[]	Yes		Display URL of image
response.item_status	string	Yes	NORMAL	Item status
response.price_info	object	Yes		Item price info
response.price_info.current_price	float	Yes	148.02	Current price of item
response.price_info.original_price	float	Yes	148.02	Original price of item
response.logistic_info	object[]	Yes		Logistic setting
response.logistic_info.size_id	int32	Yes		Size ID
response.logistic_info.shipping_fee	float	Yes		Shipping fee
response.logistic_info.enabled	boolean	Yes	false	Whether this channel is enabled for this item
response.logistic_info.logistic_id	int32	Yes		Logistic channel ID
response.logistic_info.is_free	boolean	Yes	false	Whether cover shipping fee for buyer
response.item_id	int64	Yes		Item ID
response.attribute	object[]	Yes		Item attributes
response.attribute.attribute_id	int32	Yes		Attribute ID
response.attribute.attribute_value_list	object[]
response.attribute.attribute_value_list.original_value_name	string		Samsung ID	Value name
response.attribute.attribute_value_list.value_id	int32		32142	Value ID
response.attribute.attribute_value_list.value_unit	string		kg	Unit of attribute value
response.category_id	int32	Yes		Category ID
response.dimension	object	Yes		The dimension of this item.
response.dimension.package_width	int32	Yes		The width of package for this item, the unit is CM.
response.dimension.package_length	int32	Yes		The length of package for this item, the unit is CM.
response.dimension.package_height	int32	Yes		The height of package for this item, the unit is CM.
response.condition	string	Yes	NEW	Item condition, could be NEW or USED
response.video_info	object[]			Item video
response.video_info.video_url	string		https://cvf.shopee.sg/file/c67b847c954fd710e0d35ef1e22378d1	Video playback url
response.video_info.thumbnail_url	string		https://cf.shopee.sg/file/6fc53c203151635da72151cfbad03cdf	Video preview image url
response.video_info.duration	int32		15	Video duration
response.wholesale	object[]			Wholesale setting
response.wholesale.min_count	int32		1	Minimum count of this tier
response.wholesale.max_count	int32		100	Maximum count of this tier
response.wholesale.unit_price	float		13.3	Unit price of this tier
response.brand	object
response.brand.brand_id	int32		0	Id of brand.
response.brand.original_brand_name	string		nike	Original name of brand.
response.item_dangerous	int32		0	This field is only applicable for local sellers in Indonesia and Malaysia. Use this field to identify whether a product is a dangerous product. 0 for non-dangerous product and 1 for dangerous product. For more information, please visit the market's respective Seller Education Hub.
response.description_info	object			New description field. Only whitelist sellers can use it. If item with extended_description this field will return, otherwise do not return.
response.description_info.extended_description	object			If description_type is extended , description information should be set by this field.
response.description_info.extended_description.field_list	object[]			Field of extended description.
response.description_info.extended_description.field_list.field_type	string			Type of extended description field ：values: See Data Definition- description_field_type (text , image).
response.description_info.extended_description.field_list.text	string			If field_type is text, text information will be set by this field.
response.description_info.extended_description.field_list.image_info	object			If field_type is image, image url will be set by this field.
response.description_info.extended_description.field_list.image_info.image_id	string			Image id.
response.description_type	string			Values: See Data Definition- description_type (normal , extended).
response.complaint_policy	object			Complaint Policy for item. Only returned for local PL sellers.
response.complaint_policy.warranty_time	string		ONE_YEAR	Time for a warranty claim. Could be ONE_YEAR, TWO_YEARS, OVER_TWO_YEARS.
response.complaint_policy.exclude_entrepreneur_warranty	boolean		false	If True means "I exclude warranty complaints for entrepreneur"
response.complaint_policy.complaint_address_id	int64			The identity of complaint address.
response.complaint_policy.additional_information	string			Additional information for complaint policy.
response.seller_stock	object[]			seller stock
response.seller_stock.location_id	string			location id
response.seller_stock.stock	int32			stock
error	string	Yes		Indicate error type if hit error. Empty if no error happened.

§5 Common parameters

Common parameters

Name	Type	Sample	Description
partner_id	int	1	Partner ID is assigned upon registration is successful. Required for all requests.
timestamp	timestamp	1610000000	This is to indicate the timestamp of the request. Required for all requests. Expires in 5 minutes.
access_token	string	c09222e3fc40ffb25fc947f738b1abf1	The token for API access, using to identify your permission to the api. Valid for multiple use and expires in 4 hours.
shop_id	int	600000	Shopee's unique identifier for a shop. Required param for most APIs.
sign	string	e318d3e932719916a9f9ebb57e2011961bd47abfa54a36e040d050d8931596e2	Signature generated by partner_id, api path, timestamp, access_token, shop_id and partner_key via HMAC-SHA256 hashing algorithm. More details: https://open.shopee.com/documents?module=87&type=2&id=58&version=2

§6 Request samples

Request samples

§7 Payload

Payload

{
	"original_price": 123.3,
	"description": "item description test",
	"weight": 1.1,
	"item_name": "Item Name Example",
	"item_status": "UNLIST",
	"dimension": {
		"package_height": 11,
		"package_length": 11,
		"package_width": 11
	},
	"logistic_info": [
		{
			"size_id": 0,
			"shipping_fee": 23.12,
			"enabled": true,
			"logistic_id": 80101,
			"is_free": true
		}
	],
	"attribute_list": [
		{
			"attribute_id": 4990,
			"attribute_value_list": [
				{
					"value_id": 32142,
					"original_value_name": "Brand",
					"value_unit": " kg"
				}
			]
		}
	],
	"category_id": 14695,
	"image": {
		"image_id_list": [
			"-"
		]
	},
	"pre_order": {
		"is_pre_order": true,
		"days_to_ship": 3
	},
	"item_sku": "-",
	"condition": "NEW",
	"wholesale": [
		{
			"min_count": 1,
			"max_count": 100,
			"unit_price": 28.3
		}
	],
	"video_upload_id": [
		"sg_f4bde9bc-ff3c-485e-a6dd-3161dab4b942_000000"
	],
	"brand": {
		"brand_id": 0,
		"original_brand_name": "nike"
	},
	"item_dangerous": 0,
	"tax_info": {
		"ncm": "-",
		"same_state_cfop": "-",
		"diff_state_cfop": "-",
		"csosn": "-",
		"origin": "-",
		"cest": "-",
		"measure_unit": "-",
		"invoice_option": "-",
		"vat_rate": "-"
	},
	"complaint_policy": {
		"warranty_time": "-",
		"exclude_entrepreneur_warranty": true,
		"complaint_address_id": 0,
		"additional_information": "-"
	},
	"description_info": {
		"extended_description": {
			"field_list": [
				{
					"field_type": "-",
					"text": "-",
					"image_info": {
						"image_id": "-"
					}
				}
			]
		}
	},
	"description_type": "-",
	"seller_stock": [
		{
			"location_id": "-",
			"stock": 0
		}
	]
}

§8 Java

Java

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://partner.uat.shopeemobile.com/api/v2/product/add_item?sign=sign&access_token=access_token&timestamp=timestamp&shop_id=shop_id&partner_id=partner_id")
.header("Content-Type","application/json")
.body("{
   \"attribute_list\": [
      {
         \"attribute_id\": 4990,
         \"attribute_value_list\": [
            {
               \"original_value_name\": \"Brand\",
               \"value_id\": 32142,
               \"value_unit\": \" kg\"
            }
         ]
      }
   ],
   \"brand\": {
      \"brand_id\": 0,
      \"original_brand_name\": \"nike\"
   },
   \"category_id\": 14695,
   \"complaint_policy\": {
      \"additional_information\": \"-\",
      \"complaint_address_id\": 0,
      \"exclude_entrepreneur_warranty\": true,
      \"warranty_time\": \"-\"
   },
   \"condition\": \"NEW\",
   \"description\": \"item description test\",
   \"description_info\": {
      \"extended_description\": {
         \"field_list\": [
            {
               \"field_type\": \"-\",
               \"image_info\": {
                  \"image_id\": \"-\"
               },
               \"text\": \"-\"
            }
         ]
      }
   },
   \"description_type\": \"-\",
   \"dimension\": {
      \"package_height\": 11,
      \"package_length\": 11,
      \"package_width\": 11
   },
   \"image\": {
      \"image_id_list\": [
         \"-\"
      ]
   },
   \"item_dangerous\": 0,
   \"item_name\": \"Item Name Example\",
   \"item_sku\": \"-\",
   \"item_status\": \"UNLIST\",
   \"logistic_info\": [
      {
         \"enabled\": true,
         \"is_free\": true,
         \"logistic_id\": 80101,
         \"shipping_fee\": 23.12,
         \"size_id\": 0
      }
   ],
   \"normal_stock\": 33,
   \"original_price\": 123.3,
   \"pre_order\": {
      \"days_to_ship\": 3,
      \"is_pre_order\": true
   },
   \"seller_stock\": [
      {
         \"location_id\": \"-\",
         \"stock\": 0
      }
   ],
   \"tax_info\": {
      \"cest\": \"-\",
      \"csosn\": \"-\",
      \"diff_state_cfop\": \"-\",
      \"hs_code\": \"-\",
      \"invoice_option\": \"-\",
      \"measure_unit\": \"-\",
      \"ncm\": \"-\",
      \"origin\": \"-\",
      \"same_state_cfop\": \"-\",
      \"tax_code\": \"-\",
      \"vat_rate\": \"-\"
   },
   \"video_upload_id\": [
      \"sg_f4bde9bc-ff3c-485e-a6dd-3161dab4b942_000000\"
   ],
   \"weight\": 1.1,
   \"wholesale\": [
      {
         \"max_count\": 100,
         \"min_count\": 1,
         \"unit_price\": 28.3
      }
   ]
}")
.asString();

§9 PHP

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://partner.uat.shopeemobile.com/api/v2/product/add_item?access_token=access_token&partner_id=partner_id&shop_id=shop_id&sign=sign&timestamp=timestamp',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
    "attribute_list": [
        {
            "attribute_id": 4990,
            "attribute_value_list": [
                {
                    "original_value_name": "Brand",
                    "value_id": 32142,
                    "value_unit": " kg"
                }
            ]
        }
    ],
    "brand": {
        "brand_id": 0,
        "original_brand_name": "nike"
    },
    "category_id": 14695,
    "complaint_policy": {
        "additional_information": "-",
        "complaint_address_id": 0,
        "exclude_entrepreneur_warranty": true,
        "warranty_time": "-"
    },
    "condition": "NEW",
    "description": "item description test",
    "description_info": {
        "extended_description": {
            "field_list": [
                {
                    "field_type": "-",
                    "image_info": {
                        "image_id": "-"
                    },
                    "text": "-"
                }
            ]
        }
    },
    "description_type": "-",
    "dimension": {
        "package_height": 11,
        "package_length": 11,
        "package_width": 11
    },
    "image": {
        "image_id_list": [
            "-"
        ]
    },
    "item_dangerous": 0,
    "item_name": "Item Name Example",
    "item_sku": "-",
    "item_status": "UNLIST",
    "logistic_info": [
        {
            "enabled": true,
            "is_free": true,
            "logistic_id": 80101,
            "shipping_fee": 23.12,
            "size_id": 0
        }
    ],
    "normal_stock": 33,
    "original_price": 123.3,
    "pre_order": {
        "days_to_ship": 3,
        "is_pre_order": true
    },
    "seller_stock": [
        {
            "location_id": "-",
            "stock": 0
        }
    ],
    "tax_info": {
        "cest": "-",
        "csosn": "-",
        "diff_state_cfop": "-",
        "hs_code": "-",
        "invoice_option": "-",
        "measure_unit": "-",
        "ncm": "-",
        "origin": "-",
        "same_state_cfop": "-",
        "tax_code": "-",
        "vat_rate": "-"
    },
    "video_upload_id": [
        "sg_f4bde9bc-ff3c-485e-a6dd-3161dab4b942_000000"
    ],
    "weight": 1.1,
    "wholesale": [
        {
            "max_count": 100,
            "min_count": 1,
            "unit_price": 28.3
        }
    ]
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

§10 cURL

cURL

curl --location --request POST 'https://partner.uat.shopeemobile.com/api/v2/product/add_item?access_token=access_token&timestamp=timestamp&shop_id=shop_id&partner_id=partner_id&sign=sign' \
--header 'Content-Type: application/json' \
--data-raw '{
   "attribute_list": [
      {
         "attribute_id": 4990,
         "attribute_value_list": [
            {
               "original_value_name": "Brand",
               "value_id": 32142,
               "value_unit": " kg"
            }
         ]
      }
   ],
   "brand": {
      "brand_id": 0,
      "original_brand_name": "nike"
   },
   "category_id": 14695,
   "complaint_policy": {
      "additional_information": "-",
      "complaint_address_id": 0,
      "exclude_entrepreneur_warranty": true,
      "warranty_time": "-"
   },
   "condition": "NEW",
   "description": "item description test",
   "description_info": {
      "extended_description": {
         "field_list": [
            {
               "field_type": "-",
               "image_info": {
                  "image_id": "-"
               },
               "text": "-"
            }
         ]
      }
   },
   "description_type": "-",
   "dimension": {
      "package_height": 11,
      "package_length": 11,
      "package_width": 11
   },
   "image": {
      "image_id_list": [
         "-"
      ]
   },
   "item_dangerous": 0,
   "item_name": "Item Name Example",
   "item_sku": "-",
   "item_status": "UNLIST",
   "logistic_info": [
      {
         "enabled": true,
         "is_free": true,
         "logistic_id": 80101,
         "shipping_fee": 23.12,
         "size_id": 0
      }
   ],
   "normal_stock": 33,
   "original_price": 123.3,
   "pre_order": {
      "days_to_ship": 3,
      "is_pre_order": true
   },
   "seller_stock": [
      {
         "location_id": "-",
         "stock": 0
      }
   ],
   "tax_info": {
      "cest": "-",
      "csosn": "-",
      "diff_state_cfop": "-",
      "hs_code": "-",
      "invoice_option": "-",
      "measure_unit": "-",
      "ncm": "-",
      "origin": "-",
      "same_state_cfop": "-",
      "tax_code": "-",
      "vat_rate": "-"
   },
   "video_upload_id": [
      "sg_f4bde9bc-ff3c-485e-a6dd-3161dab4b942_000000"
   ],
   "weight": 1.1,
   "wholesale": [
      {
         "max_count": 100,
         "min_count": 1,
         "unit_price": 28.3
      }
   ]
}'

§11 Python

Python

import requests
import json

url = "https://partner.uat.shopeemobile.com/api/v2/product/add_item?access_token=access_token&partner_id=partner_id&shop_id=shop_id&sign=sign&timestamp=timestamp"

payload=json.dumps({
  "attribute_list": [
    {
      "attribute_id": 4990,
      "attribute_value_list": [
        {
          "original_value_name": "Brand",
          "value_id": 32142,
          "value_unit": " kg"
        }
      ]
    }
  ],
  "brand": {
    "brand_id": 0,
    "original_brand_name": "nike"
  },
  "category_id": 14695,
  "complaint_policy": {
    "additional_information": "-",
    "complaint_address_id": 0,
    "exclude_entrepreneur_warranty": True,
    "warranty_time": "-"
  },
  "condition": "NEW",
  "description": "item description test",
  "description_info": {
    "extended_description": {
      "field_list": [
        {
          "field_type": "-",
          "image_info": {
            "image_id": "-"
          },
          "text": "-"
        }
      ]
    }
  },
  "description_type": "-",
  "dimension": {
    "package_height": 11,
    "package_length": 11,
    "package_width": 11
  },
  "image": {
    "image_id_list": [
      "-"
    ]
  },
  "item_dangerous": 0,
  "item_name": "Item Name Example",
  "item_sku": "-",
  "item_status": "UNLIST",
  "logistic_info": [
    {
      "enabled": True,
      "is_free": True,
      "logistic_id": 80101,
      "shipping_fee": 23.12,
      "size_id": 0
    }
  ],
  "normal_stock": 33,
  "original_price": 123.3,
  "pre_order": {
    "days_to_ship": 3,
    "is_pre_order": True
  },
  "seller_stock": [
    {
      "location_id": "-",
      "stock": 0
    }
  ],
  "tax_info": {
    "cest": "-",
    "csosn": "-",
    "diff_state_cfop": "-",
    "hs_code": "-",
    "invoice_option": "-",
    "measure_unit": "-",
    "ncm": "-",
    "origin": "-",
    "same_state_cfop": "-",
    "tax_code": "-",
    "vat_rate": "-"
  },
  "video_upload_id": [
    "sg_f4bde9bc-ff3c-485e-a6dd-3161dab4b942_000000"
  ],
  "weight": 1.1,
  "wholesale": [
    {
      "max_count": 100,
      "min_count": 1,
      "unit_price": 28.3
    }
  ]
})
headers = {
  'Content-Type': 'application/json'
}
response = requests.request("POST",url,headers=headers, data=payload, allow_redirects=False)

print(response.text)

§12 Response sample

Response sample

§13 JSON

JSON

{
	"message": "-",
	"warning": "-",
	"request_id": "98eae35efff24dd0974c21a847127184",
	"response": {
		"description": "description",
		"weight": 1,
		"pre_order": {
			"days_to_ship": 1,
			"is_pre_order": true
		},
		"item_name": "Hello Product",
		"images": {
			"image_id_list": [
				"-"
			],
			"image_url_list": [
				"-"
			]
		},
		"item_status": "NORMAL",
		"price_info": {
			"current_price": 148.02,
			"original_price": 148.02
		},
		"logistic_info": [
			{
				"size_id": 0,
				"shipping_fee": 0.1,
				"enabled": true,
				"logistic_id": 88014,
				"is_free": true
			}
		],
		"item_id": 3000142341,
		"attributes": [
			{
				"attribute_id": 4990,
				"attribute_value_list": [
					{
						"original_value_name": "Samsung ID",
						"value_id": 32142,
						"value_unit": "kg"
					}
				]
			}
		],
		"category_id": 14695,
		"dimension": {
			"package_width": 11,
			"package_length": 11,
			"package_height": 11
		},
		"condition": "NEW",
		"video_info": [
			{
				"video_url": "https://cvf.shopee.sg/file/c67b847c954fd710e0d35ef1e22378d1",
				"thumbnail_url": "https://cf.shopee.sg/file/6fc53c203151635da72151cfbad03cdf",
				"duration": 15
			}
		],
		"wholesale": [
			{
				"min_count": 1,
				"max_count": 100,
				"unit_price": 13.3
			}
		],
		"brand": {
			"brand_id": 0,
			"original_brand_name": "nike"
		},
		"item_dangerous": 0,
		"description_info": {
			"extended_description": {
				"field_list": [
					{
						"field_type": "-",
						"text": "-",
						"image_info": {
							"image_id": "-"
						}
					}
				]
			}
		},
		"description_type": "-",
		"complaint_policy": {
			"warranty_time": "ONE_YEAR",
			"exclude_entrepreneur_warranty": true,
			"complaint_address_id": 0,
			"additional_information": "-"
		},
		"seller_stock": [
			{
				"location_id": "-",
				"stock": 0
			}
		]
	},
	"error": "-"
}

§14 Errors

Errors

Error	Description	Solution
product.error_busi	The GTIN code is mandatory, please check and upload again.
product.error_busi	Please input the correct TS Mark (TD Mark) to upload your product, and refer to the SEH article - https://seller.shopee.tw/edu/article/19732 if you have any questions.
product.error_busi	Medicine ID is mandatory for products in Prescription/OTC category.
product.error_busi	Please input the correct medicine ID.
product.error_busi	For OTC medicine, maximum purchase limit per order is mandatory and cannot exceed 3 days of use.
product.error_busi	Upload failed, please upload a more standard size chart image.
product.error_busi	Please input the tax information becasue the shop is invoice issued by Shopee
error_network	Inner http call failed
error_data	parse data failed
error_data	data not exist
error_param	parameter invalid
error_param	The information you queried is not found.
error_param	Wrong parameters, detail: {msg}.
error_server	Something wrong. Please try later.
error_shop	shopid is invalid
error_param	request not from gateway
error_auth_shop_not_found	Shop is not found.
error_auth	cnsc shop not upgraded, can not edit item.
error_param_shop_id_not_found	Shop_id is not found.
error_param	[Gateway] illegal request.
error_param	Invalid logistic info, {{.error_info}}
error_param	Invalid category.
error_param	Invalid attribute. {{.error_info}}
error_param	Invalid wholesale setting.
error_param	Parameter is not match the constraints, {{.error_info}}.
error_param	Invalid Weight.
error_param	Image not exist.
error_invalid_days_to_ship	Invalid days_to_ship.
error_value_name_required	Value_name is required.
error_value_id_must_equal_zero	Value_id must equal 0.
error_invalid_category_attribute	Category and attribute not match.
error_busi	logistic must be free
error_invalid_brand	Invalid brand
error_invalid_brand	Brand ID value should be "0".
error_invalid_brand	Brand name required
error_invalid_brand	Brand ID required
error_incalid_brand	Brand ID or brand name required
error_invalid_attribute	Mandatory attribute information required
error_invalid_brand	Brand information required
error_param	dimension is required
error_param	invalid additional information
error_param	all BR tax field should be empty or be filled at same time
error_get_shop_fail	Get shop failed. please try later.
error_busi_add_item_failed	Add item failed. please try later {{.error_info}}.
error_busi_invalid_shop_status	Shop status invalid.
error_busi_invalid_account_status	Account status is invalid.
error_invalid_category	Invalid category ID {{.error_info}}
error_busi_attribute_error	Attribute NCC value is invalid
error_busi_attribute_error	Attribute NCC is mandatory
error_busi_attribute_error	Attribute BSMI value is invalid
error_busi_attribute_error	Attribute BSMI is mandatory
error_attribute_fda_error	Attribute FDA value is invalid
error_inner	Our system is taking some time to respond, please try later.
error_inner	System error, please try again later or contact the OpenAPI support team.
error_unknown	{{.error_info}}
error_item_not_found	Product not found
error_check_luc_fail	{{.error_info}}
error_check_luc_fail	{{.error_info}}
error_check_luc_fail	{{.error_info}}
error_check_luc_fail	{{.error_info}}
error_check_luc_fail	{{.error_info}}
error_check_luc_fail	{{.error_info}}
error_check_luc_fail	{{.error_info}}
error_check_luc_fail	{{.error_info}}
error_check_luc_fail	{{.error_info}}
error_check_luc_fail	{{.error_info}}
error_check_luc_fail	{{.error_info}}
error_repeated_mtsku	A similar product has already been uploaded
error_invalid_price	Invalid price, please use the correct format
error_category_is_block	Category is restricted
error_less_required_attribute	Mandatory attribute information required
error_less_required_brand	Brand information required
error_inner	Update item failed {{.error_info}}
error_inner	Update item failed {{.error_info}}
error_param	Attribute format is invalid. NCC field only allows Eng Alphanumeric input
error_param	NCC filed only allows character length less than 50.
error_unlist_item_fail	Please upload your products to UNLIST status. Products will be published automatically by Shopee at the official launch date.
error_invalid_logistic_info	invalid logistic info , {{.error_info}}
error_invalid_price_for_logistic	Shipping channel cannot be enabled as product price exceeds limit.
error_inner	System error, please try again later or contact the OpenAPI support team.
error_inner	System error, please try again later or contact the OpenAPI support team.
error_auth	The current item belong to the full FBS or B2C shop, so normal stock must be equal to 0
error_param_validate	This is not a valid GTIN. Please, inform a valid number.
error_param_validate	This is not a valid GTIN. Please, inform a valid number.
error_desc_image_no_pass	{{.error_info}}
error_desc_image_no_pass	{{.error_info}}
error_desc_image_no_pass	{{.error_info}}
error_desc_image_no_pass	{{.error_info}}
error_busi_cannot_edit_vsku	Can not use OpenAPI to edit/create VSKU, please connect with your manager
error_auth	The location_id input is not matched the shop's location_id(more/wrong). Please double check.
error_auth	Lack of location_id, please double check.
error_auth	Please wait for the holiday mode set then to edit item. Please try later.
error_auth	Total stock must be more than reserved stock.
error_param	{{.error_info}}
error_param_validate	Wholesale cannot be used in this category and attributes.
error_auth	Your shop can not use model level dts
error_param	{{.error_info}}
error_auth	You do not have right to use seller location_id, please only fill seller_stock filed.
error_desc_image_no_pass	{{.error_info}}
error_desc_image_no_pass	{{.error_info}}
error_desc_image_no_pass	{{.error_info}}
error_desc_image_no_pass	{{.error_info}}
error_param	{{.error_info}}
error.param	Can not update item with stock less than reserved stock
error_inner	Invalid stock location ID
error_param	Can not update item with different stock structure. Can only update seller stock with location id when existing seller stock have location id. Can only update seller stock without location id when existing seller stock without location id.
error_param	Can not update item with stock less than reserve stock
error_busi	The merchant/shop has multi warehouse, please input location id
error_auth	Stock should be larger than reserved stock.
error_incalid_brand	{{.error_info}}
error_duplicated_brand	Brand already exists
error_marshal	Interal error, please contact openapi team
error_param	Invalid parameter for product.
error_system_busy	Our system is taking some time to respond, please try later.
error_image_unavailable	Image is invalid: single image url length is less than 32.
error_reach_shop_item_limit	Item published item count reaches limit.
error_name_length_limit	Exceeded item_name length limitation.
error_nil_shopid_or_itemid	Query information failed.
error_desc_hash_tag_over_limit	Count of hash tags is more than 18
error_item_name_empty	Item name could not be empty.
error_holiday_on_add_item	Shop is under vocation mode.
error_nil_name_new_item	Item_name cannot be empty.
error_item_name_is_too_short	Item_name length is less than min limit.
error_title_exceeds_max_length	The length of item_name is bigger than max limit.
error_title_character_forbidden	Item_name contains forbidden characters.
error_desc_length_min_limit	Description length is less than the min limit.
error_image_num_min	{{.error_info}}
error_forbidden_category	The category is forbidden.
error_brand_forbidden	The brand is forbidden.
error_param_dts_exceeds_max_limit	Days_to_ship exceeds max limit
error_price_exceed_min_limitt	Original_price is less than min price limit.
error_price_exceed_max_limitt	Original_price is bigger than max price limit.
error_wholesale_price_less_than_ratio_limit	Wholesale price is less than ratio limit.
error_param_category_not_support_pre_order	Category does not support pre-order.
error_param	Can not update item with different stock structure. Can only update seller stock with location id when existing seller stock have location id. Can only update seller stock without location id when existing seller stock without location id.
error_invalid_attribute_value	Invalid attribute value.
error_wrong_attrsnapshot	Invalid attribute.
error_category_level	Interal error, please contact openapi team.
error_category_path_count_limit	Interal error, please contact openapi team.
error_server	Interal error, please contact openapi team.
error_invalid_category	Invalid category.
error_incalid_category	Category IDs for L1 and L2 do not match.
error_category_dts	The current day_to_ship is bigger than category's max days_to_ship.
error_invalid_category	Category is blocked for CB seller.
error_whole_sale_min_count_incorrect	Interal error, please contact openapi team.
error_whole_sale_price_setting_incorrect	Wholesale price can't more than original price.
error_video_info_not_found	Video_info not found.

§15 Common errors

Common errors

Error	Description	Solution
error_auth	partner_id is invalid
error_auth	The App is deleted, and you'll be unable to make any API call.
error_auth	App developer’s permissions for authorizations have been restricted. If you’re a seller, contact the developer for more information. If you’re the developer, refer to the Open Platform Console for details.
error_param	There is no partner_id in query.
error_param	Invalid partner_id.
error_param	no timestamp
error_param	Invalid timestamp
error_param	There is no sign in query.
error_sign	Wrong sign.
invalid_partner_id	Invalid partner_id, please have a check.
error_auth	No permission to current api.
error_api_call_restricted	The App permission for api call have been restricted. If you’re a seller, contact the developer for more information. If you’re the developer, refer to the Open Platform Console for details.
api_suspended	The API is offline. Please call v2 API instead.
error_limit	The total API call number made by your APP has reached the daily API call limit, please try again after 00: 00 (UTC+08:00)
error_rate_limit	Too many requests. You have reached the rate limit. Please try again later.
source_ip_undeclared	Request Source IP ({ip}) is undeclared. Please declare all your IP addresses in the Shopee Open Platform Console > App list > IP Address Whitelist
error_param	Permission denied. This API is currently offline or the request path is incorrect.
error_param	Partner_id is invalid, should be an integer between 0 and 4294967295.
error_param	no timestamp.
error_param	Timestamp is invalid, should be an integer between 0 and 4294967295.
error_param	Timestamp is expired.
error_partner_key_expired	Your API partner key has expired, please reset the Live API Partner Key in Console to get a new valid partner key to call open api.
error_api_permission	This app type has no permission to this API.
error_param	There is no access_token in query.
error_auth	Invalid access_token.
error_auth	Invalid partner_id or shopid.
shop_no_linked	Partner and shop has no linked.
shop_banned	The shop account has been banned. Permissions for shop authorization and API calls have been suspended until the shop account is restored.
invalid_acceess_token	Invalid access_token, please have a check.
partner_shop_no_link	Invalid partner_id or shop_id, please have a check.
error_ashop_api_permission	The shop is Affiliate shop has no permission to call this API.
error_kyc_auth	No permission. Please inform the seller to complete the Seller Registration on Shopee Seller Center first, then this shop can call for this API.
error_auth	System error, please try again later.
error_param	There is no shop_id in query.
error_param	shop_id is invalid, should be an integer between 0 and 4294967295.

§16 Update log

Update log

Date	Change
2026-09-01	Condition is required for BR
2026-06-24	2026-06-17
2026-03-13	Introduce "medicine_id" as the request parameter
2025-09-19	The request field certification_type has been removed. If this field is still passed in the request, it will be ignored by the system.
2025-04-28	Add permit_id

这条内容对你有帮助吗？