Ad Group

An Ad Group sits inside an ad campaign and controls delivery for ads. It sets the audience, schedule, and budget 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.

Endpoints

Endpoint	Request
List Ad Groups	GET `/ad_groups`
Retrieve an Ad Group	GET `/ad_groups/{id}`
Create an Ad Group	POST `/ad_groups`
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`
Update an Ad Group	PATCH `/ad_groups/{id}`
Delete an Ad Group	DELETE `/ad_groups/{id}`

Targeting restrictions

Ad groups cannot target the countries listed in the advertising guide. Requests to create an ad group or update its targeted countries are rejected if they include a blocked country in regions.include.countries.

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 USD, which is what it is stored and billed in. null when the budget is set on the campaign instead.

number | null

required

The same budget stated in budget_currency at today’s exchange rate, for display in the account’s ads reporting currency. null when budget_amount is.

string

required

The ISO 4217 code budget_amount_local is in: the account’s ads_reporting_currency preference. usd unless the account changed it.

string | null

required

Whether budget_amount is spent per day (daily) or over the ad group’s full run (lifetime). A lifetime ad group also needs ends_at, at least 24 hours after it starts.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

required

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

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.

object | null

required

Hours the ad group delivers in each week, keyed by day. Days it doesn’t deliver are omitted. null when it delivers at every hour. Some platforms need a lifetime budget_type for a schedule, on the ad group or on its campaign when the campaign holds the budget.

Properties

object[]

Windows the ad group delivers in on Friday, in time order. Omitted when it doesn’t deliver that day.

Properties

string

required

When delivery stops, as a 24-hour HH:00 time up to 24:00 for midnight. Later than start; a window past midnight is split across two days.

string

required

When delivery starts, as a 24-hour HH:00 time from 00:00 to 23:00.

object[]

Windows the ad group delivers in on Monday, in time order. Omitted when it doesn’t deliver that day.

Properties

string

required

When delivery stops, as a 24-hour HH:00 time up to 24:00 for midnight. Later than start; a window past midnight is split across two days.

string

required

When delivery starts, as a 24-hour HH:00 time from 00:00 to 23:00.

object[]

Windows the ad group delivers in on Saturday, in time order. Omitted when it doesn’t deliver that day.

Properties

string

required

When delivery stops, as a 24-hour HH:00 time up to 24:00 for midnight. Later than start; a window past midnight is split across two days.

string

required

When delivery starts, as a 24-hour HH:00 time from 00:00 to 23:00.

object[]

Windows the ad group delivers in on Sunday, in time order. Omitted when it doesn’t deliver that day.

Properties

string

required

When delivery stops, as a 24-hour HH:00 time up to 24:00 for midnight. Later than start; a window past midnight is split across two days.

string

required

When delivery starts, as a 24-hour HH:00 time from 00:00 to 23:00.

object[]

Windows the ad group delivers in on Thursday, in time order. Omitted when it doesn’t deliver that day.

Properties

string

required

When delivery stops, as a 24-hour HH:00 time up to 24:00 for midnight. Later than start; a window past midnight is split across two days.

string

required

When delivery starts, as a 24-hour HH:00 time from 00:00 to 23:00.

object[]

Windows the ad group delivers in on Tuesday, in time order. Omitted when it doesn’t deliver that day.

Properties

string

required

When delivery stops, as a 24-hour HH:00 time up to 24:00 for midnight. Later than start; a window past midnight is split across two days.

string

required

When delivery starts, as a 24-hour HH:00 time from 00:00 to 23:00.

object[]

Windows the ad group delivers in on Wednesday, in time order. Omitted when it doesn’t deliver that day.

Properties

string

required

When delivery stops, as a 24-hour HH:00 time up to 24:00 for midnight. Later than start; a window past midnight is split across two days.

string

required

When delivery starts, as a 24-hour HH:00 time from 00:00 to 23:00.

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: in_appeal, 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. When true, delivery can reach beyond the ages and genders 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

required

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

string | null

required

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

number | null

required

Impressions divided by reach.

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

The kind of issue: information about delivery, a warning, or an error requiring attention.Available options: information, warning, error

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

required

A short, creator-facing title for the issue.

object[]

Search terms this ad group’s ads can show for, and terms they never show for. Search campaigns only, where each ad group needs at least one before launch.

Properties

string

required

How closely a search has to match: broad also reaches related searches, phrase needs the meaning of the phrase, and exact needs the same meaning as the term. Defaults to broad.Available options: broad, phrase, exact

boolean

required

Whether this term keeps the ads from showing instead of making them eligible. Defaults to false.

string

required

The search term, up to 80 characters and 10 words.

string[]

required

Languages targeted, as ISO 639 codes such as en or es. A region-specific locale with no ISO code appears as a numeric 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.

object | null

required

Progress toward the conversions this ad group’s learning phase needs. Null unless it is learning or learning limited and valid counts are available. Reaching the threshold does not determine delivery status.

Properties

integer

required

The conversions this ad group’s learning phase needs. It can change during delivery.

integer

required

Conversions counted since the last significant edit during this ad group’s learning phase.

number

required

Conversions divided by the threshold, as a percentage clamped to 0–100. The ad group’s delivery_status remains authoritative.

number

required

Page views on your destination from people who clicked the ad, recorded by the Whop pixel. Counted the same way on every ad platform.

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

required

Locations targeted and excluded.

Properties

object

required

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

Properties

object[]

required

Cities, keyed by the location taxonomy.

Properties

string

required

The city’s key in the location taxonomy.

string

City name, such as Austin. Absent when the location taxonomy has none.

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

ISO 3166-1 alpha-2 country the point falls in. Send it under a special ad category, where the campaign must declare the countries its ad sets reach.

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, keyed as COUNTRY:CODE, such as US:78756.

object

required

Locations the ad group targets.

Properties

object[]

required

Cities, keyed by the location taxonomy.

Properties

string

required

The city’s key in the location taxonomy.

string

City name, such as Austin. Absent when the location taxonomy has none.

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

ISO 3166-1 alpha-2 country the point falls in. Send it under a special ad category, where the campaign must declare the countries its ad sets reach.

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, keyed as COUNTRY:CODE, such as US:78756.

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, messaging_conversation

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_amount_local": 100,
	"budget_currency": "usd",
	"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",
	"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",
	"learning_progress": null,
	"demographics": {
		"automatic": false,
		"minimum_age": 21,
		"maximum_age": 45,
		"gender": "all"
	},
	"delivery_schedule": {
		"monday": [
			{
				"start": "09:00",
				"end": "17:00"
			}
		],
		"tuesday": [
			{
				"start": "09:00",
				"end": "17:00"
			}
		],
		"wednesday": [
			{
				"start": "09:00",
				"end": "17:00"
			}
		],
		"thursday": [
			{
				"start": "09:00",
				"end": "17:00"
			}
		],
		"friday": [
			{
				"start": "09:00",
				"end": "12:00"
			},
			{
				"start": "16:00",
				"end": "20:00"
			}
		],
		"saturday": [
			{
				"start": "10:00",
				"end": "14:00"
			}
		],
		"sunday": [
			{
				"start": "12:00",
				"end": "16:00"
			}
		]
	},
	"desired_cost_per_result": 30,
	"devices": {
		"platforms": ["mobile", "desktop"],
		"operating_systems": [
			{
				"os": "ios",
				"minimum_version": "18.0"
			}
		]
	},
	"ends_at": "2026-07-01T12:00:00Z",
	"frequency": 1.6,
	"impressions": 20000,
	"issues": [
		{
			"id": "adiss_xxxxxxxxxxx",
			"category": "error",
			"title": "Ad issue",
			"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,
	"link_clicks": 576,
	"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

Payments

Money

Commerce

Websites

Ads

Analytics

Communication

Partners

Workforce

Media

Developer

Endpoints

Targeting restrictions

Attributes

​Endpoints

​Targeting restrictions

​Attributes

Endpoints

Targeting restrictions

Attributes