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 an Ad Group	POST `/ad_groups`
Retrieve an Ad Group	GET `/ad_groups/{id}`
Update an Ad Group	PATCH `/ad_groups/{id}`
Delete an Ad Group	DELETE `/ad_groups/{id}`
Duplicate an Ad Group	POST `/ad_groups/{id}/duplicate`
Pause an Ad Group	POST `/ad_groups/{id}/pause`
Unpause an Ad Group	POST `/ad_groups/{id}/unpause`
Estimate Ad Group Reach	POST `/ad_groups/estimate_reach`
Search Targeting Options	GET `/ad_groups/targeting_options`

Attributes

string

required

Unique identifier for the ad group, prefixed adgrp_.

object

required

The ad campaign this ad group belongs to.

Properties

string

required

The referenced entity’s id.

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.

number

required

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

object

required

Saved audiences this ad group delivers to or excludes.

Properties

string[]

required

IDs of saved audiences excluded from delivery, prefixed adaud_.

string[]

required

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

string | null

required

How delivery bids are set in the ad auction. Target-based strategies use desired_cost_per_result.Available options: minimum_cost, average_target, maximum_target

number | null

required

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

string | null

required

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

number

required

Clicks divided by impressions, between 0 and 1.

number

required

The number of clicks.

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.

number

required

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

number

required

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

number

required

Whop pixel-attributed contact events, last-click.

string | null

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

string | null

Where the outcome being optimized for occurs, such as a website visit, social-profile visit, messaging conversation, ad interaction, or lead-form submission.Available options: website, profile, instagram_and_facebook, instagram_profile, messaging, on_ad, instant_forms, instant_forms_and_messenger, website_and_instant_forms

number | null

required

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

number

required

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

number | null

required

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

number | null

required

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

number | null

required

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

number

required

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

number | null

required

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

number | null

required

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

number | null

required

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

number | null

required

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

number | null

required

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

number | null

required

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

string

required

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

number

required

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

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.

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.

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

object

required

Age, gender, and automatic-audience targeting.

Properties

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.

string

required

Gender targeted.Available options: all, male, female

number | null

required

Oldest age targeted. null when no maximum is set.

number | null

required

Youngest age targeted. null when no minimum is set.

number | null

required

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

object

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

object[]

required

Behavior categories targeted, such as frequent travelers.

Properties

string

required

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

string

Category name, such as Movies.

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.

string

Category name, such as Recently moved.

string

required

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

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.

string

Category name, such as Movies.

object

Device platforms and operating systems targeted.

Properties

object[]

required

Operating systems targeted. Empty targets all operating systems.

Properties

string

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

string

required

Operating system targeted.Available options: ios, android

string[]

required

Device types targeted. Empty targets all devices.Available options: mobile, desktop

boolean

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

string | null

required

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

number | null

required

Platform-reported impressions divided by reach.

object | null

Cap on how often one person sees ads from this ad group. Only available on campaigns with the awareness objective; null when uncapped.

Properties

number

required

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

number | null

required

Length of the rolling window, in days.

number

required

The number of impressions.

object[]

required

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

Properties

string

required

Unique identifier for the issue.

string

required

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

string | null

required

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

string

required

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

string[]

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.

number

required

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

number

required

Whop pixel-attributed leads, last-click.

string[]

Apps the conversation opens in when conversion_location is messaging. Empty for other conversion locations.Available options: messenger, instagram, whatsapp

number | null

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

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

object[]

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

Properties

string

required

Publisher platform where the ad is eligible to appear.Available options: facebook, instagram, messenger, audience_network, threads, whatsapp

string[]

required

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

number

required

USD value of pixel-attributed purchases.

number

required

Whop pixel-attributed purchases, last-click.

number

required

The number of unique people who saw this.

object

Locations targeted and excluded.

Properties

object

required

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

Properties

object[]

required

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

Properties

string

required

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

string

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

string[]

required

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

string[]

required

Multi-country groups such as worldwide or europe.

object[]

required

Circular areas, each a coordinate plus a radius.

Properties

string

required

Unit for radius.Available options: mile, kilometer

number

required

Latitude of the center point.

number

required

Longitude of the center point.

string

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

number

required

Radius around the center point, in distance_unit.

string[]

required

US states and DC, as ISO 3166-2 codes such as US-CA. US territories (PR, GU, VI, AS, MP) and everywhere outside the US are targeted through countries.

string[]

required

ZIP and postal codes.

object

required

Locations the ad group targets.

Properties

object[]

required

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

Properties

string

required

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

string

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

string[]

required

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

string[]

required

Multi-country groups such as worldwide or europe.

object[]

required

Circular areas, each a coordinate plus a radius.

Properties

string

required

Unit for radius.Available options: mile, kilometer

number

required

Latitude of the center point.

number

required

Longitude of the center point.

string

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

number

required

Radius around the center point, in distance_unit.

string[]

required

US states and DC, as ISO 3166-2 codes such as US-CA. US territories (PR, GU, VI, AS, MP) and everywhere outside the US are targeted through countries.

string[]

required

ZIP and postal codes.

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

string | null

required

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

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.

number

required

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

number

required

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

number

required

Whop pixel-attributed schedule events, last-click.

number

required

The amount charged, in spend_currency.

string | null

required

The ISO 4217 currency code of all monetary metrics.

string | null

required

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

string

required

Whether the ad group is enabled. active and paused are set by you; rejected means it failed ad review; duplicating is a copy still being filled in.Available options: active, paused, rejected, duplicating

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.

number

required

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

string | null

required

Display name of the ad group.

number | null

required

Unique clicks divided by impressions, between 0 and 1.

number

required

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

string

required

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

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.

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

Notifications

Money

Commerce

Partners

Workforce

Tracking

Ads

Media

Identity

Developer

Endpoints

Attributes

​Endpoints

​Attributes

Endpoints

Attributes