Sign in
Ad Groups

Update an Ad Group

Updates an ad group's editable fields. Only the keys you send are changed.

patch/ad_groups/{id}

Request body

audiencesobject

Saved-audience targeting: { include, exclude } arrays of audience IDs. Incompatible with demographics.automatic (Advantage+).

bid_type'minimum_cost' | 'average_target' | 'maximum_target'

Bid strategy.

budget_amountnumber

Ad-set budget in dollars (ABO only; omit under CBO).

budget_type'daily' | 'lifetime'

Whether the budget is daily or lifetime.

conversion_location'website' | 'profile' | 'messaging' | 'on_ad' | 'instant_forms' | 'instant_forms_and_messenger' | 'website_and_instant_forms'

Where results happen: website (conversions), profile (IG/FB engagement), messaging (DM), on_ad (engagement on the ad, surface follows the optimization goal), or the lead destinations (instant_forms, instant_forms_and_messenger, website_and_instant_forms). The lead form itself is set on the ad.

demographicsobject

Demographic targeting: { automatic, minimum_age, maximum_age, gender }.

desired_cost_per_resultnumber

Target/cap cost for average_target / maximum_target.

devicesobject

Device targeting: { platforms, operating_systems: [{ os, minimum_version }] }.

ends_atstring

Schedule end, ISO 8601.

frequency_capobject

{ maximum_impressions, per_days } — only valid for reach optimization.

languagesstring[]

Languages to target as ISO 639 codes (e.g. en, es). Empty/omitted = all languages.

message_appsstring[]

Required when conversion_location is messaging: which apps to message on. Combinations map to the matching Meta destination.

minimum_daily_spendnumber

Daily spend floor within the budget.

optimization_goalstring

What the ad group optimizes for (e.g. conversions, link_clicks, reach).

{"stackTrail":"paths:/ad_groups/{id}:patch:requestBody:content:application/json:schema:properties:placements","oasType":"schema","type":"unknown","description":"'automatic' (Advantage+) or a list of { platform, positions }. Omit positions to target all of a platform's.\n\nValid positions per platform:\n\n- `facebook`: `feed`, `right_hand_column`, `marketplace`, `search`, `profile_feed`, `notification`, `story`, `instream_video`, `facebook_reels`, `facebook_reels_overlay`, `biz_disco_feed`\n- `instagram`: `stream`, `story`, `explore`, `explore_home`, `reels`, `profile_feed`, `profile_reels`, `ig_search`\n- `messenger`: `story`\n- `audience_network`: `classic`, `rewarded_video`\n- `threads`: `threads_stream`\n- `whatsapp`: `status`"}
regionsobject

Geo targeting: { include / exclude: { countries (ISO 3166-1), regions (states/provinces as ISO 3166-2, e.g. US-CA), cities (keyed), zips } }.

starts_atstring

Schedule start, ISO 8601.

status'active' | 'paused'

Initial status (default: active).

titlestring

The display name of the ad group.

Response

ad group updated

added_to_cartsnumber required

Whop pixel-attributed add-to-cart events, last-click.

audiencesobject required

Saved-audience targeting: { include, exclude } arrays of audience IDs.

bid_type'minimum_cost' | 'average_target' | 'maximum_target' | 'null' nullable required

Bid strategy.

budget_amountnumber nullable required

Ad-set budget; null when the campaign owns budget (CBO).

budget_type'daily' | 'lifetime' | 'null' nullable required

Whether the budget is daily or lifetime.

click_through_ratenumber required

Clicks divided by impressions, between 0 and 1.

clicksnumber required

The number of clicks.

completed_registrationsnumber required

Whop pixel-attributed complete-registration events, last-click.

contactsnumber required

Whop pixel-attributed contact events, last-click.

conversion_location'website' | 'profile' | 'messaging' | 'on_ad' | 'instant_forms' | 'instant_forms_and_messenger' | 'website_and_instant_forms' | 'null' nullable required

Where results happen: website, profile (IG/FB), messaging (DM), on_ad (engagement), or the lead destinations (instant_forms, instant_forms_and_messenger, website_and_instant_forms).

cost_per_added_to_cartnumber nullable required

Spend divided by attributed add-to-cart events; null when they are not the goal and none are attributed.

cost_per_clicknumber required

Spend divided by clicks; 0 when there are no clicks.

cost_per_completed_registrationnumber nullable required

Spend divided by attributed complete-registration events; null when they are not the goal and none are attributed.

cost_per_contactnumber nullable required

Spend divided by attributed contact events; null when contacts are not the goal and none are attributed.

cost_per_leadnumber nullable required

Spend divided by attributed leads; null when leads are not a goal and none are attributed.

cost_per_millenumber required

