Update the statuses of ad groups
POST/adgroup/status/update/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/adgroup/status/update/
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 enable, disable or delete an ad group. You can:
- Enable the ad group and deliver it to your audience with a specified delivery plan.
- Disable the ad group, suspend the delivery.
- Delete the ad group.
>Note
>
- The ad group in a Dedicated Campaign cannot be deleted. To delete such an ad group, you have to delete the campaign.
- The operation status of a deleted ad group or an ad group in a deleted campaign cannot be modified. You can use /campaign/get/ or /adgroup/get/ to get the operation status of a campaign or an ad group via
operation_status.
Request
Endpoint
POST https://partner.quantri360.com/v1/tiktok_business/adgroup/status/update/
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 |
|---|---|---|---|---|---|
| adgroup_ids | body | string[] | Yes | The IDs of the ad groups to be operated on. Size range: 1-20. | |
| operation_status | body | string | Yes | The operation to be performed on the ad groups.
Enum values: DISABLE (pause), ENABLE (enable), DELETE (delete).
Note:
- The status of deleted ad groups or ad groups in deleted campaigns cannot be modified.
- ENABLE and DISABLE operations are not supported for R&F ad groups. | |
| allow_partial_success | body | boolean | No | Whether to allow partial success for the operation.
Enum values: true, false. Default value: false.
If this field is set to true and you specify an operation for multiple ad groups, the operation can succeed for only some of the specified ad groups. In this case, the ineligible ad groups will be filtered out. |
Request examples
curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/adgroup/status/update/" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"adgroup_ids":[],"operation_status":""}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/tiktok_business/adgroup/status/update/",
params={},
json={
"adgroup_ids": [],
"operation_status": ""
},
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/adgroup/status/update/');
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({"adgroup_ids":[],"operation_status":""}),
});
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/adgroup/status/update/' . '?' . 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, '{"adgroup_ids":[],"operation_status":""}');
$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 Codes. | |
| message | string | Response message. For details, see Appendix - Return Codes. | |
| data | object | Return data. | |
| adgroup_ids | string[] | The IDs of ad groups for which the operation was successful. | |
| status | string | The current status of the ad groups for which the operation was successful. Enum values: `DISABLE` (paused), `ENABLE` (enabled), `DELETE` (deleted). | |
| error_list | object[] | Returned only when `allow_partial_success` is set to `true`. A list of errors and the corresponding failed ad groups. | |
| adgroup_id | string | The ID of the ad group for which the operation failed. | |
| error_message | string | The error message associated with the failed ad group. | |
| request_id | string | The log id of a request, which uniquely identifies the request. |
Response sample
HTTPS/1.1 200 OK
{
"message": "OK",
"code": 0,
"data": {
"status": "DISABLE",
"adgroup_ids": [
111
]
},
"request_id": "2020031110223101018904922300361F64"
}
(/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