Upload products via a file URL
POST/catalog/product/file/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/catalog/product/file/
Write endpoint — changes data on TikTok Business. The key must be created with "Allow write API calls" ticked, otherwise you get 403 write_not_allowed. Every call is logged.
Description
Use this endpoint to upload products via a file URL. Products will be added or updated to the catalog asynchronously. In the response, you will get a task processing ID feed_log_id. With this ID you can view the processing status and final results of the task via the /catalog/product/log/ endpoint.
Use this endpoint, rather than /catalog/product/upload/, for the initial upload of products to a catalog, or for the regular full upload of products to a catalog with the update frequency of once a day.
Currently, the API only supports CSV file format for Catalog Feeds. CSV Catalog Feed templates are available for different types of catalogs as below:
- Template for E-commerce catalogs
- Template for hotel catalogs
- Template for flight catalogs
- Template for destination catalogs
- Template for entertainment catalogs
- Template for Auto-Inventory catalogs
- Template for Auto-Model catalogs
- Template for mini series catalogs
- Template for generic catalogs
- Template for online-to-offline catalogs
Product images (image_link) must be 500x500 px or larger in size. Otherwise, the product will not be approved. For details, see Product Image Requirements.
> Note
>
- Entertainment catalogs are currently an allowlist-only feature and is invitation-only because the catalog type is under Alpha Testing. If you would like to access it, please contact your TikTok representative. However, acceptance into the Alpha Test is not guaranteed.
- The mini series catalog is currently an allowlist-only feature and is invitation-only because the catalog type is under testing. If you would like to access it, please contact your TikTok representative. However, acceptance into the test is not guaranteed.
- The SKU is unique under the same product catalog and only belongs to a certain feed. All operations on a SKU need to be performed under the feed to which it belongs.
- A feed can only handle one file task at the same time, and new tasks will fail if the current file task is not complete. Please wait for the current task to complete before sending the next task. The processing speed for products is about 5 million entries per hour, which is impacted by service load and is for reference only.
Request
Endpoint
POST https://partner.quantri360.com/v1/tiktok_business/catalog/product/file/
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 | 7000000000000000001 | Tài sản TikTok Business đã kết nối — "Mã tài sản" ở trang Nền tảng hoặc GET /v1/platforms (tài khoản quảng cáo cho Marketing API, tài khoản TikTok cho Organic / Messaging). Có thể bỏ khi chỉ kết nối một tài sản. |
Request parameters
| Name | In | Type | Required | Sample | Description |
|---|---|---|---|---|---|
| bc_id | body | string | Yes | Business Center ID. | |
| catalog_id | body | string | Yes | Catalog ID. | |
| feed_id | body | string | No | Feed ID. | |
| file_url | body | string | Yes | The download address of the CSV file. The number of product lines in the file should be less than 20 million.
- Currently, the API only allows CSV file type Catalog Feeds. CSV Catalog Feed templates are available for different types of catalogs as below:
- Template for E-commerce catalogs
- Template for hotel catalogs
- When your CSV file contains alias fields, the system will automatically map these fields to their corresponding existing fields. To learn more about the alias fields and their related existing fields, see Alias fields for hotel catalogs.
- Template for flight catalogs
- When your CSV file contains alias fields, the system will automatically map these fields to their corresponding existing fields. To learn more about the alias fields and their related existing fields, see Alias fields for flight catalogs.
- Template for destination catalogs
- Template for entertainment catalogs
- Template for Auto-Inventory catalogs
- Template for Auto-Model catalogs
- Template for mini series catalogs
- Template for generic catalogs
- To learn about the detailed parameters and available values for the generic catalog CSV feed template, see Generic catalog CSV feed parameters.
- Template for online-to-offline catalogs
- To learn about the detailed parameters and available values for online to offline CSV feed template, see O2O catalog CSV feed parameters.To learn about the detailed introduction of each catalog product parameter, see products object array parameters.
To understand how a field and its corresponding value in JSON format are represented in the CSV template, see Comparison of Catalog Product Parameters in JSON Format & CSV Template.
- Product images (image_link) must be 500 x 500 pixels or larger in size. Otherwise, the product will not be approved. For details, see Product Image Requirements.
Note:
- To upload short drama series that target multiple regions to a short drama catalog, call /catalog/product/file/ multiple times with the same series_id and different country settings. After the uploads, access the consolidated targeting settings for the same short drama series through target_config and additional_product_list in /catalog/product/get/.
- For example, separate uploads with country set to US (same as the primary targeting region for the short drama catalog) and VN (same as one of the additional targeting regions) results in list.target_config.region_code as US and list.additional_product_list.region_code as VN in /catalog/product/get/.
- If your additional image URL contains commas (,), URL-encode them by replacing with %2C before adding them to this field.
For example, for URLs such as you need to set this field to ["]. | |
| update_mode | body | string | No | Update mode. The mode is one-time only and only applies to the current request.
Enum values:
- OVERWRITE: In this mode, all the products in the catalog will be replaced by the products in the file you specify.
- INCREMENTAL: In this mode, the products in the file you specify will be added to the catalog. Note that if you upload a product already in the catalog with a duplicate SKU ID via the file, the data for the product in the catalog will be replaced.Default value: INCREMENTAL.
Note: If you pass in feed_id, the update mode you specify via this field will not affect the update mode of the feed. |
Request examples
curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/catalog/product/file/" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"bc_id":"","catalog_id":"","file_url":""}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/tiktok_business/catalog/product/file/",
params={},
json={
"bc_id": "",
"catalog_id": "",
"file_url": ""
},
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/tiktok_business/catalog/product/file/');
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({"bc_id":"","catalog_id":"","file_url":""}),
});
console.log(r.status, await r.json());PHP
<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/tiktok_business/catalog/product/file/' . '?' . 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, '{"bc_id":"","catalog_id":"","file_url":""}');
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;Response
Response fields (as returned by TikTok Business)
| Name | Type | Sample | Description |
|---|---|---|---|
| code | number | Return code, see Appendix - return code. | |
| message | string | Return message, see Appendix-Return message. | |
| request_id | string | The log id of a request, which uniquely identifies the request. | |
| data | object | Returned data. | |
| feed_log_id | string | Catalog handling log ID. |
Response sample
HTTPS/1.1 200 OK
{
"message": "OK",
"code": 0,
"data": {
"feed_log_id": "{{feed_log_id}}"
},
"request_id": "{{request_id}}"
}
(/code);
Get started
- Sign up for Partner
- Enable a data type of the Ads (Marketing API) group on the platform page
- Create an API key (tick the TikTok Business channel)
- Call it as in the examples above