Ad Group

An Ad Group sits inside an ad campaign and controls delivery for ads. It sets the audience, placements, schedule, budget, and optimization goal for its ads. Use the Ad Groups API to create ad groups in campaigns, list or retrieve targeting and delivery settings, update budgets or targeting, delete groups that should stop running, and pause or resume delivery. It can also search the ad platform’s targeting taxonomy for options to target and estimate how many people a draft targeting spec can reach.

Endpoints

Endpoint	Request
List Ad Groups	GET `/ad_groups`
Create Ad Group	POST `/ad_groups`
Retrieve Ad Group	GET `/ad_groups/{id}`
Update Ad Group	PATCH `/ad_groups/{id}`
Delete Ad Group	DELETE `/ad_groups/{id}`
Pause Ad Group	POST `/ad_groups/{id}/pause`
Unpause Ad Group	POST `/ad_groups/{id}/unpause`

Attributes

string

required

Unique identifier for the ad group, prefixed adgrp_.

ad_campaign

object

required

The ad campaign this ad group belongs to.

Properties

string

required

The referenced entity’s id.

added_to_cart_value

number

required

USD value attributed to add-to-cart events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.

added_to_carts

number

required

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

audiences

object

required

Saved audiences this ad group delivers to or excludes.

Properties

exclude

string[]

required

IDs of saved audiences excluded from delivery, prefixed adaud_.

include

string[]

required

IDs of saved audiences the ad group delivers to, prefixed adaud_.

bid_type

string | null

required

How delivery bids in the ad auction: minimum_cost gets the most results for the budget, average_target keeps the average cost per result near desired_cost_per_result, and maximum_target never bids above it.Available options: minimum_cost, average_target, maximum_target

budget_amount

number | null

required

This ad group’s budget, in the ad account’s currency. null when the budget is set on the campaign instead.

budget_type

string | null

required

Whether budget_amount is spent per day (daily) or over the ad group’s full run (lifetime).Available options: daily, lifetime

click_through_rate

number

required

Clicks divided by impressions, between 0 and 1.

clicks

number

required

The number of clicks.

completed_registration_value

number

required

USD value attributed to complete-registration events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.

completed_registrations

number

required

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

contact_value

number

required

USD value attributed to contact events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.

contacts

number

required

Whop pixel-attributed contact events, last-click.

conversion_event

string | null

required

The pixel event optimized for. A standard event, or any custom pixel event name.

conversion_location

string | null

required

Where the result you’re optimizing for happens: website (your site), profile (your social media profile), instagram_and_facebook or instagram_profile (visits to your Instagram profile), messaging (a direct-message conversation), on_ad (engagement with the ad itself), or a lead form (instant_forms, instant_forms_and_messenger, website_and_instant_forms).Available options: website, profile, instagram_and_facebook, instagram_profile, messaging, on_ad, instant_forms, instant_forms_and_messenger, website_and_instant_forms

cost_per_added_to_cart

number | null

required

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

cost_per_click

number

required

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

cost_per_completed_registration

number | null

required

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

cost_per_contact

number | null

required

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

cost_per_lead

number | null

required

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

cost_per_mille

number

required

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

cost_per_purchase

number | null

required

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

cost_per_result

number | null

required

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

cost_per_schedule

number | null

required

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

cost_per_submitted_application

number | null

required

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

cost_per_unique_click

number | null

required

Spend divided by unique clicks; null when there are no unique clicks.

cost_per_viewed_content

number | null

required

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

created_at

string

required

When the ad group was created, as an ISO 8601 timestamp.

custom_conversions

number

required

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

custom_event_counts

object

required

Whop pixel-attributed custom conversions, keyed by your event name with its last-click count as the value. 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.

custom_event_values

object

required

Conversion value attributed to each custom event, keyed by event name like custom_event_counts. Sums the value passed to whop.track, normalized to USD; events fired without a value contribute 0.

delivery_status

string

required

Whether ads in this ad group are delivering right now, and if not, why. When several states apply at once, the highest-precedence one is returned.Available options: all_ads_rejected, rejected, draft, no_ads, campaign_paused, paused, processing, issues, scheduled, completed, ads_off, learning_limited, learning, active

