v2.product.batch_add_item

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

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

打开官方原文 ↗

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

查看技术与溯源信息

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

资料正文

§1 v2.product.batch_add_item

Create asynchronous task to batch add item

§2 Overview

Overview

Field	Value
Module	Product
API type	Shop
HTTP method	POST
Path	/api/v2/product/batch_add_item
Production URL	https://partner.shopeemobile.com/api/v2/product/batch_add_item
Sandbox URL	https://partner.test-stable.shopeemobile.com/api/v2/product/batch_add_item
Permission	ERP System; Seller In House System; Product Management

§3 Request parameters

Request parameters

Name	Type	Required	Sample	Description
item_list	object[]	Yes		The item list to batch add. The list size must be between 1 and 100.
item_list.original_price	float	Yes		Item price
item_list.description	string	Yes	item description test	if description_type is normal , Description information should be set by this field.
item_list.weight	float	Yes		The weight of this item, the unit is KG.
item_list.item_name	string	Yes	Item Name Example	Item name
item_list.item_status	string	No	UNLIST	Item status, could be UNLIST or NORMAL
item_list.dimension	object	No		The dimension of this item.
item_list.dimension.package_height	int32	Yes		The height of package for this item, the unit is CM.
item_list.dimension.package_length	int32	Yes		The length of package for this item, the unit is CM.
item_list.dimension.package_width	int32	Yes		The width of package for this item, the unit is CM.
item_list.logistic_info	object[]	Yes		Logistic channel setting
item_list.logistic_info.size_id	int32	No		Size ID, If specify logistic fee_type is SIZE_SELECTION size_id is required.
item_list.logistic_info.shipping_fee	float	No		Shipping fee, Only needed when logistics fee_type = CUSTOM_PRICE.
item_list.logistic_info.enabled	boolean	Yes	true	Whether channel is enabled for this item
item_list.logistic_info.logistic_id	int32	Yes		ID of the channel
item_list.logistic_info.is_free	boolean	No	false	Whether cover shipping fee for buyer
item_list.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.
item_list.attribute_list.attribute_id	int32	Yes		ID of attribute
item_list.attribute_list.attribute_value_list	object[]	No
item_list.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.
item_list.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.
item_list.attribute_list.attribute_value_list.value_unit	string	No	kg	Unit of attribute value (quantitative attribute only).
item_list.category_id	int32	Yes		ID of category
item_list.image	object	Yes		Item images
item_list.image.image_id_list	string[]	Yes		ID of image
item_list.image.image_ratio	string	No		Ratio of image, OptionalAllowed ratios : "1:1" (default) "3:4"; only applicable to whitelisted seller.
item_list.pre_order	object	No		Pre order setting
item_list.pre_order.is_pre_order	boolean	Yes	false	Whether item is pre order
item_list.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_list.item_sku	string	No		SKU tag of item
item_list.condition	string	No	NEW	Condition of item, could be USED or NEW
item_list.wholesale	object[]	No		Wholesale setting
item_list.wholesale.min_count	int32	Yes	1	Minimum count of this tier
item_list.wholesale.max_count	int32	Yes	100	Maximum count of this tier
item_list.wholesale.unit_price	float	Yes	28.3	Unit price of this tier
item_list.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.
item_list.brand	object	No
item_list.brand.brand_id	int32	Yes	0	Id of brand.
item_list.brand.original_brand_name	string	Yes	nike	Original name of brand( No Brand if not brand).
item_list.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.
item_list.tax_info	object	No		Tax information
item_list.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"
item_list.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)
item_list.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)
item_list.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)
item_list.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%\|
item_list.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".
item_list.tax_info.measure_unit	string	No		(BR region)
item_list.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
item_list.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
item_list.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
item_list.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.
item_list.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.
item_list.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.
item_list.tax_info.operation_type	string	No		Only for BR shop.; 1: Retailer; 2: Manufacturer
item_list.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.
item_list.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.
item_list.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).
item_list.tax_info.additional_info	string	No		Only for BR shop.; Include relevant information to display on Invoice.
item_list.tax_info.group_item_info	object	No		Only for BR shop.; Required if the item is a group item.
item_list.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.
item_list.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.
item_list.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.
item_list.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.
item_list.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.
item_list.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.
item_list.tax_info.export_cfop	string	No	7101	[BR region]; 7101 - for sales of self-produced goods; 7102 - resale of third-party goods
item_list.complaint_policy	object	No		Complaint Policy for item. Only required for local PL sellers, ignored otherwise.
item_list.complaint_policy.warranty_time	string	No		Value should be in one of ONE_YEAR TWO_YEARS OVER_TWO_YEARS.
item_list.complaint_policy.exclude_entrepreneur_warranty	boolean	No		Whether to exclude warranty complaints for entrepreneurs.If True means "I exclude warranty complaints for entrepreneur"
item_list.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.
item_list.complaint_policy.additional_information	string	No		Additional information for warranty claim. Should be less than 1000 characters.
item_list.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
item_list.description_info.extended_description	object	No		If description_type is extended , Description information should be set by this field.
item_list.description_info.extended_description.field_list	object[]	No		Field of extended description.
item_list.description_info.extended_description.field_list.field_type	string	No		Type of extended description field ：values: See Data Definition- description_field_type (text , image).
item_list.description_info.extended_description.field_list.text	string	No		If field_type is text， text information will be set by this field.
item_list.description_info.extended_description.field_list.image_info	object	No		If field_type is image，image url will be set by this field.
item_list.description_info.extended_description.field_list.image_info.image_id	string	No		Image id.
item_list.description_type	string	No		Values: See Data Definition- description_type (normal , extended). If you want to use extended_description, this field must be inputed
item_list.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）
item_list.seller_stock.location_id	string	No		location id
item_list.seller_stock.stock	int32	Yes		stock
item_list.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.
item_list.ds_cat_rcmd_id	string	No		category recommendation service id
item_list.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
item_list.promotion_images.image_id_list	string[]	No		Promotion Image
item_list.compatibility_info	object	No
item_list.compatibility_info.vehicle_info_list	object[]	Yes
item_list.compatibility_info.vehicle_info_list.brand_id	int64	Yes	1234	ID of the brand.
item_list.compatibility_info.vehicle_info_list.model_id	int64	Yes	2345	ID of the model.
item_list.compatibility_info.vehicle_info_list.year_id	int64	No	3456	ID of the year.
item_list.compatibility_info.vehicle_info_list.version_id	int64	No	4567	ID of the version.
item_list.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
item_list.authorised_brand_id	int64	No		ID of authorised reseller brand.
item_list.size_chart_info	object	No
item_list.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".
item_list.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".
item_list.certification_info	object	No		For PH product certification input Required for some category and attribute option
item_list.certification_info.certification_list	object[]	No		Array of certification records for the product, each containing type, certificate number, permit ID, and proof documents.
item_list.certification_info.certification_list.certification_no	string	Yes		Certification No.
item_list.certification_info.certification_list.permit_id	int64	Yes		Permit ID, get from v2.product.get_product_certification_rule
item_list.certification_info.certification_list.expiry_date	int32	No	1610000000	Expiry timestamp. Required for PH, but not needed for TW.
item_list.certification_info.certification_list.certification_proofs	object[]	Yes		An array of proof documents for the certification; each element represents one proof file.<path></path>
item_list.certification_info.certification_list.certification_proofs.file_name	string	Yes		The name of the uploaded certification proof file.
item_list.certification_info.certification_list.certification_proofs.image_id	int32	Yes		The unique image ID of the certification proof, returned by the image upload API.
item_list.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
item_list.purchase_limit_info	object	No		purchase limit info
item_list.purchase_limit_info.min_purchase_limit	int32	No		minimum purchase count for each order
item_list.purchase_limit_info.max_purchase_limit	object	No
item_list.purchase_limit_info.max_purchase_limit.purchase_limit	int32	No		maximum purchase limit for each order.
item_list.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	Description
error	string	Indicate error type if hit error. Empty if no error happened.
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	The identifier for an API request for error tracking.
response	object
response.task_id	int64	The task ID of the batch add item task.

