adgroup_update

List of behavioral targeting objects.

Ad group ID.

Ad group name. Maximum length is 512 characters and emoji are not allowed.

Advertiser ID.

Age groups to target. In some scenarios, targeting `AGE_13_17` in the U.S., Latin America, the EEA, the UK, Switzerland, or Canada is not allowed. If you are affected by these restrictions and leave `age_groups` unset or pass `[]` without setting `exclude_age_under_eighteen=true`, the request will fail. In those restricted scenarios, if you would otherwise leave `age_groups` unset or empty, TikTok recommends also setting `exclude_age_under_eighteen=true` to avoid errors.

Audience IDs to include. Use `/dmp/custom_audience/list/` to obtain valid IDs.

Audience rules. Valid when `objective_type` is `TRAFFIC` or `APP_PROMOTION`.

Required and valid only when campaign-level `app_promotion_type` is `APP_RETARGETING`; not supported otherwise. App retargeting audience type. You must use the same setting as when the ad group was created. Supported value is `NEW_CUSTOM_AUDIENCE`. If you want an empty retargeting custom audience, do not pass `audience_ids` or `excluded_audience_ids`. For a non-empty retargeting custom audience, pass `audience_ids`, `excluded_audience_ids`, or both, but the two lists cannot contain the same IDs.

Valid only when campaign-level `is_search_campaign` is `true`. Whether to let the system automatically generate keywords after ads are added. Default is `false`. This feature is allowlist-only for Search Ads Campaigns.

Valid only when `bid_type` is `BID_TYPE_CUSTOM` and `billing_event` is `CPC`, `CPM`, or `CPV`. Bid price for Cost Cap bidding. When CBO (`budget_optimize_on`) is on, TikTok suggests using the same bid across ad groups in the same campaign. `bid_price` must be lower than both campaign-level and ad-group-level budget.

Bidding strategy that controls cost management, spending, and delivery. This field cannot be updated when Campaign Budget Optimization (`budget_optimize_on=TRUE`) is enabled.

Pangle app block list IDs. Effective only when Pangle placement is selected. Use the `app_package_id` returned by the Pangle block list endpoint.

Brand safety type. Use `/tool/region/` to determine the countries and regions available for the chosen brand safety setting. Updating Brand Safety settings (`brand_safety_type`, `category_exclusion_ids`, and `vertical_sensitivity_id`) is allowlist-only. Pre-bid first-party Brand Safety for `APP_PROMOTION`, `WEB_CONVERSIONS`, `TRAFFIC`, `LEAD_GENERATION`, and `PRODUCT_SALES` in Auction ads is also allowlist-only.

Advertising budget. Cannot be updated when Campaign Budget Optimization (`budget_optimize_on`) is on. The new budget must be at least 105% of current spend; use reporting endpoints to retrieve the `spend` metric if needed.

Carrier IDs to target. A carrier is valid only when its `in_use` field is `true`, and carriers must be consistent with the targeted locations.

For catalogs in Business Center, specify the Business Center ID that the catalog belongs to. Starting June 30th, 2024, when `product_source` is `STORE`, this field is ignored on update. If you update an existing ad group where `product_source` is `STORE`, any existing `catalog_authorized_bc_id` will no longer be returned.

Content exclusion category IDs. This field can be updated only if the ad group's `schedule_start_time` has not been reached, or if it has been reached but `operation_status` is `DISABLE` and cost is 0; use `/adgroup/get/` to check those values. Use `/tool/content_exclusion/get/` to retrieve `excluded_category_list`. Updating Brand Safety settings is allowlist-only.

Whether to allow comments on ads in this ad group on TikTok.

Contextual tag IDs. Use `/tool/contextual_tag/get/` to retrieve valid tags. This is an allowlist-only feature. Supported only when campaign `objective_type` is `REACH` or `VIDEO_VIEWS`, and not supported when `brand_safety_type` is `THIRD_PARTY`.

Valid only when `bid_type` is `BID_TYPE_CUSTOM` and `billing_event` is `OCPM`. Target cost per conversion for oCPM. `conversion_bid_price` must be lower than both campaign-level and ad-group-level budget.

