Update a GMV Max Campaign
POST/campaign/gmv_max/update/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/campaign/gmv_max/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
Sửa chiến dịch GMV Max: ngân sách ngày, ROI mục tiêu, tên, lịch chạy, ngày khuyến mãi, tự tăng ngân sách, danh sách sản phẩm, danh sách video. Chỉ gửi trường cần đổi — trường không gửi giữ nguyên. Bật / tắt chiến dịch dùng /campaign/status/update/.
- API GHI — cần key có quyền ghi.
- Tài khoản quảng cáo phải đang giữ quyền GMV Max độc quyền của TikTok Shop — kiểm
exclusive_authorized_advertiser_info.advertiser_idở /gmv_max/store/list/. item_group_ids/item_listlà THAY CẢ DANH SÁCH, không cộng thêm — gửi thiếu phần tử nào là gỡ phần tử đó khỏi chiến dịch.- Sửa ROI mục tiêu làm chiến dịch mất điều kiện bảo vệ ROI (xét lại mỗi 24 giờ — xem
roi_protection_compensation_statusở /gmv_max/campaign/get/). - Hạ ROI ngày khuyến mãi: TikTok có thể tính ROI khuyến mãi từ mức thấp hơn giữa ROI bạn nhập và hiệu quả 7 ngày thường gần nhất rồi mới áp mức giảm — giá trị trả về có thể khác số bạn gửi.
Request
Endpoint
POST https://partner.quantri360.com/v1/tiktok_business/campaign/gmv_max/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 |
|---|---|---|---|---|---|
| campaign_id | body | string | Yes | 1800000000000000001 | Id chiến dịch GMV Max. |
| budget | body | float | No | 2000000 | Ngân sách ngày mới, theo tiền tệ của tài khoản quảng cáo. |
| roas_bid | body | float | No | 3.2 | ROI mục tiêu mới, tối đa 1 chữ số thập phân (vd 3, 3.2) — chỉ khi chiến dịch đặt giá thầu theo ROI (deep_bid_type = VO_MIN_ROAS). |
| campaign_name | body | string | No | GMV Max - Áo sơ mi | Tên mới. |
| schedule_type | body | string | No | SCHEDULE_START_END | SCHEDULE_FROM_NOW = chạy liên tục · SCHEDULE_START_END = có giờ kết thúc. |
| schedule_end_time | body | string | No | 2026-12-31 16:59:59 | Giờ kết thúc, YYYY-MM-DD HH:MM:SS UTC (giờ Việt Nam − 7). Bắt buộc khi SCHEDULE_START_END; không gửi khi SCHEDULE_FROM_NOW. |
| promotion_days | body | object | No | {"is_enabled":true,"auto_schedule_enabled":true,"roas_bid_multiplier":90,"budget_increase_percentage":50,"increase_limit":10} | Ngày khuyến mãi (gửi object này là tự bật is_enabled):
- auto_schedule_enabled: theo lịch khuyến mãi của TikTok Shop (mặc định true khi bật).
- custom_schedule_list: lịch tự đặt [{start_date, end_date}] (YYYY-MM-DD theo múi giờ tài khoản quảng cáo, không trước hôm nay, tối đa 50) — bắt buộc ít nhất một khi auto_schedule_enabled = false.
- roas_bid_multiplier: hạ ROI mục tiêu trong ngày khuyến mãi 90 (−10%) · 80 (−20%) · 70 (−30%).
- budget_increase_percentage 50–300 (% tăng mỗi lần) · increase_limit 1–10 (số lần tăng tối đa / ngày). |
| auto_budget | body | object | No | {"auto_budget_enabled":true,"budget_increase_percentage":50,"increase_limit":10} | Tự tăng ngân sách ngày thường khi đạt ≥ 90% ROI mục tiêu và đã tiêu ≥ 80% ngân sách (về lại mức gốc mỗi ngày): auto_budget_enabled, budget_increase_percentage 50–300, increase_limit 1–10. |
| item_group_ids | body | string[] | No | ["1729000000000000001","1729000000000000002"] | DANH SÁCH SPU MỚI (thay toàn bộ danh sách cũ, tối đa 50) — chỉ chiến dịch sản phẩm có product_specific_type = CUSTOMIZED_PRODUCTS. Muốn thêm / gỡ: lấy item_group_ids hiện tại ở /campaign/gmv_max/info/, gộp / bỏ rồi gửi lại cả danh sách. SPU dùng được: /store/product/get/ với ad_creation_eligible = GMV_MAX, chọn sản phẩm status = AVAILABLE và gmv_max_ads_status = UNOCCUPIED. |
| item_list | body | object[] | No | [{"item_id":"7650000000000000001","spu_id_list":["1729000000000000001"],"identity_info":{"identity_id":"7000000000000000101","identity_type":"TTS_TT","store_id":"7490000000000000001"},"video_info":{"video_id":"v10044g50000abcdef"}}] | DANH SÁCH VIDEO MỚI (thay toàn bộ, tối đa 50) — chỉ chiến dịch sản phẩm có product_video_specific_type = CUSTOM_SELECTION. Mỗi phần tử: item_id, spu_id_list, identity_info {identity_id, identity_type; identity_authorized_bc_id khi BC_AUTH_TT; identity_authorized_shop_id khi danh tính có trường này ở /gmv_max/identity/get/; store_id khi TTS_TT}, video_info {video_id}. Video dùng được: /gmv_max/video/get/. Muốn thêm video: lấy item_list hiện tại ở /campaign/gmv_max/info/ rồi gửi lại kèm video mới. |
| affiliate_posts_enabled | body | bool | No | true | Dùng thêm bài của creator affiliate — chỉ chiến dịch sản phẩm có product_video_specific_type = AUTO_SELECTION. |
| accelerate_testing_for_new_videos | body | string | No | ON | ON / OFF — ưu tiên thử video mới trong 7 ngày. |
| custom_anchor_video_list | body | object[] | No | Trường cũ (TikTok sắp bỏ): video dùng làm bài tùy chỉnh của chiến dịch [{item_id, spu_id_list (1 SPU), identity_info}]. |
Request examples
curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/campaign/gmv_max/update/?platform_shop_id=7000000000000000001" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"campaign_id":"1800000000000000001","budget":2000000,"roas_bid":3.2}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/tiktok_business/campaign/gmv_max/update/",
params={
"platform_shop_id": "7000000000000000001"
},
json={
"campaign_id": "1800000000000000001",
"budget": 2000000,
"roas_bid": 3.2
},
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/campaign/gmv_max/update/');
for (const [k, v] of Object.entries({"platform_shop_id":"7000000000000000001"})) 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({"campaign_id":"1800000000000000001","budget":2000000,"roas_bid":3.2}),
});
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/campaign/gmv_max/update/' . '?' . http_build_query(['platform_shop_id' => '7000000000000000001']);
$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, '{"campaign_id":"1800000000000000001","budget":2000000,"roas_bid":3.2}');
$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)
Trả cấu hình chiến dịch SAU khi sửa (cùng dạng /campaign/gmv_max/info/).
| Name | Type | Sample | Description |
|---|---|---|---|
| code | int | 0 | 0 = thành công; khác 0 xem `message` (TikTok trả HTTP 200 kèm code lỗi; vd 40002 = tham số sai, message liệt kê giá trị hợp lệ). |
| message | string | OK | Thông điệp của TikTok. |
| request_id | string | 2021080307532501024502410704A7306F | Mã request TikTok — ghi lại khi cần tra lỗi. |
| data | object | Dữ liệu. | |
| advertiser_id | string | 7000000000000000001 | Id tài khoản quảng cáo. |
| campaign_id | string | 1800000000000000001 | Id chiến dịch. |
| campaign_name | string | GMV Max - Áo sơ mi | Tên chiến dịch. |
| operation_status | string | ENABLE | `ENABLE` = đang bật · `DISABLE` = đang tắt. |
| store_id | string | 7490000000000000001 | Id TikTok Shop được quảng bá. |
| store_authorized_bc_id | string | Id Business Center có quyền với TikTok Shop. | |
| shopping_ads_type | string | PRODUCT | `PRODUCT` = GMV Max sản phẩm · `LIVE` = GMV Max LIVE. |
| product_specific_type | string | ALL | Cách chọn sản phẩm: `ALL` = TikTok tự chọn trong toàn bộ sản phẩm của shop · `CUSTOMIZED_PRODUCTS` = chỉ các sản phẩm đã chọn (`item_group_ids`) · `UNSET`. |
| item_group_ids | string[] | ["1729000000000000001"] | Chỉ khi `PRODUCT` + `CUSTOMIZED_PRODUCTS`: id SPU (sản phẩm cha) đã chọn. |
| optimization_goal | string | VALUE | `VALUE` = tối ưu doanh thu. |
| deep_bid_type | string | VO_MIN_ROAS | `VO_MIN_ROAS` = đặt giá thầu theo ROI mục tiêu. |
| roas_bid | float | 3.2 | ROI mục tiêu (chỉ khi `VO_MIN_ROAS`). |
| budget | float | 2000000 | Ngân sách ngày, theo tiền tệ của tài khoản quảng cáo. |
| roi_protection_enabled | bool | true | Chiến dịch có thuộc diện bảo vệ ROI không (TikTok bù tín dụng quảng cáo khi ROI thấp hơn mục tiêu dù chạy đúng hướng dẫn). |
| promotion_days | object | Cài đặt ngày khuyến mãi (tự hạ ROI mục tiêu / tăng ngân sách vào ngày mua sắm cao điểm). | |
| is_enabled | bool | false | Bật tối ưu ngày khuyến mãi. |
| auto_schedule_enabled | bool | true | Theo lịch khuyến mãi của TikTok Shop. |
| custom_schedule_list | object[] | Lịch khuyến mãi tự đặt. | |
| start_time | string | 2026-11-11 | Ngày bắt đầu, `YYYY-MM-DD` theo múi giờ tài khoản quảng cáo. |
| end_time | string | 2026-11-12 | Ngày kết thúc, cùng định dạng. |
| roas_bid_multiplier | int | 90 | Hạ ROI mục tiêu trong ngày khuyến mãi: `90` = −10% · `80` = −20% · `70` = −30%. |
| adjusted_roas_bid | float | ROI mục tiêu áp dụng trong ngày khuyến mãi. | |
| budget_increase_percentage | int | 50 | % tăng ngân sách mỗi lần tự tăng trong ngày khuyến mãi (50 = +50%). |
| increase_limit | int | 10 | Số lần tự tăng tối đa mỗi ngày trong ngày khuyến mãi. |
| current_budget | float | Ngân sách ngày đang đặt (= `budget`). | |
| next_increase | float | Mức tăng mỗi lần = `current_budget × budget_increase_percentage`. | |
| remained_times | int | Số lần tự tăng còn lại. | |
| maximum_budget | float | Ngân sách tối đa có thể đạt = `current_budget + current_budget × budget_increase_percentage × remained_times`. | |
| estimated_gross_revenue_increase | string | 24% | Ước tính % doanh thu tăng nhờ hạ ROI. |
| auto_budget | object | Tự tăng ngân sách vào ngày thường (khi đạt ≥ 90% ROI mục tiêu và đã tiêu ≥ 80% ngân sách; ngân sách về lại mức gốc mỗi ngày). | |
| auto_budget_enabled | bool | false | Bật tự tăng ngân sách ngày thường. |
| budget_increase_percentage | int | 50 | % tăng ngân sách mỗi lần tự tăng ngày thường (50 = +50%). |
| increase_limit | int | 10 | Số lần tự tăng tối đa mỗi ngày ngày thường. |
| current_budget | float | Ngân sách ngày đang đặt (= `budget`). | |
| next_increase | float | Mức tăng mỗi lần = `current_budget × budget_increase_percentage`. | |
| remained_times | int | Số lần tự tăng còn lại. | |
| maximum_budget | float | Ngân sách tối đa có thể đạt = `current_budget + current_budget × budget_increase_percentage × remained_times`. | |
| auto_budget_enabled | bool | Trường cũ (TikTok sắp bỏ) — dùng `auto_budget.auto_budget_enabled`. | |
| schedule_type | string | SCHEDULE_FROM_NOW | `SCHEDULE_FROM_NOW` = chạy liên tục từ giờ bắt đầu · `SCHEDULE_START_END` = chạy trong khoảng bắt đầu – kết thúc. |
| schedule_start_time | string | 2026-10-01 00:00:00 | Giờ bắt đầu, `YYYY-MM-DD HH:MM:SS` UTC (cộng 7 ra giờ Việt Nam). |
| schedule_end_time | string | Giờ kết thúc, cùng định dạng. | |
| placements | string[] | ["PLACEMENT_TIKTOK","PLACEMENT_PANGLE"] | Vị trí hiển thị: `PLACEMENT_TIKTOK` · `PLACEMENT_PANGLE`. |
| location_ids | string[] | Id khu vực nhắm tới. | |
| age_groups | string[] | Nhóm tuổi nhắm tới. | |
| product_video_specific_type | string | AUTO_SELECTION | Cách chọn video: `AUTO_SELECTION` = TikTok tự chọn · `CUSTOM_SELECTION` = chọn tay (`item_list`) · `UNSET`. |
| accelerate_testing_for_new_videos | string | OFF | `ON` = ưu tiên thử video mới / mới ủy quyền / mới gắn link sản phẩm trong 7 ngày (doanh thu có thể giảm tạm thời, ROI vẫn trong khoảng mục tiêu) · `OFF`. |
| affiliate_posts_enabled | bool | false | Dùng thêm bài của creator affiliate đã ủy quyền cho quảng cáo TikTok Shop. |
| identity_list | object[] | Danh tính (tài khoản TikTok) gắn với chiến dịch. | |
| identity_id | string | 7000000000000000101 | Id danh tính (tài khoản TikTok). |
| identity_type | string | TTS_TT | `AUTH_CODE` = người dùng được ủy quyền bằng mã video / mã tài khoản · `TT_USER` = tài khoản TikTok doanh nghiệp đã liên kết · `BC_AUTH_TT` = tài khoản TikTok thêm vào Business Center (chủ tài khoản đã đồng ý) · `TTS_TT` = tài khoản TikTok chính thức của TikTok Shop. |
| identity_authorized_bc_id | string | Chỉ khi `BC_AUTH_TT`: id Business Center của danh tính. | |
| identity_authorized_shop_id | string | Một số danh tính `BC_AUTH_TT`: id TikTok Shop gắn với danh tính. | |
| store_id | string | Chỉ khi `TTS_TT`: id TikTok Shop của danh tính. | |
| item_list | object[] | Bài đăng (video) gắn với chiến dịch — bài có sẵn đã ủy quyền hoặc bài tùy chỉnh gắn link sản phẩm. | |
| item_id | string | 7650000000000000001 | Id bài. |
| text | string | Mô tả bài. | |
| spu_id_list | string[] | ["1729000000000000001"] | Id SPU gắn với bài. |
| identity_info | object | Danh tính đăng bài. | |
| identity_id | string | 7000000000000000101 | Id danh tính (tài khoản TikTok). |
| identity_type | string | TTS_TT | `AUTH_CODE` = người dùng được ủy quyền bằng mã video / mã tài khoản · `TT_USER` = tài khoản TikTok doanh nghiệp đã liên kết · `BC_AUTH_TT` = tài khoản TikTok thêm vào Business Center (chủ tài khoản đã đồng ý) · `TTS_TT` = tài khoản TikTok chính thức của TikTok Shop. |
| identity_authorized_bc_id | string | Chỉ khi `BC_AUTH_TT`: id Business Center của danh tính. | |
| identity_authorized_shop_id | string | Một số danh tính `BC_AUTH_TT`: id TikTok Shop gắn với danh tính. | |
| store_id | string | Chỉ khi `TTS_TT`: id TikTok Shop của danh tính. | |
| profile_image | string | Ảnh đại diện — link TẠM, hạn khoảng 48 giờ (`x-expires`); hết hạn thì gọi lại API này. | |
| user_name | string | thuonghieu.official | Tên người dùng TikTok. |
| video_info | object | Video của bài. | |
| video_id | string | v10044g50000abcdef | Id video. |
| video_cover_url | string | Ảnh bìa — link TẠM, hạn khoảng 24 giờ. | |
| preview_url | string | Link xem thử — link TẠM, hạn 6 giờ. | |
| width | int | 1080 | |
| height | int | 1920 | |
| duration | float | 15.2 | Giây. |
| size | int | 3898461 | Byte. |
| bit_rate | int | bps. | |
| fps | int | 30 | Khung hình/giây. |
| format | string | mp4 | |
| definition | string | 1080p | |
| signature | string | MD5 của file. | |
| custom_anchor_video_list | object[] | Trường cũ (TikTok sắp bỏ): bài tùy chỉnh của chiến dịch. | |
| campaign_custom_anchor_video_id | string | Trường cũ (TikTok sắp bỏ). |
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