VI | EN
Message us on Messenger
Developer resources

Update a GMV Max Campaign — TikTok Business API

Update a GMV Max Campaign · 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.

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_list là 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

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_idquerystring7000000000000000001Tà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

NameInTypeRequiredSampleDescription
campaign_idbodystringYes1800000000000000001Id chiến dịch GMV Max.
budgetbodyfloatNo2000000Ngân sách ngày mới, theo tiền tệ của tài khoản quảng cáo.
roas_bidbodyfloatNo3.2ROI 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_namebodystringNoGMV Max - Áo sơ miTên mới.
schedule_typebodystringNoSCHEDULE_START_ENDSCHEDULE_FROM_NOW = chạy liên tục · SCHEDULE_START_END = có giờ kết thúc.
schedule_end_timebodystringNo2026-12-31 16:59:59Giờ 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_daysbodyobjectNo{"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_budgetbodyobjectNo{"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_idsbodystring[]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_listbodyobject[]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_enabledbodyboolNotrueDù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_videosbodystringNoONON / OFF — ưu tiên thử video mới trong 7 ngày.
custom_anchor_video_listbodyobject[]NoTrườ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/).

NameTypeSampleDescription
codeint00 = 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ệ).
messagestringOKThông điệp của TikTok.
request_idstring2021080307532501024502410704A7306FMã request TikTok — ghi lại khi cần tra lỗi.
dataobjectDữ liệu.
advertiser_idstring7000000000000000001Id tài khoản quảng cáo.
campaign_idstring1800000000000000001Id chiến dịch.
campaign_namestringGMV Max - Áo sơ miTên chiến dịch.
operation_statusstringENABLE`ENABLE` = đang bật · `DISABLE` = đang tắt.
store_idstring7490000000000000001Id TikTok Shop được quảng bá.
store_authorized_bc_idstringId Business Center có quyền với TikTok Shop.
shopping_ads_typestringPRODUCT`PRODUCT` = GMV Max sản phẩm · `LIVE` = GMV Max LIVE.
product_specific_typestringALLCá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_idsstring[]["1729000000000000001"]Chỉ khi `PRODUCT` + `CUSTOMIZED_PRODUCTS`: id SPU (sản phẩm cha) đã chọn.
optimization_goalstringVALUE`VALUE` = tối ưu doanh thu.
deep_bid_typestringVO_MIN_ROAS`VO_MIN_ROAS` = đặt giá thầu theo ROI mục tiêu.
roas_bidfloat3.2ROI mục tiêu (chỉ khi `VO_MIN_ROAS`).
budgetfloat2000000Ngân sách ngày, theo tiền tệ của tài khoản quảng cáo.
roi_protection_enabledbooltrueChiế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_daysobjectCà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_enabledboolfalseBật tối ưu ngày khuyến mãi.
auto_schedule_enabledbooltrueTheo lịch khuyến mãi của TikTok Shop.
custom_schedule_listobject[]Lịch khuyến mãi tự đặt.
start_timestring2026-11-11Ngày bắt đầu, `YYYY-MM-DD` theo múi giờ tài khoản quảng cáo.
end_timestring2026-11-12Ngày kết thúc, cùng định dạng.
roas_bid_multiplierint90Hạ ROI mục tiêu trong ngày khuyến mãi: `90` = −10% · `80` = −20% · `70` = −30%.
adjusted_roas_bidfloatROI mục tiêu áp dụng trong ngày khuyến mãi.
budget_increase_percentageint50% tăng ngân sách mỗi lần tự tăng trong ngày khuyến mãi (50 = +50%).
increase_limitint10Số lần tự tăng tối đa mỗi ngày trong ngày khuyến mãi.
current_budgetfloatNgân sách ngày đang đặt (= `budget`).
next_increasefloatMức tăng mỗi lần = `current_budget × budget_increase_percentage`.
remained_timesintSố lần tự tăng còn lại.
maximum_budgetfloatNgân sách tối đa có thể đạt = `current_budget + current_budget × budget_increase_percentage × remained_times`.
estimated_gross_revenue_increasestring24%Ước tính % doanh thu tăng nhờ hạ ROI.
auto_budgetobjectTự 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_enabledboolfalseBật tự tăng ngân sách ngày thường.
budget_increase_percentageint50% tăng ngân sách mỗi lần tự tăng ngày thường (50 = +50%).
increase_limitint10Số lần tự tăng tối đa mỗi ngày ngày thường.
current_budgetfloatNgân sách ngày đang đặt (= `budget`).
next_increasefloatMức tăng mỗi lần = `current_budget × budget_increase_percentage`.
remained_timesintSố lần tự tăng còn lại.
maximum_budgetfloatNgân sách tối đa có thể đạt = `current_budget + current_budget × budget_increase_percentage × remained_times`.
auto_budget_enabledboolTrường cũ (TikTok sắp bỏ) — dùng `auto_budget.auto_budget_enabled`.
schedule_typestringSCHEDULE_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_timestring2026-10-01 00:00:00Giờ bắt đầu, `YYYY-MM-DD HH:MM:SS` UTC (cộng 7 ra giờ Việt Nam).
schedule_end_timestringGiờ kết thúc, cùng định dạng.
placementsstring[]["PLACEMENT_TIKTOK","PLACEMENT_PANGLE"]Vị trí hiển thị: `PLACEMENT_TIKTOK` · `PLACEMENT_PANGLE`.
location_idsstring[]Id khu vực nhắm tới.
age_groupsstring[]Nhóm tuổi nhắm tới.
product_video_specific_typestringAUTO_SELECTIONCách chọn video: `AUTO_SELECTION` = TikTok tự chọn · `CUSTOM_SELECTION` = chọn tay (`item_list`) · `UNSET`.
accelerate_testing_for_new_videosstringOFF`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_enabledboolfalseDùng thêm bài của creator affiliate đã ủy quyền cho quảng cáo TikTok Shop.
identity_listobject[]Danh tính (tài khoản TikTok) gắn với chiến dịch.
identity_idstring7000000000000000101Id danh tính (tài khoản TikTok).
identity_typestringTTS_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_idstringChỉ khi `BC_AUTH_TT`: id Business Center của danh tính.
identity_authorized_shop_idstringMột số danh tính `BC_AUTH_TT`: id TikTok Shop gắn với danh tính.
store_idstringChỉ khi `TTS_TT`: id TikTok Shop của danh tính.
item_listobject[]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_idstring7650000000000000001Id bài.
textstringMô tả bài.
spu_id_liststring[]["1729000000000000001"]Id SPU gắn với bài.
identity_infoobjectDanh tính đăng bài.
identity_idstring7000000000000000101Id danh tính (tài khoản TikTok).
identity_typestringTTS_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_idstringChỉ khi `BC_AUTH_TT`: id Business Center của danh tính.
identity_authorized_shop_idstringMột số danh tính `BC_AUTH_TT`: id TikTok Shop gắn với danh tính.
store_idstringChỉ khi `TTS_TT`: id TikTok Shop của danh tính.
profile_imagestringẢ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_namestringthuonghieu.officialTên người dùng TikTok.
video_infoobjectVideo của bài.
video_idstringv10044g50000abcdefId video.
video_cover_urlstringẢnh bìa — link TẠM, hạn khoảng 24 giờ.
preview_urlstringLink xem thử — link TẠM, hạn 6 giờ.
widthint1080
heightint1920
durationfloat15.2Giây.
sizeint3898461Byte.
bit_rateintbps.
fpsint30Khung hình/giây.
formatstringmp4
definitionstring1080p
signaturestringMD5 của file.
custom_anchor_video_listobject[]Trường cũ (TikTok sắp bỏ): bài tùy chỉnh của chiến dịch.
campaign_custom_anchor_video_idstringTrường cũ (TikTok sắp bỏ).

Get started

  1. Sign up for Partner
  2. Enable a data type of the Ads (Marketing API) group on the platform page
  3. Create an API key (tick the TikTok Business channel)
  4. Call it as in the examples above