Ad delivery schedule as a 48×7-character string, where each character maps to a 30-minute slot from Monday through Sunday. `1` means deliver and `0` means do not deliver. If omitted, all `0`, or all `1`, delivery is treated as full-time.

Bidding strategy for in-app events. When `secondary_optimization_event` is specified, you must also pass `deep_bid_type`.

Bid price used after choosing an in-app-event bidding strategy, for example `VO_MIN`.

Required when `deep_funnel_optimization_status` is `ON`. Event source type for deep funnel optimization. When deep funnel optimization is enabled, you cannot update `deep_funnel_event_source`, `deep_funnel_event_source_id`, or `deep_funnel_optimization_event`. `PIXEL` uses a Pixel, `OFFLINE` uses an Offline Event Set, and `CRM` uses a CRM Event Set.

Required when `deep_funnel_optimization_status` is `ON`. Event source ID. If `deep_funnel_event_source` is `PIXEL`, pass a Pixel ID from `/pixel/list/`. If `OFFLINE`, pass an Offline Event Set ID from `/offline/get/`. If `CRM`, pass a CRM Event Set ID from `/crm/list/`. When deep funnel optimization is enabled, you cannot update `deep_funnel_event_source`, `deep_funnel_event_source_id`, or `deep_funnel_optimization_event`.

Required when `deep_funnel_optimization_status` is `ON`. Deep funnel optimization event. Supported values depend on the chosen event source; for Pixels you can also inspect `optimization_event` returned by `/pixel/list/`. Example: `SHOPPING`.

Valid only when `promotion_type` is `LEAD_GENERATION`. Controls deep funnel optimization, which optimizes both upper-funnel and deeper-funnel events. If set to `ON`, you must also provide `deep_funnel_event_source`, `deep_funnel_event_source_id`, and `deep_funnel_optimization_event`. Default is `OFF`. Deep funnel optimization with CRM events is allowlist-only; Pixel and Offline event sources are generally available.

Device model IDs to target. Use `/tool/device_model/` to retrieve valid IDs and device statuses; only active devices (`is_active=true`) can be used. Do not set this field together with `device_price_ranges`.

Device price range targeting. Values must be multiples of 50; `10000` means 1000+. Important: the upper limit you set is increased by 50 for the actual applied upper limit shown in Ads Manager. For example, `[0,250]` actually means `[0,300]`.

Whether to exclude users younger than 18. Use only in scenarios where targeting `AGE_13_17` in the U.S., Latin America, the EEA, the UK, Switzerland, or Canada is not supported; in other scenarios this field is not supported. Default is `false`. See `age_groups` for the dependency.

Audience IDs to exclude. Use `/dmp/custom_audience/list/` to obtain valid IDs.

Custom actions to exclude for filtering shopping-ads retargeting audiences. When `shopping_ads_retargeting_type` is `LAB3`, you must pass either `included_custom_actions` or `excluded_custom_actions`.

Pangle audience package IDs to exclude. Valid only for Pangle placement. Obtain `package_id` values from `/pangle_audience_package/get/` with `bind_type=EXCLUDE`. Do not pass this field together with `included_pangle_audience_package_ids`.

Used with `frequency_schedule` to control how often people see the ad. Available only for `REACH` ads. Both must satisfy `1 <= frequency <= 1000` and `1 <= frequency_schedule <= 30`. Example: `frequency=2` and `frequency_schedule=3` means show ads no more than twice every 3 days.

Used with `frequency` to control ad frequency. Available only for `REACH` ads.

Gender to target.

Household income targeting. Not supported in Reach & Frequency ads and works only on TikTok placement in the U.S.

Custom actions to include for filtering shopping-ads retargeting audiences. When `shopping_ads_retargeting_type` is `LAB3`, you must pass either `included_custom_actions` or `excluded_custom_actions`.