demographics

object

required

Age, gender, and automatic-audience targeting.

Properties

automatic

boolean

required

Whether automatic audience targeting is on (Advantage+ on Meta). When true, the platform can deliver beyond the ages, genders, and detailed targeting you set, treating them as suggestions.

gender

string

required

Gender targeted.Available options: all, male, female

maximum_age

number | null

required

Oldest age targeted. null when no maximum is set.

minimum_age

number | null

required

Youngest age targeted. null when no minimum is set.

desired_cost_per_result

number | null

required

Cost per result to aim for (average_target) or never exceed (maximum_target). null for minimum_cost bidding.

detailed_targeting

object

required

Interest, behavior, and demographic targeting, using categories from the ad platform’s targeting taxonomy. Can’t be combined with automatic audience targeting, and unavailable to campaigns with special_ad_categories.

Properties

behaviors

object[]

required

Behavior categories targeted, such as frequent travelers.

Properties

string

required

The ad platform’s ID for the category in its targeting taxonomy.

name

string

Category name, such as Movies.

demographics

object[]

required

Demographic categories targeted, such as life events or industries.

Properties

string

required

The ad platform’s ID for the category in its targeting taxonomy.

name

string

Category name, such as Recently moved.

type

string

required

Kind of demographic the category belongs to.Available options: life_events, industries, income, family_statuses

interests

object[]

required

Interest categories targeted, such as an interest in movies.

Properties

string

required

The ad platform’s ID for the category in its targeting taxonomy.

name

string

Category name, such as Movies.

devices

object

required

Device platforms and operating systems targeted.

Properties

operating_systems

object[]

required

Operating systems targeted. Empty targets all operating systems.

Properties

minimum_version

string

Lowest OS version targeted, such as 18.0. Absent when any version qualifies.

string

required

Operating system targeted.Available options: ios, android

platforms

string[]

required

Device types targeted. Empty targets all devices.

dynamic_creative

boolean

required

Whether the ad platform automatically mixes and matches this ad group’s creatives and copy to find the best-performing combinations.

ends_at

string | null

required

When the ad group stops delivering, as an ISO 8601 timestamp. null when it runs until paused.

frequency

number | null

required

Platform-reported impressions divided by reach.

frequency_cap

object | null

required

Cap on how often one person sees ads from this ad group. Only available with reach optimization; null when uncapped.

Properties

maximum_impressions

number

required

Most times one person can be shown ads from this ad group within the window.

per_days

number | null

required

Length of the rolling window, in days.

impressions

number

required

The number of impressions.

issues

object[]

required

Open issues affecting this ad group and its ads. Empty when there are none.

Properties

string

required

Unique identifier for the issue.

message

string

required

A description of what the issue is and how it can be resolved.

resource_id

string | null

required

The ID of the campaign, ad group, or ad the issue is attached to.

resource_type

string

required

The type of resource the issue is attached to.Available options: ad_campaign, ad_group, ad

languages

string[]

required

Languages targeted, as ISO 639 codes such as en or es. A region-specific locale with no ISO code appears as its numeric platform locale key. Empty targets all languages.

lead_value

number

required

USD value attributed to lead events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.

leads

number

required

Whop pixel-attributed leads, last-click.

message_apps

string[]

required

Apps the conversation opens in when conversion_location is messaging. Empty for other conversion locations.

minimum_daily_spend

number | null

required

Minimum the ad group tries to spend each day. null when no floor is set.

optimization_goal

string | null

required

The result the ad group’s delivery is optimized to get the most of.Available options: conversions, link_clicks, landing_page_views, reach, impressions, engagement, conversations, video_views, two_second_views, page_likes, social_profile, ad_recall_lift, event_responses, reminders_set, lead_generation, quality_lead, value, profile_and_page_engagement

placements

object[]

required

Where ads can appear, per platform. Empty when placements are chosen automatically.

Properties

platform

string

required

Platform the ads run on: facebook, instagram, messenger, audience_network, threads, or whatsapp.

positions

string[]

required

Positions targeted within the platform, such as feed or story. Empty targets all of the platform’s positions.