Spend per 1,000 impressions; 0 when there are no impressions.

cost_per_purchasenumber nullable required

Spend divided by attributed purchases; null when purchases are not a goal and none are attributed.

cost_per_resultnumber nullable required

Spend divided by Whop pixel-attributed results; null when nothing Whop-attributable is being optimized for.

cost_per_schedulenumber nullable required

Spend divided by attributed schedule events; null when schedules are not the goal and none are attributed.

cost_per_submitted_applicationnumber nullable required

Spend divided by attributed submit-application events; null when they are not the goal and none are attributed.

cost_per_viewed_contentnumber nullable required

Spend divided by attributed view-content events; null when they are not the goal and none are attributed.

created_atstring required

When the ad group was created, ISO 8601.

custom_conversionsnumber required

Whop pixel-attributed custom (merchant-defined) conversion events, last-click, across all custom event names.

custom_event_countsobject required

Whop pixel-attributed custom conversions broken out by merchant-defined event name, last-click, as a { event_name => count } map over the stats window. Empty when no named custom events are attributed. Custom events fired without a name are counted in custom_conversions but omitted here, so these values sum to at most custom_conversions.

delivery_status'all_ads_rejected' | 'rejected' | 'draft' | 'no_ads' | 'campaign_paused' | 'paused' | 'processing' | 'issues' | 'scheduled' | 'completed' | 'ads_off' | 'learning_limited' | 'learning' | 'active' required

The current delivery state, mirroring the Delivery column in the ads dashboard. When several states apply at once, the highest-precedence one is returned.

demographicsobject required

Demographic targeting: automatic (Advantage+), age range, gender.

desired_cost_per_resultnumber nullable required

Target/cap cost for average_target / maximum_target.

devicesobject required

Device targeting: platforms and operating systems.

dynamic_creativeboolean required

Whether ads within this ad group have their creatives and copy dynamically AB tested.

ends_atstring nullable required

Schedule end, ISO 8601.

frequencynumber nullable required

Platform-reported impressions divided by reach.

frequency_capobject nullable required

Impression cap; only valid for reach optimization.

idstring required

Unique identifier for the ad group.

impressionsnumber required

The number of impressions.

languagesstring[] required
leadsnumber required

Whop pixel-attributed leads, last-click.

message_appsstring[] required
minimum_daily_spendnumber nullable required

Daily spend floor within the budget.

optimization_goalstring nullable required

What the ad group optimizes for.

placementsobject[] required
purchase_valuenumber required

USD value of pixel-attributed purchases.

purchasesnumber required

Whop pixel-attributed purchases, last-click.

reachnumber required

The number of unique people who saw this.

regionsobject required

Geo targeting: include/exclude countries, regions (ISO 3166-2 states, e.g. US-CA), cities, zips.

result_event'purchase' | 'lead' | 'schedule' | 'submit_application' | 'contact' | 'complete_registration' | 'view_content' | 'add_to_cart' | 'custom' | 'null' nullable required

The Whop pixel conversion event whose attributed count represents results — the optimization goal, or the highest-volume attributed event for campaigns that budget per ad group. Null when the goal isn't a Whop-attributed event.

result_event_namestring nullable required

The merchant-defined event name when result_event is custom; null for the standard events.

resultsnumber nullable required

The Whop pixel-attributed count behind result_event. When a campaign's ad groups optimize different goals there is no single result_event (it is null), and this is instead the sum of each ad group's own attributed results. Null when nothing Whop-attributable is being optimized for.

return_on_ad_spendnumber required

Purchase value divided by spend, both in USD (a currency-neutral ratio); 0 when there is no spend.

schedulesnumber required

Whop pixel-attributed schedule events, last-click.

spendnumber required

The amount charged, in spend_currency.

spend_currencystring nullable required

The ISO 4217 currency code of all monetary metrics.

starts_atstring nullable required

Schedule start, ISO 8601.

status'active' | 'paused' | 'rejected' required

Delivery status of the ad group.

submitted_applicationsnumber required

Whop pixel-attributed submit-application events, last-click.

titlestring nullable required

The display title of the ad group.

unique_click_through_ratenumber nullable required

Unique clicks divided by impressions, between 0 and 1.

unique_clicksnumber required

The number of unique clicks.

updated_atstring required

When the ad group was last updated, ISO 8601.

viewed_contentsnumber required

Whop pixel-attributed view-content events, last-click.

Example response

{
  "bid_type": "minimum_cost",
  "budget_type": "daily",
  "conversion_location": "website",
  "delivery_status": "all_ads_rejected",
  "issues": [
    {
      "resource_type": "ad_campaign"
    }
  ],
  "result_event": "purchase",
  "status": "active"
}

Changes