Pangle audience package IDs to include. Valid only for Pangle placement. Obtain `package_id` values from `/pangle_audience_package/get/` with `bind_type=INCLUDE`. Do not pass this field together with `excluded_pangle_audience_package_ids`.

General interest category IDs for audience targeting. Search or list them with `/targeting/search/` (recommended) or `/tool/interest_category/`; get recommendations by industry with `/tool/targeting_category/recommend/`.

Additional interest category IDs for audience targeting. Search them with `/targeting/search/` (recommended) or `/tool/interest_keyword/recommend/`.

Required and must be `IOS14_PLUS` when campaign-level `campaign_type` is `IOS14_CAMPAIGN`. iOS targeting mode. `UNSET` targets iOS 14.4 or earlier. `IOS14_MINUS` targets versions earlier than iOS 14.0. `IOS14_PLUS` targets iOS 14.5+ and is supported only for Dedicated Campaigns; once set to `IOS14_PLUS`, this field cannot be updated. `ALL` targets iOS 14.5+ and is supported only for iOS App Retargeting ads and iOS retargeting Video Shopping Ads with catalog product source and app optimization. If targeting iOS 14.5+ in App Retargeting ads, set `ios14_targeting=ALL` and `min_ios_version` to `14.5` or later, otherwise the request fails. For iOS App Retargeting ads (`app_promotion_type=APP_RETARGETING` and `promotion_type=APP_IOS`) and iOS retargeting Video Shopping Ads (`shopping_ads_type=VIDEO`, `product_source=CATALOG`, `promotion_type=APP_IOS`, and `shopping_ads_retargeting_type` is not `OFF`), `ALL` is used regardless of the value passed. In other cases the default is `UNSET`. Once set to `IOS14_PLUS`, these requirements must be met: `app_id` must be an iOS app ID from `/app/list/`, `operating_systems` must be `["IOS"]`, `min_ios_version` must be provided and consistent, `optimization_goal` must be `CLICK`, `INSTALL`, `IN_APP_EVENT`, or `VALUE`, `min_android_version`, `shopping_ads_retargeting_type`, and `shopping_ads_retargeting_actions_days` must not be specified, and at the ad level `deeplink_type` must not be `DEFERRED_DEEPLINK`.

Whether the promoted content is HFSS (High Fat, Salt, Sugar). If the ad promotes or prominently features an HFSS product or brand, set this to `true`. In regulated regions, HFSS ads must target only users age 18+. You can set this field to `true` when targeting locations include the UK, Australia, New Zealand, or the European Union. This setting can only be updated from `false` to `true`, not the reverse.

Whether the promoted content complies with LHF (Less Healthy Foods) regulations. Setting this to `true` confirms that any food or drink products advertised in the UK comply with the 2024 Less Healthy Foods Regulations and other applicable laws. Starting January 1st, 2026, if targeted locations include the UK and `is_hfss` is `true`, this field is required and must be `true`.

Internet service provider IDs to target. Valid only when you also provide a valid country- or region-level `location_ids` value. Use `/tool/targeting/list/` to get ISP IDs for a location. When `isp_ids` is set, `placements` cannot be only `PLACEMENT_GLOBAL_APP_BUNDLE`.

Language codes to target. If omitted or empty, language targeting is not limited. Retrieve valid codes from `/tool/language/`.

Location IDs to target. You must provide `location_ids`, `zipcode_ids`, or both. Maximum 3,000 combined IDs across `location_ids`, zip codes, and postal codes per ad group. Use `/tool/targeting/search/` or `/tool/region/` to find valid locations. Overlapping locations are not supported (for example, the U.S. and California together). If the ad group originally targeted U.S. locations via `location_ids` or `zipcode_ids`, you can update to other U.S. locations but cannot remove all U.S. locations and target only non-U.S. countries. If `TIKTOK_LITE` is included in `tiktok_subplacements`, you cannot update the ad group to exclude Japan and South Korea. To remove all location IDs, set `location_ids` to `[]` and simultaneously provide `zipcode_ids`, because targeted locations remain mandatory.

Minimum Android version.

Required when `ios14_targeting` is specified. Minimum iOS version; it must also be consistent with `ios14_targeting` when required.