purchase_value

number

required

USD value of pixel-attributed purchases.

purchases

number

required

Whop pixel-attributed purchases, last-click.

reach

number

required

The number of unique people who saw this.

regions

object

required

Locations targeted and excluded.

Properties

exclude

object

required

Locations excluded from targeting. Country groups can’t be excluded.

Properties

cities

object[]

required

Cities, keyed by the ad platform’s location taxonomy.

Properties

key

string

required

The ad platform’s key for the city in its location taxonomy.

name

string

City name, such as Austin. Absent when the platform doesn’t return one.

countries

string[]

required

Countries, as ISO 3166-1 alpha-2 codes such as US.

country_groups

string[]

required

Multi-country groups such as worldwide or europe.

custom_locations

object[]

required

Circular areas, each a coordinate plus a radius.

Properties

distance_unit

string

required

Unit for radius.Available options: mile, kilometer

latitude

number

required

Latitude of the center point.

longitude

number

required

Longitude of the center point.

name

string

Label for the location, such as a city or address. Absent when the location has no label.

radius

number

required

Radius around the center point, in distance_unit.

regions

string[]

required

States and provinces, as ISO 3166-2 codes such as US-CA.

zips

string[]

required

ZIP and postal codes.

include

object

required

Locations the ad group targets.

Properties

cities

object[]

required

Cities, keyed by the ad platform’s location taxonomy.

Properties

key

string

required

The ad platform’s key for the city in its location taxonomy.

name

string

City name, such as Austin. Absent when the platform doesn’t return one.

countries

string[]

required

Countries, as ISO 3166-1 alpha-2 codes such as US.

country_groups

string[]

required

Multi-country groups such as worldwide or europe.

custom_locations

object[]

required

Circular areas, each a coordinate plus a radius.

Properties

distance_unit

string

required

Unit for radius.Available options: mile, kilometer

latitude

number

required

Latitude of the center point.

longitude

number

required

Longitude of the center point.

name

string

Label for the location, such as a city or address. Absent when the location has no label.

radius

number

required

Radius around the center point, in distance_unit.

regions

string[]

required

States and provinces, as ISO 3166-2 codes such as US-CA.

zips

string[]

required

ZIP and postal codes.

result_event

string | null

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.Available options: purchase, lead, schedule, submit_application, contact, complete_registration, view_content, add_to_cart, custom

result_event_name

string | null

required

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

results

number | null

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_spend

number

required

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

schedule_value

number

required

USD value attributed to schedule events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.

schedules

number

required

Whop pixel-attributed schedule events, last-click.

spend

number

required

The amount charged, in spend_currency.

spend_currency

string | null

required

The ISO 4217 currency code of all monetary metrics.

starts_at

string | null

required

When the ad group starts delivering, as an ISO 8601 timestamp. null when it starts as soon as it’s active.

status

string

required

Whether the ad group is enabled. active and paused are set by you; rejected means it failed ad review.Available options: active, paused, rejected

submitted_application_value

number

required

USD value attributed to submit-application events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.

submitted_applications

number

required

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

title

string | null

required

Display name of the ad group.

unique_click_through_rate

number | null

required

Unique clicks divided by impressions, between 0 and 1.

unique_clicks

number

required

People who clicked, reported by the Whop pixel, counted once per person.

updated_at

string

required

When the ad group was last updated, as an ISO 8601 timestamp.

viewed_content_value

number

required

USD value attributed to view-content events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.

viewed_contents

number

required

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

AdGroup

