Check Value-Based Optimization eligibility
GET/tool/vbo_status/Via 360: GET https://partner.quantri360.com/v1/tiktok_business/tool/vbo_status/
Description
Use this endpoint to check whether certain settings are eligible for Value-Based Optimization (VBO), and to get the available VBO bidding strategies for the specified settings.
To learn about how to enable VBO, refer to Enable Value-Based Optimization.
>Note
> If you specify through the request an allowlist-only VBO feature, and you are not allowlisted for the feature, the response will indicate that your settings are ineligible for VBO (vo_status = NOT_SUPPORT).
Request
Endpoint
GET https://partner.quantri360.com/v1/tiktok_business/tool/vbo_status/
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 |
|---|---|---|---|---|---|
| objective_type | query | string | Yes | Advertising objective.
Set this field to APP_PROMOTION, WEB_CONVERSIONS, or PRODUCT_SALES.
When you set this field to any other objective, vo_status will be NOT_SUPPORT because these objectives are not supported for VBO.
For enum values and descriptions, see Objectives.
Note: When objective_type is set to PRODUCT_SALES and promotion_type is set to LIVE_SHOPPING or VIDEO_SHOPPING, do not pass in pixel_id or app_id. Otherwise, pass in either pixel_id or app_id. | |
| app_promotion_type | query | string | No | Required when objective_type is APP_PROMOTION.
App promotion type.
Enum values:
- APP_INSTALL: Get new users to install your app.
- APP_RETARGETING: Re-engage existing users to take action in your app.
- MINIS: TikTok Minis. Get people to watch your series or play your games with TikTok Minis.
- To learn more about the campaign type where this setting is supported, see Create an Upgraded Smart+ Minis Campaign.
Note: Only the enum value APP_INSTALL can be used in an iOS14 Dedicated Campaign. | |
| campaign_type | query | string | No | Do not pass campaign_type and ios14_quota_type at the same time. If both fields are passed, ios14_quota_type will be ignored.
Campaign type.
Enums values:
- REGULAR_CAMPAIGN: non-iOS 14 Dedicated Campaign.
- IOS14_CAMPAIGN: iOS 14 Dedicated Campaign.
The value IOS14_CAMPAIGN can only be used when:
- objective_type is PRODUCT_SALES.
- objective_type is APP_PROMOTION and app_promotion_type is APP_INSTALL. | |
| is_advanced_dedicated_campaign | query | boolean | No | Whether the campaign is an Advanced Dedicated Campaign. Advanced Dedicated Campaigns leverage advanced delivery models that benefit from real-time signals.
Supported values: true, false.
Default value: false.
To learn about how to create such campaigns, see Create Advanced Dedicated Campaigns.
Note: Once set, this field cannot be updated. | |
| disable_skan_campaign | query | boolean | No | Valid only when the following conditions are all met:
- objective_type is APP_PROMOTION.
- app_promotion_type is APP_INSTALL.
- campaign_type is IOS14_CAMPAIGN.
- app_id is set to the ID of an iOS app that is eligible for Advanced Dedicated Campaigns. To confirm whether an app is eligible for Advanced Dedicated Campaigns, use /app/list/ and check the returned advanced_dedicated_campaign_allowed.
Whether to disable SKAN (SKAdNetwork) attribution, Apple's conversion attribution solution for iOS campaigns
Enum values:
- true: To disable SKAN attribution. The campaign will not be bound by Dedicated Campaign quota limits and you will be able to retrieve Self Attribution Network (SAN) metrics for the campaign. However, you cannot retrieve SKAN reporting metrics for the campaign. Learn more about SAN integration.
- For a Dedicated Campaign using an app that is eligible for Advanced Dedicated Campaigns, you need to enable SKAN attribution or Advanced Dedicated Campaign or both. You cannot disable SKAN attribution and Advanced Dedicated Campaign simultaneously.
- false: To enable SKAN attribution. The campaign will be bound by Dedicated Campaign quota limits and you will be able to retrieve SKAN metrics for the campaign.
- If you enable Advanced Dedicated Campaign by setting is_advanced_dedicated_campaign to true simultaneously, you'll be able to retrieve both SAN and SKAN reporting metrics for the campaign.
Note:
- Disabling SKAN attribution for Dedicated Campaigns is currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative.
- If you are allowlisted for disabling SKAN attribution for Dedicated Campaigns, you cannot set bid_type to BID_TYPE_CUSTOM at the ad group level when the following conditions are all met:
- At the campaign level:
- is_advanced_dedicated_campaign is false.
- disable_skan_campaign is false.
- At the ad group level:
- optimization_goal is INSTALL or IN_APP_EVENT.
- Once set, this field cannot be updated.
- Getting access to Advanced Dedicated Campaign requires the app to meet certain criteria. If your app is ineligible for Advanced Dedicated Campaign, reach out to your TikTok representative. Your TikTok representative will be able to provide troubleshooting support to help your app get access to Advanced Dedicated Campaign. | |
| bid_align_type | query | string | No | Valid only when the following conditions are all met:
- objective_type is APP_PROMOTION.
- app_promotion_type is APP_INSTALL.
- campaign_type is IOS14_CAMPAIGN.
- app_id is set to the ID of an iOS app that is eligible for Advanced Dedicated Campaigns. To confirm whether an app is eligible for Advanced Dedicated Campaigns, use /app/list/ and check the returned advanced_dedicated_campaign_allowed.
The attribution type for the Dedicated Campaign. The type determines which attribution network the target CPA or ROAS at the ad group level is based on.
Enum value:
- SAN: Self Attributing Network(SAN).
- SKAN: SKAdNetwork (SKAN).
- When is_advanced_dedicated_campaign is true and you are not allowlisted for disabling SKAN attribution for Dedicated Campaigns, set this field to SKAN.
- When is_advanced_dedicated_campaign is true, you are allowlisted for disabling SKAN attribution for Dedicated Campaigns, and disable_skan_campaign is false, set this field to SAN.
- When is_advanced_dedicated_campaign is true and disable_skan_campaign is true, set this field to SAN.
- When is_advanced_dedicated_campaign is false and disable_skan_campaign is false, set this field to SKAN. | |
| promotion_type | query | string | Yes | Promotion type and you can decide where you'd like to promote your products using this field.
For enum values, see Enumeration - Promotion Type.
Note: When objective_type is set to PRODUCT_SALES and promotion_type is set to LIVE_SHOPPING or VIDEO_SHOPPING, do not pass in pixel_id or app_id. Otherwise, pass in either pixel_id or app_id. | |
| placements | query | string[] | Yes | The apps where you want to deliver your ads.
Note:
- Currently, we support PLACEMENT_TIKTOK, PLACEMENT_PANGLE and PLACEMENT_GLOBAL_APP_BUNDLE.
- For Product Sales campaigns (objective_type = PRODUCT_SALES), only TikTok placement (PLACEMENT_TIKTOK) is supported. | |
| ios14_quota_type | query | string | No | Do not pass campaign_type and ios14_quota_type at the same time. If both fields are passed, ios14_quota_type will be ignored.
We recommend using campaign_type alone when you specify an iOS 14 Dedicated Campaign.
- campaign_type as REGULAR_CAMPAIGN or ios14_quota_type as UNOCCUPIED both indicate a non-iOS 14 Dedicated Campaign.
- campaign_type as IOS14_CAMPAIGN or ios14_quota_type as OCCUPIED both indicate an iOS 14 Dedicated Campaign.
Whether the campaign will be counted towards the iOS 14 Dedicated Campaign quota.
Enum values:
- OCCUPIED: The campaign is an iOS 14 Dedicated Campaign.
- UNOCCUPIED: The campaign is not an iOS 14 Dedicated Campaign. | |
| campaign_app_profile_page_state | query | string | No | Whether to use App Profile Page at the campaign level to optimize delivery.
Enum values: ON, OFF.
You can use the field only when objective_type is APP_PROMOTION and your campaign is an iOS14 Dedicated Campaign (ios14_quota_type =OCCUPIED). Otherwise, an error will occur. | |
| pixel_id | query | string | No | Not supported when objective_type is set to PRODUCT_SALES and promotion_type is set to LIVE_SHOPPING or VIDEO_SHOPPING or when app_promotion_type is MINIS.
Otherwise, pass in either pixel_id or app_id.
Pixel ID.
When you pass in this field, you need to specify optimization_event at the same time.
To get Pixel IDs, use the /pixel/list/ endpoint. | |
| optimization_event | query | string | No | Required when pixel_id is passed.
Ignored when app_id is passed.
Conversion event for the ad group.
See Conversion events for more. | |
| store_id | query | string | No | Valid only when objective_type is PRODUCT_SALES.
ID of the TikTok Shop.
Note: To get the TikTok Shop ID, you can use /bc/asset/get/:
- When in the response asset_type is TIKTOK_SHOP, the returned asset_id is the TikTok Shop ID. | |
| is_smart_performance_campaign | query | boolean | No | Whether the campaign is a Smart+ Campaign or not.
Enum values: true, false. | |
| campaign_automation_type | query | string | No | Campaign automation type.
Enum values:
- MANUAL: Manual Campaigns.
- SMART_PLUS: Smart+ Campaigns.
- UPGRADED_SMART_PLUS: Upgraded Smart+ Campaigns, a new automated campaign type. To learn more about Upgraded Smart+ Campaigns, see Upgraded Smart+ Campaign. | |
| budget_optimize_on | query | boolean | No | Whether to enable Campaign Budget Optimization (CBO).
Enum values: true, false.
For details about CBO, see Campaign Budget Optimization. |
Request examples
curl -s "https://partner.quantri360.com/v1/tiktok_business/tool/vbo_status/?objective_type=&promotion_type=&placements=%5B%5D" \ -H "Authorization: Bearer $KEY"
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.get(
"https://partner.quantri360.com/v1/tiktok_business/tool/vbo_status/",
params={
"objective_type": "",
"promotion_type": "",
"placements": []
},
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/tool/vbo_status/');
for (const [k, v] of Object.entries({"objective_type":"","promotion_type":"","placements":[]})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
method: 'GET',
headers: { Authorization: `Bearer ${KEY}` },
});
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/tool/vbo_status/' . '?' . http_build_query(['objective_type' => '', 'promotion_type' => '', 'placements' => '[]']); $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key]); $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. | |
| vo_status | string | The status of VBO for Web or VBO IAP for App for the settings in the request. Enum values: - `QUALIFIED`: Eligible. - `NO_EVENT`: Not eligible because the pixel (`pixel_id`) or App (`app_id`) has not accumulated any event. - `NO_VALUE`: Not eligible because the pixel (`pixel_id`) or App (`app_id`) has not accumulated any value. - `INSUFFICIENT_EVENTS`: Not eligible because the pixel (`pixel_id`) or App (`app_id`) has not accumulated enough events. - `NOT_SUPPORT`: Not eligible for any of the following reasons: - The settings are not supported. - The settings are supported, but you are not allowlisted to use the allowlist-only feature specified through the settings. | |
| vo_min | string | The status of the Cost Cap bidding strategy for the settings in the request when VBO for Web or VBO IAP for App is enabled. Enum values: - `QUALIFIED`: Eligible. - `NO_EVENT`: Not eligible because the pixel (`pixel_id`) or App (`app_id`) has not accumulated any event. - `NO_VALUE`: Not eligible because the pixel (`pixel_id`) or App (`app_id`) has not accumulated any value. - `INSUFFICIENT_EVENTS`: Not eligible because the pixel (`pixel_id`) or App (`app_id`) has not accumulated enough events. - `NOT_SUPPORT`: Not eligible for any of the following reasons: - The settings are not supported. - The settings are supported, but you are not allowlisted to use the allowlist-only feature specified through the settings. Note: The Cost Cap bidding strategy is no longer supported for VBO. Therefore, the value of this field is always `NOT_SUPPORT`. | |
| vo_min_roas | string | The status of the bidding strategy Minimum ROAS for the settings in the request when VBO for Web or VBO IAP for App is enabled. Enum values: - `QUALIFIED`: Eligible. - `NO_EVENT`: Not eligible because the pixel (`pixel_id`) or App (`app_id`) has not accumulated any event. - `NO_VALUE`: Not eligible because the pixel (`pixel_id`) or App (`app_id`) has not accumulated any value. - `INSUFFICIENT_EVENTS`: Not eligible because the pixel (`pixel_id`) or App (`app_id`) has not accumulated enough events. - `NOT_SUPPORT`: Not eligible for any of the following reasons: - The settings are not supported. - The settings are supported, but you are not allowlisted to use the allowlist-only feature specified through the settings. | |
| vo_highest_value | string | The status of the bidding strategy Highest Value for the settings in the request when VBO for Web or VBO IAP for App is enabled. Enum values: - `QUALIFIED`: Eligible. - `NO_EVENT`: Not eligible because the pixel (`pixel_id`) or App (`app_id`) has not accumulated any event. - `NO_VALUE`: Not eligible because the pixel (`pixel_id`) or App (`app_id`) has not accumulated any value. - `INSUFFICIENT_EVENTS`: Not eligible because the pixel (`pixel_id`) or App (`app_id`) has not accumulated enough events. - `NOT_SUPPORT`: Not eligible for any of the following reasons: - The settings are not supported. - The settings are supported, but you are not allowlisted to use the allowlist-only feature specified through the settings. | |
| vo_iaa_min_roas | string | The status of the Day 7 bidding strategy Minimum ROAS (Day 7 ROAS) for the settings in the request when VBO IAA for App is enabled. Enum values: - `QUALIFIED`: Eligible. - `NO_EVENT`: Not eligible because the App (`app_id`) has not accumulated any event. - `NO_VALUE`: Not eligible because the App (`app_id`) has not accumulated any events with a conversion value greater than 0. - `INSUFFICIENT_EVENTS`: Not eligible because the App (`app_id`) has not accumulated enough events with a conversion value greater than 0. - `NOT_SUPPORT`: Not eligible for any of the following reasons: - The settings are not supported. - The settings are supported, but the App (`app_id`) has not met the unlocking criteria for the feature. | |
| vo_iaa_highest_value | string | The status of the Day 7 bidding strategy Highest Value (Day 7 Highest Value) for the settings in the request when VBO IAA for App is enabled. Enum values: - `QUALIFIED`: Eligible. - `NO_EVENT`: Not eligible because the App (`app_id`) has not accumulated any event. - `NO_VALUE`: Not eligible because the App (`app_id`) has not accumulated any events with a conversion value greater than 0. - `INSUFFICIENT_EVENTS`: Not eligible because the App (`app_id`) has not accumulated enough events with a conversion value greater than 0. - `NOT_SUPPORT`: Not eligible for any of the following reasons: - The settings are not supported. - The settings are supported, but the App (`app_id`) has not met the unlocking criteria for the feature. | |
| vo_iaa_min_roas_zero_day | string | The status of the Day 0 bidding strategy Minimum ROAS (Day 0 ROAS) for the settings in the request when VBO IAA for App is enabled. Enum values: - `QUALIFIED`: Eligible. - `NO_EVENT`: Not eligible because the App (`app_id`) has not accumulated any event. - `NO_VALUE`: Not eligible because the App (`app_id`) has not accumulated any events with a conversion value greater than 0. - `INSUFFICIENT_EVENTS`: Not eligible because the App (`app_id`) has not accumulated enough events with a conversion value greater than 0. - `NOT_SUPPORT`: Not eligible for any of the following reasons: - The settings are not supported. - The settings are supported, but the advertiser (`advertiser_id`) has not been allowlisted for day 0 bidding of VBO IAA. | |
| vo_iaa_highest_value_zero_day | string | The status of the Day 0 bidding strategy Highest Value (Day 0 Highest Value) for the settings in the request when VBO IAA for App is enabled. Enum values: - `QUALIFIED`: Eligible. - `NO_EVENT`: Not eligible because the App (`app_id`) has not accumulated any event. - `NO_VALUE`: Not eligible because the App (`app_id`) has not accumulated any events with a conversion value greater than 0. - `INSUFFICIENT_EVENTS`: Not eligible because the App (`app_id`) has not accumulated enough events with a conversion value greater than 0. - `NOT_SUPPORT`: Not eligible for any of the following reasons: - The settings are not supported. - The settings are supported, but the advertiser (`advertiser_id`) has not been allowlisted for day 0 bidding of VBO IAA. | |
| roas_status_day7 | string | The status of the Day 7 bidding strategy Minimum ROAS (Day 7 ROAS) for the settings in the request when VBO IAP for App is enabled. Enum values: - `QUALIFIED`: Eligible. - `NO_EVENT`: Not eligible because the App (`app_id`) has not accumulated any event. - `NO_VALUE`: Not eligible because the App (`app_id`) has not accumulated any events with a conversion value greater than 0. - `INSUFFICIENT_EVENTS`: Not eligible because the App (`app_id`) has not accumulated enough events with a conversion value greater than 0. - `NOT_SUPPORT`: Not eligible for any of the following reasons: - The settings are not supported. - The settings are supported, but the App (`app_id`) has not been allowlisted for day 7 bidding of VBO IAP. | |
| highest_value_status_day7 | string | The status of the Day 7 bidding strategy Highest Value (Day 7 Highest Value) for the settings in the request when VBO IAP for App is enabled. Enum values: - `QUALIFIED`: Eligible. - `NO_EVENT`: Not eligible because the App (`app_id`) has not accumulated any event. - `NO_VALUE`: Not eligible because the App (`app_id`) has not accumulated any events with a conversion value greater than 0. - `INSUFFICIENT_EVENTS`: Not eligible because the App (`app_id`) has not accumulated enough events with a conversion value greater than 0. - `NOT_SUPPORT`: Not eligible for any of the following reasons: - The settings are not supported. - The settings are supported, but the App (`app_id`) has not been allowlisted for day 7 bidding of VBO IAP. | |
| roas_status_day0 | string | The status of the Day 0 bidding strategy Minimum ROAS (Day 7 ROAS) for the settings in the request when VBO IAP for App is enabled. Enum values: - `QUALIFIED`: Eligible. - `NO_EVENT`: Not eligible because the App (`app_id`) has not accumulated any event. - `NO_VALUE`: Not eligible because the App (`app_id`) has not accumulated any events with a conversion value greater than 0. - `INSUFFICIENT_EVENTS`: Not eligible because the App (`app_id`) has not accumulated enough events with a conversion value greater than 0. - `NOT_SUPPORT`: Not eligible for any of the following reasons: - The settings are not supported. - The settings are supported, but the App (`app_id`) has not been allowlisted for day 0 bidding of VBO IAP. | |
| highest_value_status_day0 | string | The status of the Day 0 bidding strategy Highest Value (Day 7 Highest Value) for the settings in the request when VBO IAP for App is enabled. Enum values: - `QUALIFIED`: Eligible. - `NO_EVENT`: Not eligible because the App (`app_id`) has not accumulated any event. - `NO_VALUE`: Not eligible because the App (`app_id`) has not accumulated any events with a conversion value greater than 0. - `INSUFFICIENT_EVENTS`: Not eligible because the App (`app_id`) has not accumulated enough events with a conversion value greater than 0. - `NOT_SUPPORT`: Not eligible for any of the following reasons: - The settings are not supported. - The settings are supported, but the App (`app_id`) has not been allowlisted for day 0 bidding of VBO IAP. |
Response sample
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"vo_highest_value": "QUALIFIED",
"vo_min_roas": "QUALIFIED",
"vo_status": "QUALIFIED",
"vo_min": "NOT_SUPPORT",
"vo_iaa_highest_value": "NOT_SUPPORT",
"vo_iaa_min_roas": "NOT_SUPPORT",
"vo_iaa_highest_value_zero_day": "NOT_SUPPORT",
"vo_iaa_min_roas_zero_day": "NOT_SUPPORT"
}
}
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