v2.product.add_item
POST/api/v2/product/add_itemVia 360: POST https://partner.quantri360.com/v1/shopee/api/v2/product/add_item
Write endpoint — changes data on Shopee. The key must be created with "Allow write API calls" ticked, otherwise you get 403 write_not_allowed. Every call is logged.
Description
TẠO SẢN PHẨM MỚI trên gian hàng: tên, mô tả, ngành, thuộc tính, ảnh (image_id đã tải lên), giá, tồn, cân nặng / kích thước, kênh vận chuyển, thương hiệu. Sản phẩm có phân loại: tạo xong gọi tiếp init_tier_variation.
- Là API GHI — thay đổi dữ liệu thật trên Shopee; key cần quyền ghi. Gọi bằng POST, body JSON.
- Ảnh phải tải lên Shopee trước (media_space/upload_image) — không nhận link ảnh ngoài.
- Luồng đăng sản phẩm có phân loại 360 đang dùng: add_item với
item_status = UNLIST→ chờ ≥ 5 giây → init_tier_variation → lỗi thì xóa sản phẩm vừa tạo (delete_item) để không để lại sản phẩm thiếu phân loại → muốn mở bán thì unlist_itemunlist = false. - Gửi thiếu một kênh vận chuyển gian hàng bắt buộc bật → lỗi "cannot disable a force-enabled channel" (kể cả khi get_channel_list báo force_enable = false). Cách chắc ăn: gửi đúng các kênh đang bật trên một sản phẩm đang bán (logistic_info của get_item_base_info).
error_repeated_mtsku= Shopee coi là trùng một sản phẩm đã có trên gian hàng.
Request
Endpoint
POST https://partner.quantri360.com/v1/shopee/api/v2/product/add_item
Authentication & shop
| Name | In | Type | Sample | Description |
|---|---|---|---|---|
| Authorization | header | header | Bearer q360_live_ab12cd34_… | Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand. |
| platform_shop_id | query | string | 100001 | Gian hàng (lấy ở GET /v1/platforms → shops[].platform_shop_id). BẮT BUỘC khi brand có > 1 gian hàng trên nền tảng; 360 bỏ tham số này trước khi chuyển tiếp. |
Request parameters
| Name | In | Type | Required | Sample | Description |
|---|---|---|---|---|---|
| item_name | body | string | Yes | Sản phẩm mẫu | Tên — độ dài theo get_item_limit (VN: 20–120 ký tự). |
| description | body | string | Yes | Chân váy dáng A, chất tuytsi… | Mô tả chữ (VN: 100–5000 ký tự). |
| category_id | body | int | Yes | 100102 | Ngành hàng LÁ (get_category / category_recommend). |
| original_price | body | float | Yes | 300000 | Giá gốc (VND, số nguyên). Sản phẩm có phân loại: giá thật đặt ở từng phân loại trong init_tier_variation. |
| weight | body | float | Yes | 0.5 | Cân nặng (kg). |
| dimension | body | object | No | {"package_length":25,"package_width":20,"package_height":10} | Kích thước gói (cm, số nguyên). |
| image | body | object | Yes | {"image_id_list":["vn-10000000092-7r98o-lxm45esiq5zt3b"]} | image_id_list: mã ảnh trả về từ media_space/upload_image (1–9 ảnh, ảnh đầu = ảnh bìa); image_ratio 1:1 (mặc định) hoặc 3:4. |
| logistic_info | body | object[] | Yes | [{"logistic_id":5001,"enabled":true}] | Kênh vận chuyển: logistic_id (get_channel_list), enabled, tùy chọn is_free, size_id, shipping_fee. |
| item_status | body | string | No | UNLIST | UNLIST (tạo ẩn) · NORMAL (đăng bán ngay). |
| attribute_list | body | object[] | No | [{"attribute_id":100134,"attribute_value_list":[{"value_id":0,"original_value_name":"Tuytsi"}]}] | Thuộc tính: mã từ get_attribute_tree; giá trị tự gõ gửi value_id = 0 + original_value_name. Phải đủ thuộc tính bắt buộc của ngành. |
| seller_stock | body | object[] | No | [{"location_id":"VNZ","stock":10}] | Tồn (sản phẩm không phân loại): stock, kèm location_id (get_warehouse_detail) khi gian hàng nhiều kho. |
| item_sku | body | string | No | Sản phẩm mẫu | SKU cha. |
| condition | body | string | No | NEW | NEW · USED. |
| brand | body | object | No | {"brand_id":0,"original_brand_name":"NoBrand"} | brand_id từ get_brand_list; không thương hiệu: 0 + "NoBrand". |
| pre_order | body | object | No | {"is_pre_order":false,"days_to_ship":2} | Hàng đặt trước + số ngày chuẩn bị hàng. |
| size_chart_info | body | object | No | {"size_chart_id":10000000096} | Bảng size: size_chart (mã ảnh) hoặc size_chart_id (bảng dạng mẫu, get_size_chart_list). |
| wholesale | body | object[] | No | Giá sỉ theo bậc: min_count, max_count, unit_price. | |
| video_upload_id | body | string[] | No | Mã video đã tải lên (một video). | |
| description_type | body | string | No | normal | normal (dùng description) · extended (dùng description_info, chỉ gian hàng được Shopee mở). |
Request examples
curl -s -X POST "https://partner.quantri360.com/v1/shopee/api/v2/product/add_item" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"item_name":"Sản phẩm mẫu","description":"Chân váy dáng A thiết kế túi hộp, chất tuytsi cao cấp. Màu xanh đậm, xanh nhạt. Size S, M, L, XL. Giặt nước lạnh, không dùng chất tẩy có Clo, phơi trong bóng râm.","category_id":100102,"original_price":300000,"weight":0.5,"dimension":{"package_length":25,"package_width":20,"package_height":10},"image":{"image_id_list":["vn-10000000092-7r98o-lxm45esiq5zt3b"]},"logistic_info":[{"logistic_id":5001,"enabled":true}],"item_status":"UNLIST","condition":"NEW","attribute_list":[{"attribute_id":100134,"attribute_value_list":[{"value_id":0,"original_value_name":"Tuytsi"}]}],"brand":{"brand_id":0,"original_brand_name":"NoBrand"},"seller_stock":[{"location_id":"VNZ","stock":0}],"item_sku":"Sản phẩm mẫu"}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/shopee/api/v2/product/add_item",
params={},
json={
"item_name": "Sản phẩm mẫu",
"description": "Chân váy dáng A thiết kế túi hộp, chất tuytsi cao cấp. Màu xanh đậm, xanh nhạt. Size S, M, L, XL. Giặt nước lạnh, không dùng chất tẩy có Clo, phơi trong bóng râm.",
"category_id": 100102,
"original_price": 300000,
"weight": 0.5,
"dimension": {
"package_length": 25,
"package_width": 20,
"package_height": 10
},
"image": {
"image_id_list": [
"vn-10000000092-7r98o-lxm45esiq5zt3b"
]
},
"logistic_info": [
{
"logistic_id": 5001,
"enabled": True
}
],
"item_status": "UNLIST",
"condition": "NEW",
"attribute_list": [
{
"attribute_id": 100134,
"attribute_value_list": [
{
"value_id": 0,
"original_value_name": "Tuytsi"
}
]
}
],
"brand": {
"brand_id": 0,
"original_brand_name": "NoBrand"
},
"seller_stock": [
{
"location_id": "VNZ",
"stock": 0
}
],
"item_sku": "Sản phẩm mẫu"
},
headers={"Authorization": f"Bearer {KEY}"},
timeout=60,
)
print(r.status_code)
print(r.json())Node.js
const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/shopee/api/v2/product/add_item');
for (const [k, v] of Object.entries({})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({"item_name":"Sản phẩm mẫu","description":"Chân váy dáng A thiết kế túi hộp, chất tuytsi cao cấp. Màu xanh đậm, xanh nhạt. Size S, M, L, XL. Giặt nước lạnh, không dùng chất tẩy có Clo, phơi trong bóng râm.","category_id":100102,"original_price":300000,"weight":0.5,"dimension":{"package_length":25,"package_width":20,"package_height":10},"image":{"image_id_list":["vn-10000000092-7r98o-lxm45esiq5zt3b"]},"logistic_info":[{"logistic_id":5001,"enabled":true}],"item_status":"UNLIST","condition":"NEW","attribute_list":[{"attribute_id":100134,"attribute_value_list":[{"value_id":0,"original_value_name":"Tuytsi"}]}],"brand":{"brand_id":0,"original_brand_name":"NoBrand"},"seller_stock":[{"location_id":"VNZ","stock":0}],"item_sku":"Sản phẩm mẫu"}),
});
console.log(r.status, await r.json());PHP
<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/shopee/api/v2/product/add_item' . '?' . http_build_query([]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key, 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"item_name":"Sản phẩm mẫu","description":"Chân váy dáng A thiết kế túi hộp, chất tuytsi cao cấp. Màu xanh đậm, xanh nhạt. Size S, M, L, XL. Giặt nước lạnh, không dùng chất tẩy có Clo, phơi trong bóng râm.","category_id":100102,"original_price":300000,"weight":0.5,"dimension":{"package_length":25,"package_width":20,"package_height":10},"image":{"image_id_list":["vn-10000000092-7r98o-lxm45esiq5zt3b"]},"logistic_info":[{"logistic_id":5001,"enabled":true}],"item_status":"UNLIST","condition":"NEW","attribute_list":[{"attribute_id":100134,"attribute_value_list":[{"value_id":0,"original_value_name":"Tuytsi"}]}],"brand":{"brand_id":0,"original_brand_name":"NoBrand"},"seller_stock":[{"location_id":"VNZ","stock":0}],"item_sku":"Sản phẩm mẫu"}');
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;Response
Response fields (as returned by Shopee)
| Name | Type | Sample | Description |
|---|---|---|---|
| request_id | string | d52ca43b277a4f9292fb8be658bfd33d | Mã request của Shopee để tra lỗi. |
| error | string | Mã lỗi Shopee; rỗng = thành công. | |
| message | string | Mô tả lỗi. | |
| warning | string | ||
| response | object | Sản phẩm vừa tạo. | |
| item_id | int | 10000000093 | Mã sản phẩm mới — dùng cho init_tier_variation / update_item. |
| item_name | string | ||
| item_status | string | UNLIST | |
| category_id | int | 100102 | |
| price_info | object | original_price, current_price. | |
| images | object | image_id_list, image_url_list. | |
| logistic_info | object[] | Kênh vận chuyển đã lưu. | |
| attribute | object[] | Thuộc tính đã lưu. | |
| seller_stock | object[] | Tồn đã lưu. | |
| weight | float | 0.5 | |
| dimension | object | ||
| brand | object | ||
| pre_order | object | ||
| condition | string | NEW | |
| description | string |
Response sample
{
"error": "",
"message": "",
"warning": "",
"request_id": "98eae35efff24dd0…",
"response": {
"item_id": 10000000093,
"item_name": "Sản phẩm mẫu",
"item_status": "UNLIST",
"category_id": 100102,
"price_info": {
"original_price": 300000,
"current_price": 300000
},
"images": {
"image_id_list": [
"vn-10000000092-7r98o-lxm45esiq5zt3b"
],
"image_url_list": [
"https://example.com/anh-mau.jpg"
]
},
"logistic_info": [
{
"logistic_id": 5001,
"enabled": true,
"is_free": false,
"size_id": 0
}
],
"weight": 0.5,
"dimension": {
"package_length": 25,
"package_width": 20,
"package_height": 10
},
"condition": "NEW",
"brand": {
"brand_id": 0,
"original_brand_name": "NoBrand"
},
"pre_order": {
"is_pre_order": false,
"days_to_ship": 2
},
"seller_stock": [
{
"location_id": "VNZ",
"stock": 0
}
]
}
}
Shopee error codes (75)
Show
| Code | Meaning |
|---|---|
| product.error_busi | The GTIN code is mandatory, please check and upload again. |
| error_data | Dữ liệu không tồn tại hoặc không hợp lệ cho thao tác (vd mã không có, loại yêu cầu không cho phép). |
| error_param | Tham số sai / thiếu / sai kiểu — xem `message` để biết tham số nào. |
| error_server | Lỗi hệ thống Shopee — thử lại sau ít phút. |
| error_shop | Gian hàng không hợp lệ — kiểm tra platform_shop_id. |
| error_auth_shop_not_found | Không tìm thấy gian hàng — kiểm tra platform_shop_id. |
| error_auth | Ủy quyền gian hàng cho 360 đã hết hạn hoặc bị thu hồi (360 đã tự làm mới token một lần) — chủ gian hàng kết nối lại Shopee trong Partner. |
| error_param_shop_id_not_found | Shop_id is not found. |
| error_invalid_days_to_ship | Số ngày chuẩn bị hàng không hợp lệ. |
| error_value_name_required | Value_name is required. |
| error_value_id_must_equal_zero | Value_id must equal 0. |
| error_invalid_category_attribute | Ngành hàng không khớp thuộc tính. |
| error_busi | Merchant/gian hàng có nhiều kho; cần gửi location_id. |
| error_invalid_brand | Thông tin nhãn hàng thiếu hoặc không hợp lệ; xem `message`. |
| error_incalid_brand | Thông tin nhãn hàng thiếu hoặc không hợp lệ; xem `message`. |
| error_invalid_attribute | Thiếu thuộc tính bắt buộc. |
| error_get_shop_fail | Không lấy được gian hàng; thử lại sau. |
| 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 | Mã ngành hàng không hợp lệ; xem `message`. |
| error_busi_attribute_error | Thuộc tính chứng nhận NCC/BSMI thiếu hoặc không hợp lệ; xem `message`. |
| error_attribute_fda_error | Giá trị thuộc tính FDA không hợp lệ. |
| error_inner | Lỗi hệ thống Shopee — thử lại sau. |
| error_unknown | {{.error_info}} |
| error_item_not_found | Không tìm thấy item_id. |
| error_check_luc_fail | Kiểm tra LUC thất bại; xem `message`. |
| error_repeated_mtsku | Sản phẩm tương tự đã được tải lên. |
| error_invalid_price | Invalid price, please use the correct format |
| error_category_is_block | Ngành hàng bị hạn chế. |
| error_less_required_attribute | Thiếu thuộc tính bắt buộc. |
| error_less_required_brand | Thiếu thông tin nhãn hàng bắt buộc. |
| 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_param_validate | Thiết lập bán sỉ hoặc thị trường của merchant chưa hợp lệ; xem `message`. |
| error_desc_image_no_pass | Ảnh mô tả chưa được chấp nhận; xem `message`. |
| error_busi_cannot_edit_vsku | Can not use OpenAPI to edit/create VSKU, please connect with your manager |
| error.param | Can not update item with stock less than reserved stock |
| error_duplicated_brand | Nhãn hàng đã tồn tại. |
| error_marshal | Interal error, please contact openapi team |
| error_system_busy | Hệ thống đang bận; thử lại sau. |
| error_image_unavailable | Ảnh không khả dụng; xem `message`. |
| 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 | Số ảnh chưa đạt mức tối thiểu; xem `message`. |
| 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_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_incalid_category | Mã ngành hàng cấp 1 và cấp 2 không khớp. |
| error_category_dts | The current day_to_ship is bigger than category's max days_to_ship. |
| 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. |
| error_limit | Chạm hạn mức gọi Shopee trong ngày của kết nối — 360 trả kèm thời điểm thử lại; giảm tần suất gọi. |
| error_rate_limit | Gọi quá nhanh — chờ vài giây rồi gọi lại (360 cũng giới hạn theo key: 429 + Retry-After). |
| shop_banned | Gian hàng đang bị Shopee khóa — mọi API tạm ngưng tới khi gỡ khóa. |
| error_kyc_auth | Gian hàng chưa hoàn tất đăng ký người bán trên Kênh Người Bán. |
Get started
- Sign up for Partner
- Enable a data type of the Sản phẩm group on the platform page
- Create an API key (tick the Shopee channel)
- Call it as in the examples above