{
	"id": "adgrp_xxxxxxxxxxx",
	"ad_campaign": {
		"id": "adcamp_xxxxxxxxxx"
	},
	"added_to_cart_value": 1050,
	"added_to_carts": 24,
	"audiences": {
		"exclude": [],
		"include": ["adaud_xxxxxxxxxxx"]
	},
	"bid_type": "minimum_cost",
	"budget_amount": 100,
	"budget_type": "daily",
	"click_through_rate": 0.036,
	"clicks": 720,
	"completed_registration_value": 0,
	"completed_registrations": 16,
	"contact_value": 0,
	"contacts": 10,
	"conversion_event": "purchase",
	"conversion_location": "website",
	"cost_per_added_to_cart": 8.33,
	"cost_per_click": 0.28,
	"cost_per_completed_registration": 12.5,
	"cost_per_contact": 20,
	"cost_per_lead": 13.33,
	"cost_per_mille": 10,
	"cost_per_purchase": 25,
	"cost_per_result": 25,
	"cost_per_schedule": null,
	"cost_per_submitted_application": null,
	"cost_per_unique_click": 0.33,
	"cost_per_viewed_content": 0.67,
	"created_at": "2026-06-01T12:00:00Z",
	"custom_conversions": 5,
	"custom_event_counts": {
		"QualifiedCall": 4,
		"BookedDemo": 1
	},
	"custom_event_values": {
		"QualifiedCall": 2000,
		"BookedDemo": 0
	},
	"delivery_status": "issues",
	"demographics": {
		"automatic": false,
		"minimum_age": 21,
		"maximum_age": 45,
		"gender": "all"
	},
	"desired_cost_per_result": 30,
	"detailed_targeting": {
		"interests": [
			{
				"id": "6003139266461",
				"name": "Movies"
			}
		],
		"behaviors": [
			{
				"id": "6002714895372",
				"name": "Frequent travelers"
			}
		],
		"demographics": [
			{
				"id": "6015559470583",
				"name": "Recently moved",
				"type": "life_events"
			}
		]
	},
	"devices": {
		"platforms": ["mobile", "desktop"],
		"operating_systems": [
			{
				"os": "ios",
				"minimum_version": "18.0"
			}
		]
	},
	"dynamic_creative": false,
	"ends_at": "2026-07-01T12:00:00Z",
	"frequency": 1.6,
	"frequency_cap": null,
	"impressions": 20000,
	"issues": [
		{
			"id": "adiss_xxxxxxxxxxx",
			"message": "The audience is too narrow to deliver. Broaden the targeting to reach more people.",
			"resource_id": "adgrp_xxxxxxxxxxx",
			"resource_type": "ad_group"
		}
	],
	"languages": ["en"],
	"lead_value": 750,
	"leads": 15,
	"message_apps": [],
	"minimum_daily_spend": 25,
	"optimization_goal": "conversions",
	"placements": [
		{
			"platform": "instagram",
			"positions": ["stream", "story"]
		}
	],
	"purchase_value": 5200,
	"purchases": 8,
	"reach": 12500,
	"regions": {
		"include": {
			"countries": ["US"],
			"country_groups": [],
			"regions": ["US-CA"],
			"cities": [
				{
					"key": "2418779",
					"name": "Miami"
				}
			],
			"zips": [],
			"custom_locations": [
				{
					"latitude": 30.2672,
					"longitude": -97.7431,
					"radius": 10,
					"distance_unit": "mile",
					"name": "Austin, TX"
				}
			]
		},
		"exclude": {
			"countries": [],
			"country_groups": [],
			"regions": [],
			"cities": [
				{
					"key": "2421215",
					"name": "Anchorage"
				}
			],
			"zips": [],
			"custom_locations": [
				{
					"latitude": 40.758,
					"longitude": -73.9855,
					"radius": 2,
					"distance_unit": "mile",
					"name": "Times Square"
				}
			]
		}
	},
	"result_event": "purchase",
	"result_event_name": null,
	"results": 8,
	"return_on_ad_spend": 26,
	"schedule_value": 0,
	"schedules": 0,
	"spend": 200,
	"spend_currency": "usd",
	"starts_at": "2026-06-01T12:00:00Z",
	"status": "active",
	"submitted_application_value": 0,
	"submitted_applications": 0,
	"title": "US founders",
	"unique_click_through_rate": 0.03,
	"unique_clicks": 600,
	"updated_at": "2026-06-02T12:00:00Z",
	"viewed_content_value": 0,
	"viewed_contents": 300
}

Introduction

Reference

Core Resources

Money

Commerce

Partners

Workforce

Tracking

Ads

Media

Identity

Developer

Endpoints

Attributes

​Endpoints

​Attributes

Endpoints

Attributes