Device connection types to target.

Day-2 retention ratio. Valid only when `placements` is `PLACEMENT_PANGLE` and `secondary_optimization_event` is `NEXT_DAY_OPEN`. Formula: `next_day_retention = conversion_bid_price / deep_cpa_bid`. Range is `(0,1]`. If you use this field, pass `conversion_bid_price`, `deep_bid_type`, and `next_day_retention` together and make sure the values satisfy the formula, or unexpected errors may occur.

Device operating systems to target. Only one value is allowed. Required when campaign `objective_type` is `APP_PROMOTION`, or when campaign `objective_type` is `TRAFFIC` and campaign `promotion_type` is `APP_IOS` or `APP_ANDROID`.

Pacing mode. `PACING_MODE_SMOOTH` spreads budget evenly across the schedule; `PACING_MODE_FAST` spends as quickly as possible. When CBO (`budget_optimize_on`) is on, this setting is ignored and becomes `PACING_MODE_SMOOTH`; otherwise this field is required.

Purchase intention category IDs for targeting audiences interested in purchases related to a content category. Use `/targeting/search/` to obtain valid IDs. This field supports incremental updates.

Required when `deep_bid_type` is `VO_MIN_ROAS`. ROAS goal for Value Optimization. Range is `0.01-10` for in-app advertising with `objective_type=APP_PROMOTION`, `optimization_goal=VALUE`, and `optimization_event=AD_REVENUE_VALUE`; `0.01-20` for Product Shopping Ads with `shopping_ads_type=PRODUCT_SHOPPING_ADS` and `product_source=STORE`; otherwise `0.01-1000`.

Saved Audience ID. Supported only when campaign `special_industries` for Housing, Employment, or Credit is not set, campaign `objective_type` is not `PRODUCT_SALES`, TikTok placement is selected (`placement_type=PLACEMENT_TYPE_AUTOMATIC` or `placement_type=PLACEMENT_TYPE_NORMAL` with `PLACEMENT_TIKTOK` in `placements`), and `auto_targeting_enabled` is not `true`. Create the Saved Audience first with `/dmp/saved_audience/create/`; its advertiser must match this ad group's `advertiser_id`. Do not pass `saved_audience_id` together with targeting options already contained in that Saved Audience (for example `gender`), or the request will fail. Device settings in the Saved Audience must also be compatible with the ad group; for example, an Android Saved Audience conflicts with `ios14_targeting=IOS14_PLUS`, and an iOS Saved Audience conflicts with Android app promotion setups. If troubleshooting a conflict, use `/dmp/saved_audience/list/` to inspect the Saved Audience. If the Saved Audience was created with `age_groups`, the same age restriction rules still apply here.

Required when `schedule_type` is `SCHEDULE_START_END`. End time in UTC+0, format `YYYY-MM-DD HH:MM:SS`. It cannot be later than `2038-01-01 00:00:00`.

Required when `schedule_type` is passed. Start time in UTC+0, format `YYYY-MM-DD HH:MM:SS`. It can be up to 12 hours earlier than the current time, but not later than `2028-01-01 00:00:00`. This field cannot be updated if the ad group's current `schedule_start_time` is earlier than now.

Schedule type. If `SCHEDULE_START_END`, you must provide both `schedule_start_time` and `schedule_end_time`. If `SCHEDULE_FROM_NOW`, provide only `schedule_start_time` and the end time is automatically set to 10 years later.

Valid only in Search Ads Campaigns. List of search keywords used to match ads with user search terms. Maximum 1,000 items per ad group. To verify that the campaign is a Search Ads Campaign, call `/campaign/get/` and check `is_search_campaign`. If search keywords or targeted locations are updated, the keywords will go through review again.

