Upload catalog videos via a file URL
POST/catalog/video/file/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/catalog/video/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 catalog videos via a file URL. Videos will be added to the E-commerce catalog through an asynchronous task. The response will include a feed_log_id representing the task processing ID. You can use this ID to check the processing status and final results via the /catalog/video/log/ endpoint.
Currently, the API only accepts CSV files containing video URLs. The CSV template for catalog videos is available at catalog_video_template.
> Note
> The endpoint can only handle one file task at the same time, and new tasks will fail if the current file task is not complete. Wait for the current task to complete before sending the next task.
Request
Endpoint
POST https://partner.quantri360.com/v1/tiktok_business/catalog/video/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. To obtain the list of Business Centers that you have access to, use /bc/get/. | |
| catalog_id | body | string | Yes | Catalog ID.
To obtain the list of E-commerce catalogs within a Business Center, use /catalog/get/ and retrieve catalog_id values with catalog_type as ECOM.
You need to have Catalog Management permission for the catalog. To obtain the catalogs for which you have Catalog Management permission, use /bc/asset/get/. Set asset_type to CATALOG to retrieve asset_id values with catalog_role as ADMIN. | |
| file_url | body | string | Yes | The download URL of the CSV file. The CSV catalog video template is accessible via catalog_video_template. To find a detailed description of each catalog video parameter, see Catalog video parameters. | |
| advertiser_ids | body | string[] | No | The IDs of the ad accounts that you want to sync the videos to.
Once synced, the videos will be available in the creative library of those ad accounts. If you don't want to sync the catalog videos to any ad accounts, do not pass this field.
Max size: 100.
The ad account and the catalog (catalog_id) must be within the same Business Center (bc_id) and you need to have Admin or Operator permission for the ad account. Ineligible ad accounts will be ignored. To obtain the ad accounts for which you have Admin or Operator permission, use /bc/asset/get/. Set asset_type to ADVERTISER to retrieve asset_id values with advertiser_role as ADMIN or OPERATOR. |
Request examples
curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/catalog/video/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/video/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/video/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/video/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 | Response code. For the complete list of response codes and descriptions, see Appendix-Return Code. | |
| message | string | Response message. For details, see Appendix - Return Codes. | |
| request_id | string | The log ID of a request, which uniquely identifies the request. | |
| data | object | Returned data. | |
| feed_log_id | string | Catalog video handling log ID. To check the processing status and final results of the upload, use /catalog/video/log/. |
Response sample
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"feed_log_id": "{{feed_log_id}}"
}
}
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