VI | EN
Message us on Messenger
Developer resources

Add a new item. — Shopee API

v2.product.add_item · call it through Quantri360 with one API key for your own accounts / assets that you connected and authorized — 360 handles request signing and refreshing the authorization you granted.

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_item unlist = 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

NameInTypeSampleDescription
AuthorizationheaderheaderBearer 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_idquerystring100001Gian 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

NameInTypeRequiredSampleDescription
item_namebodystringYesSản phẩm mẫuTên — độ dài theo get_item_limit (VN: 20–120 ký tự).
descriptionbodystringYesChân váy dáng A, chất tuytsi…Mô tả chữ (VN: 100–5000 ký tự).
category_idbodyintYes100102Ngành hàng LÁ (get_category / category_recommend).
original_pricebodyfloatYes300000Giá 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.
weightbodyfloatYes0.5Cân nặng (kg).
dimensionbodyobjectNo{"package_length":25,"package_width":20,"package_height":10}Kích thước gói (cm, số nguyên).
imagebodyobjectYes{"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_infobodyobject[]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_statusbodystringNoUNLISTUNLIST (tạo ẩn) · NORMAL (đăng bán ngay).
attribute_listbodyobject[]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_stockbodyobject[]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_skubodystringNoSản phẩm mẫuSKU cha.
conditionbodystringNoNEWNEW · USED.
brandbodyobjectNo{"brand_id":0,"original_brand_name":"NoBrand"}brand_id từ get_brand_list; không thương hiệu: 0 + "NoBrand".
pre_orderbodyobjectNo{"is_pre_order":false,"days_to_ship":2}Hàng đặt trước + số ngày chuẩn bị hàng.
size_chart_infobodyobjectNo{"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).
wholesalebodyobject[]NoGiá sỉ theo bậc: min_count, max_count, unit_price.
video_upload_idbodystring[]NoMã video đã tải lên (một video).
description_typebodystringNonormalnormal (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)

NameTypeSampleDescription
request_idstringd52ca43b277a4f9292fb8be658bfd33dMã request của Shopee để tra lỗi.
errorstringMã lỗi Shopee; rỗng = thành công.
messagestringMô tả lỗi.
warningstring
responseobjectSản phẩm vừa tạo.
item_idint10000000093Mã sản phẩm mới — dùng cho init_tier_variation / update_item.
item_namestring
item_statusstringUNLIST
category_idint100102
price_infoobjectoriginal_price, current_price.
imagesobjectimage_id_list, image_url_list.
logistic_infoobject[]Kênh vận chuyển đã lưu.
attributeobject[]Thuộc tính đã lưu.
seller_stockobject[]Tồn đã lưu.
weightfloat0.5
dimensionobject
brandobject
pre_orderobject
conditionstringNEW
descriptionstring

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
CodeMeaning
product.error_busiThe GTIN code is mandatory, please check and upload again.
error_dataDữ 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_paramTham số sai / thiếu / sai kiểu — xem `message` để biết tham số nào.
error_serverLỗi hệ thống Shopee — thử lại sau ít phút.
error_shopGian hàng không hợp lệ — kiểm tra platform_shop_id.
error_auth_shop_not_foundKhô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_foundShop_id is not found.
error_invalid_days_to_shipSố ngày chuẩn bị hàng không hợp lệ.
error_value_name_requiredValue_name is required.
error_value_id_must_equal_zeroValue_id must equal 0.
error_invalid_category_attributeNgành hàng không khớp thuộc tính.
error_busiMerchant/gian hàng có nhiều kho; cần gửi location_id.
error_invalid_brandThông tin nhãn hàng thiếu hoặc không hợp lệ; xem `message`.
error_incalid_brandThông tin nhãn hàng thiếu hoặc không hợp lệ; xem `message`.
error_invalid_attributeThiếu thuộc tính bắt buộc.
error_get_shop_failKhông lấy được gian hàng; thử lại sau.
error_busi_add_item_failedAdd item failed. please try later {{.error_info}}.
error_busi_invalid_shop_statusShop status invalid.
error_busi_invalid_account_statusAccount status is invalid.
error_invalid_categoryMã ngành hàng không hợp lệ; xem `message`.
error_busi_attribute_errorThuộc tính chứng nhận NCC/BSMI thiếu hoặc không hợp lệ; xem `message`.
error_attribute_fda_errorGiá trị thuộc tính FDA không hợp lệ.
error_innerLỗi hệ thống Shopee — thử lại sau.
error_unknown{{.error_info}}
error_item_not_foundKhông tìm thấy item_id.
error_check_luc_failKiểm tra LUC thất bại; xem `message`.
error_repeated_mtskuSản phẩm tương tự đã được tải lên.
error_invalid_priceInvalid price, please use the correct format
error_category_is_blockNgành hàng bị hạn chế.
error_less_required_attributeThiếu thuộc tính bắt buộc.
error_less_required_brandThiếu thông tin nhãn hàng bắt buộc.
error_unlist_item_failPlease upload your products to UNLIST status. Products will be published automatically by Shopee at the official launch date.
error_invalid_logistic_infoinvalid logistic info , {{.error_info}}
error_invalid_price_for_logisticShipping channel cannot be enabled as product price exceeds limit.
error_param_validateThiế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_vskuCan not use OpenAPI to edit/create VSKU, please connect with your manager
error.paramCan not update item with stock less than reserved stock
error_duplicated_brandNhãn hàng đã tồn tại.
error_marshalInteral error, please contact openapi team
error_system_busyHệ thống đang bận; thử lại sau.
error_image_unavailableẢnh không khả dụng; xem `message`.
error_reach_shop_item_limitItem published item count reaches limit.
error_name_length_limitExceeded item_name length limitation.
error_nil_shopid_or_itemidQuery information failed.
error_desc_hash_tag_over_limitCount of hash tags is more than 18
error_item_name_emptyItem name could not be empty.
error_holiday_on_add_itemShop is under vocation mode.
error_nil_name_new_itemItem_name cannot be empty.
error_item_name_is_too_shortItem_name length is less than min limit.
error_title_exceeds_max_lengthThe length of item_name is bigger than max limit.
error_title_character_forbiddenItem_name contains forbidden characters.
error_desc_length_min_limitDescription length is less than the min limit.
error_image_num_minSố ảnh chưa đạt mức tối thiểu; xem `message`.
error_forbidden_categoryThe category is forbidden.
error_brand_forbiddenThe brand is forbidden.
error_param_dts_exceeds_max_limitDays_to_ship exceeds max limit
error_price_exceed_min_limittOriginal_price is less than min price limit.
error_price_exceed_max_limittOriginal_price is bigger than max price limit.
error_wholesale_price_less_than_ratio_limitWholesale price is less than ratio limit.
error_param_category_not_support_pre_orderCategory does not support pre-order.
error_invalid_attribute_valueInvalid attribute value.
error_wrong_attrsnapshotInvalid attribute.
error_category_levelInteral error, please contact openapi team.
error_category_path_count_limitInteral error, please contact openapi team.
error_incalid_categoryMã ngành hàng cấp 1 và cấp 2 không khớp.
error_category_dtsThe current day_to_ship is bigger than category's max days_to_ship.
error_whole_sale_min_count_incorrectInteral error, please contact openapi team.
error_whole_sale_price_setting_incorrectWholesale price can't more than original price.
error_video_info_not_foundVideo_info not found.
error_limitChạ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_limitGọ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_bannedGian hàng đang bị Shopee khóa — mọi API tạm ngưng tới khi gỡ khóa.
error_kyc_authGian hàng chưa hoàn tất đăng ký người bán trên Kênh Người Bán.

Get started

  1. Sign up for Partner
  2. Enable a data type of the Sản phẩm group on the platform page
  3. Create an API key (tick the Shopee channel)
  4. Call it as in the examples above