Whether to include ads in Search Ads so they can show when users search for your business on TikTok. You can use this field only when: campaign `objective_type` is `APP_PROMOTION`, `WEB_CONVERSIONS` with `is_search_campaign=false`, `TRAFFIC`, or `LEAD_GENERATION`; if `objective_type` is `LEAD_GENERATION`, `promotion_type` must be `LEAD_GENERATION`; and placement is `PLACEMENT_TYPE_AUTOMATIC` or `PLACEMENT_TYPE_NORMAL` with `PLACEMENT_TIKTOK` included in `placements`. This field can be used to update the value from `false` to `true` only under those conditions. If `is_search_campaign` is `true`, you cannot update it from `false` to `true`.

Secondary goal when `optimization_goal` is `INSTALL` or `VALUE`. When this field is specified, you must also pass `deep_bid_type`.

Whether to disable sharing of ads in this ad group to third-party platforms. `true` is valid only when all of these are met: campaign `objective_type` is one of `APP_PROMOTION`, `WEB_CONVERSIONS`, `REACH`, `TRAFFIC`, `VIDEO_VIEWS`, `ENGAGEMENT`, or `LEAD_GENERATION`; and placement is either `placement_type=PLACEMENT_TYPE_AUTOMATIC` or `placement_type=PLACEMENT_TYPE_NORMAL` with `placements` set to `PLACEMENT_TIKTOK`. This field supports incremental updates.

Valid time range for the audience action to retarget. Required when `shopping_ads_retargeting_type` is `LAB1` or `LAB2`. Allowed values: `1`, `2`, `3`, `7`, `14`, `30`, `60`, `90`, `180`.

Valid only when all are true: `shopping_ads_type=VIDEO`, `product_source=CATALOG`, `shopping_ads_retargeting_type` is `LAB1`, `LAB2`, or `LAB3`, and `audience_ids` is provided. Controls the logical relation between the Video Shopping Ads retargeting audience and the custom audience in `audience_ids`: `OR` combines them, `AND` intersects them. If the custom audience is later removed, this field is automatically reset to null.

Valid when `shopping_ads_type` is `VIDEO` and `product_source` is `CATALOG`. Shopping ads retargeting type: `LAB1` retargets users who viewed products or added to cart but did not purchase, `LAB2` retargets users who added to cart but did not purchase, `LAB3` uses custom combinations, and `OFF` disables retargeting.

Whether to enable Smart Audience.

Whether to enable Smart interests & behaviors.

Spending power targeting. `HIGH` targets users who typically spend more on TikTok ads than average users. Not supported when campaign `objective_type` is `PRODUCT_SALES` or `RF_REACH`. Requires TikTok placement via `placement_type=PLACEMENT_TYPE_AUTOMATIC` or `placements` including `PLACEMENT_TIKTOK`; if Pangle is also selected, spending power does not take effect on Pangle. When `auto_targeting_enabled=true`, `spending_power` is automatically set to `ALL`.

Vertical sensitivity category ID. This field can be updated only if the ad group's `schedule_start_time` has not been reached, or if it has been reached but `operation_status` is `DISABLE` and cost is 0; use `/adgroup/get/` to check those values. Use `/tool/content_exclusion/get/` to retrieve `vertical_sensitivity_list`. Updating Brand Safety settings is allowlist-only.

Zip code IDs or postal code IDs to target. You must provide `location_ids`, `zipcode_ids`, or both. Maximum 3,000 combined IDs across `location_ids`, zip codes, and postal codes per ad group. Obtain zip/postal IDs from `/tool/targeting/search/` using `geo_id` where `geo_type=ZIP_CODE`. Supported for U.S. zip codes and for postal codes in Canada, Brazil, Indonesia, Thailand, and Vietnam; Brazil, Indonesia, Thailand, and Vietnam postal-code targeting is allowlist-only. Not supported when campaign `special_industries` is enabled, when campaign `objective_type` is `RF_REACH`, or when TikTok placement is not included in `placements`. Overlapping locations are not supported. If the ad group originally targeted U.S. locations via `location_ids` or `zipcode_ids`, you can update to other U.S. locations but cannot remove all U.S. locations and target only non-U.S. countries. To remove all zip/postal IDs, set `zipcode_ids` to `[]` and simultaneously provide `location_ids`. This field supports incremental updates.