§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

{
	"item_list": [
		{
			"category_id": 100017,
			"item_name": "Example Item 1",
			"description": "Example item description 1",
			"item_sku": "SKU-001",
			"image": {
				"image_id_list": [
					"c54265d475b85e00ffb2404585e32b6f"
				]
			},
			"tier_variation": [
				{
					"name": "Color",
					"option_list": [
						{
							"option": "Red"
						},
						{
							"option": "Blue"
						}
					]
				}
			],
			"model_list": [
				{
					"model_sku": "SKU-001-RED",
					"original_price": 12.34,
					"seller_stock": [
						{
							"location_id": "SGZ",
							"stock": 100
						}
					],
					"tier_index": [
						0
					]
				},
				{
					"model_sku": "SKU-001-BLUE",
					"original_price": 13.34,
					"seller_stock": [
						{
							"location_id": "SGZ",
							"stock": 80
						}
					],
					"tier_index": [
						1
					]
				}
			],
			"weight": 1.2,
			"dimension": {
				"package_length": 10,
				"package_width": 8,
				"package_height": 5
			},
			"logistic_info": [
				{
					"logistic_id": 50001,
					"enabled": true
				}
			],
			"brand": {
				"brand_id": 0
			}
		},
		{
			"category_id": 100017,
			"item_name": "Example Item 2",
			"description": "Example item description 2",
			"item_sku": "SKU-002",
			"image": {
				"image_id_list": [
					"6fb33d484f232510b5f9b169f2758322"
				]
			},
			"tier_variation": [
				{
					"name": "Size",
					"option_list": [
						{
							"option": "M"
						},
						{
							"option": "L"
						}
					]
				}
			],
			"model_list": [
				{
					"model_sku": "SKU-002-M",
					"original_price": 15.99,
					"seller_stock": [
						{
							"location_id": "SGZ",
							"stock": 60
						}
					],
					"tier_index": [
						0
					]
				},
				{
					"model_sku": "SKU-002-L",
					"original_price": 16.99,
					"seller_stock": [
						{
							"location_id": "SGZ",
							"stock": 40
						}
					],
					"tier_index": [
						1
					]
				}
			],
			"weight": 1.5,
			"dimension": {
				"package_length": 12,
				"package_width": 9,
				"package_height": 6
			},
			"logistic_info": [
				{
					"logistic_id": 50001,
					"enabled": true
				}
			],
			"brand": {
				"brand_id": 0
			}
		}
	]
}

§8 Response sample

Response sample

§9 JSON

JSON

{
	"error": "",
	"message": "",
	"warning": "",
	"request_id": "f9f2c3d4e5f6a7b8",
	"response": {
		"task_id": 900000004
	}
}

§10 Error example

Error example

§11 JSON

JSON

{
    "error": "product.error_param",
    "message": "shop_id not found",
    "warning": "",
    "request_id": "e3e3e7f3549798db60beb2604da2f600"
}

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

§13 Update log

Update log

Date	Change
-	New API

这条内容对你有帮助吗？