v2.product.add_item

POST /api/v2/product/add_item

Add a new item.

Endpoint URL

URL: https://partner.shopeemobile.com/api/v2/product/add_item

Common Request 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

Request Parameters

Name	Type	Required	Sample	Description
original_price	float	True	123.3	Item price
description	string	True	item description test	if description_type is normal , Description information should be set by this field.
weight	float	True	1.1	The weight of this item, the unit is KG.
item_name	string	True	Item Name Example	Item name
item_status	string	False	UNLIST	Item status, could be UNLIST or NORMAL
dimension	object	False		The dimension of this item.
package_height	int32	True	11	The height of package for this item, the unit is CM.
package_length	int32	True	11	The length of package for this item, the unit is CM.
package_width	int32	True	11	The width of package for this item, the unit is CM.
logistic_info	object[]	True		Logistic channel setting
size_id	int32	False	0	Size ID, If specify logistic fee_type is SIZE_SELECTION size_id is required.
shipping_fee	float	False	23.12	Shipping fee, Only needed when logistics fee_type = CUSTOM_PRICE.
enabled	boolean	True	true	Whether channel is enabled for this item
logistic_id	int32	True	80101	ID of the channel
is_free	boolean	False	false	Whether cover shipping fee for buyer
attribute_list	object[]	False		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_id	int32	True	4990	ID of attribute
attribute_value_list	object[]	False
value_id	int32	True	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.
original_value_name	string	False	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.
value_unit	string	False	kg	Unit of attribute value (quantitative attribute only).
category_id	int32	True	14695	ID of category
image	object	True		Item images
image_id_list	string[]	True		ID of image
image_ratio	string	False		Ratio of image, OptionalAllowed ratios : "1:1" (default)  "3:4" only applicable to whitelisted seller.
pre_order	object	False		Pre order setting
is_pre_order	boolean	True	false	Whether item is pre order
days_to_ship	int32	False	3	The guaranteed days to ship orders. Please get the days_to_ship range from get_dts_limit api
item_sku	string	False		SKU tag of item
condition	string	False	NEW	Condition of item, could be USED or NEW
wholesale	object[]	False		Wholesale setting
min_count	int32	True	1	Minimum count of this tier
max_count	int32	True	100	Maximum count of this tier
unit_price	float	True	28.3	Unit price of this tier
video_upload_id	string[]	False	["sg_f4bde9bc-ff3c-485e-a6dd-3161dab4b942_000000"]	Video upload ID returned from video uploading API. Only accept one video_upload_id.
brand	object	False
brand_id	int32	True	0	Id of brand.
original_brand_name	string	True	nike	Original name of brand( No Brand if not brand).
item_dangerous	int32	False	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	False		Tax information
ncm	string	False		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"
same_state_cfop	string	False		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)
diff_state_cfop	string	False		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)
csosn	string	False		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)
origin	string	False		Product source, domestic or foreig (BR region).
cest	string	False		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".
measure_unit	string	False		(BR region)
tax_type	int32	False		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
pis	string	False		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
cofins	string	False		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
icms_cst	string	False		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.
pis_cofins_cst	string	False		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.
federal_state_taxes	string	False		Only for BR shop. Enter the total percentage of the combination of federal, state, and municipal taxes, using up to two decimals.
operation_type	string	False		Only for BR shop. 1: Retailer 2: Manufacturer
ex_tipi	string	False		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.
fci_num	string	False		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.
recopi_num	string	False		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).
additional_info	string	False		Only for BR shop. Include relevant information to display on Invoice.
group_item_info	object	False		Only for BR shop. Required if the item is a group item.
group_qtd	string	False		Example: The package contains 6 soda cans. Whether you are selling a pack of 6 cans (fardo) or a single can (unit), enter 6.
group_unit	string	False		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.
group_unit_value	string	False		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.
original_group_price	string	False		Example: The item is a package that contains 6 soda cans. Enter the price of the whole package.
group_gtin_sscc	string	False		Example: The item is a package that contains 6 soda cans. Please inform the GTIN SSCC code for the package.
group_grai_gtin_sscc	string	False		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.
export_cfop	string	False	7101	[BR region] 7101 - for sales of self-produced goods 7102 - resale of third-party goods
complaint_policy	object	False		Complaint Policy for item. Only required for local PL sellers, ignored otherwise.
warranty_time	string	False		Value should be in one of ONE_YEAR TWO_YEARS OVER_TWO_YEARS.
exclude_entrepreneur_warranty	boolean	False		Whether to exclude warranty complaints for entrepreneurs.If True means "I exclude warranty complaints for entrepreneur"
complaint_address_id	int64	False		Address for complaint. Fetch available addresses using v2.logistics.get_address_list, and use address_id returned from it.
additional_information	string	False		Additional information for warranty claim. Should be less than 1000 characters.
description_info	object	False		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
extended_description	object	False		If description_type is extended , Description information should be set by this field.
field_list	object[]	False		Field of extended description.
field_type	string	False		Type of extended description field ：values: See Data Definition- description_field_type (text , image).
text	string	False		If field_type is text， text information will be set by this field.
image_info	object	False		If field_type is image，image url will be set by this field.
image_id	string	False		Image id.
description_type	string	False		Values: See Data Definition- description_type (normal , extended). If you want to use extended_description, this field must be inputed
seller_stock	object[]	False		seller stock（Please notice that stock(including Seller Stock and Shopee Stock) should be larger than or equal to real-time reserved stock）
location_id	string	False		location id
stock	int32	True		stock
gtin_code	string	False		- 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	False		category recommendation service id
promotion_images	object	False		Promotion Image Currently only allow one promoton image You could set promotion image only if the product images' ratio is 3:4
image_id_list	string[]	False		Promotion Image
compatibility_info	object	False
vehicle_info_list	object[]	True
brand_id	int64	True	1234	ID of the brand.
model_id	int64	True	2345	ID of the model.
year_id	int64	False	3456	ID of the year.
version_id	int64	False	4567	ID of the version.
scheduled_publish_time	timestamp	False	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	False		ID of authorised reseller brand.
size_chart_info	object	False
size_chart	string	False		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_id	int64	False		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	False		For PH product certification input Required for some category and attribute option
certification_list	object[]	False		Array of certification records for the product, each containing type, certificate number, permit ID, and proof documents.
certification_no	string	True		Certification No.
permit_id	int64	True		Permit ID, get from v2.product.get_product_certification_rule
expiry_date	int32	False	1610000000	Expiry timestamp. Required for PH, but not needed for TW.
certification_proofs	object[]	True		An array of proof documents for the certification; each element represents one proof file.<path></path>
file_name	string	True		The name of the uploaded certification proof file.
image_id	int32	True		The unique image ID of the certification proof, returned by the image upload API.
ratio	float	True		image weight/ image height Will be optional in the future; can input 0.75 by default
purchase_limit_info	object	False		purchase limit info
min_purchase_limit	int32	False		minimum purchase count for each order
max_purchase_limit	object	False
purchase_limit	int32	False		maximum purchase limit for each order.
medicine_id	int64	False		[Only for ID local sellers] as a unique identifier for each standardized medicine, the medicine id can only be obtained offline

Response Parameters

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