Create an Ad Group

Creates an ad group (ad set) in a campaign.

POST /ad_groups

JavaScript

JavaScript

import Whop from '@whop/sdk';

const client = new Whop({
  apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted
});

const adGroup = await client.adGroups.create({ ad_campaign_id: 'adcamp_xxxxxxxxxxxxxx' });

console.log(adGroup.id);

200

{
  "ad_campaign": {
    "id": "adcamp_xxxxxxxxxxxxxx"
  },
  "added_to_cart_value": 12650,
  "added_to_carts": 165,
  "audiences": {
    "exclude": [
      "adaud_xxxxxxxxxxxxxx"
    ],
    "include": [
      "adaud_xxxxxxxxxxxxxx"
    ]
  },
  "bid_type": "average_target",
  "budget_amount": 60,
  "budget_type": "daily",
  "click_through_rate": 0.025,
  "clicks": 5500,
  "completed_registration_value": 1650,
  "completed_registrations": 55,
  "contact_value": 2640,
  "contacts": 88,
  "cost_per_added_to_cart": 8,
  "cost_per_click": 0.24,
  "cost_per_completed_registration": 24,
  "cost_per_contact": 15,
  "cost_per_lead": 10,
  "cost_per_mille": 6,
  "cost_per_purchase": 30,
  "cost_per_result": 40,
  "cost_per_schedule": 22,
  "cost_per_submitted_application": 120,
  "cost_per_unique_click": 0.4,
  "cost_per_viewed_content": 1.1,
  "created_at": "2026-01-01T12:00:00.000Z",
  "custom_conversions": 41,
  "custom_event_counts": {
    "gift_card_purchased": 5,
    "quote_requested": 33
  },
  "custom_event_values": {
    "gift_card_purchased": 750,
    "quote_requested": 0
  },
  "delivery_status": "no_ads",
  "demographics": {
    "automatic": false,
    "gender": "all",
    "maximum_age": 64,
    "minimum_age": 21
  },
  "desired_cost_per_result": 40,
  "detailed_targeting": {
    "behaviors": [
      {
        "id": "6007101291578",
        "behavior_type": "video",
        "name": "Recent vehicle purchase (30 days)",
        "period": 123
      }
    ],
    "demographics": [
      {
        "id": "6002714398172",
        "type": "life_events",
        "name": "Recently moved"
      }
    ],
    "interests": [
      {
        "id": "6003193685204",
        "name": "Car wash"
      }
    ]
  },
  "devices": {
    "operating_systems": [
      {
        "os": "ios",
        "minimum_version": "18.0"
      }
    ],
    "platforms": [
      "mobile"
    ]
  },
  "ends_at": "2026-01-01T12:00:00.000Z",
  "frequency": 123,
  "frequency_cap": {
    "maximum_impressions": 3,
    "per_days": 7
  },
  "id": "adgrp_xxxxxxxxxxxxxx",
  "impressions": 220000,
  "issues": [
    {
      "id": "adiss_xxxxxxxxxxxxxx",
      "message": "Your ad was rejected for unacceptable business practices. Edit the ad's content and resubmit.",
      "resource_id": "ad_xxxxxxxxxxxxxx",
      "resource_type": "ad"
    }
  ],
  "languages": [
    "en"
  ],
  "lead_value": 3960,
  "leads": 132,
  "optimization_goal": "conversions",
  "placements": [
    {
      "platform": "facebook",
      "positions": [
        "feed"
      ]
    }
  ],
  "purchase_value": 7920,
  "purchases": 44,
  "reach": 0,
  "regions": {
    "exclude": {
      "cities": [
        {
          "key": "2418046",
          "name": "Austin"
        }
      ],
      "countries": [
        "US"
      ],
      "country_groups": [
        "north_america"
      ],
      "custom_locations": [
        {
          "distance_unit": "mile",
          "latitude": 30.2672,
          "longitude": -97.7431,
          "radius": 25,
          "name": "4180 Burnet Rd, Austin TX 78756"
        }
      ],
      "regions": [
        "US-TX"
      ],
      "zips": [
        "78756"
      ]
    },
    "include": {
      "cities": [
        {
          "key": "2418046",
          "name": "Austin"
        }
      ],
      "countries": [
        "US"
      ],
      "country_groups": [
        "north_america"
      ],
      "custom_locations": [
        {
          "distance_unit": "mile",
          "latitude": 30.2672,
          "longitude": -97.7431,
          "radius": 25,
          "name": "4180 Burnet Rd, Austin TX 78756"
        }
      ],
      "regions": [
        "US-TX"
      ],
      "zips": [
        "78756"
      ]
    }
  },
  "result_event": "custom",
  "result_event_name": "quote_requested",
  "results": 33,
  "return_on_ad_spend": 6,
  "schedule_value": 5400,
  "schedules": 60,
  "spend": 1320,
  "spend_currency": "usd",
  "starts_at": "2026-01-01T12:00:00.000Z",
  "status": "active",
  "submitted_application_value": 1320,
  "submitted_applications": 11,
  "title": "Austin ceramic coating — repeat customers",
  "unique_click_through_rate": 123,
  "unique_clicks": 3300,
  "updated_at": "2026-01-01T12:00:00.000Z",
  "viewed_content_value": 8400,
  "viewed_contents": 1200,
  "conversion_event": "purchase",
  "conversion_location": "website",
  "dynamic_creative": false,
  "message_apps": [
    "instagram"
  ],
  "minimum_daily_spend": 25
}

Authorizations

Authorization · string · header · required

An Account API key, account-scoped JWT, App API key, or user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************.

Headers

Idempotency-Key · string

A unique key that makes this request safe to retry. See Idempotent requests.

Maximum string length: 255

Example:

"d9105228-4a08-46b1-8b91-42fed586d383"

Api-Version-Date · string

Pins the request to a dated API version.

Example:

"2026-08-21"

Body

application/json

ad_campaign_id · string · required

The ad campaign to create the ad group in, prefixed adcamp_.

Example:

"adcamp_xxxxxxxxxxxxxx"

audiences · Audiences · object

Saved audiences to deliver to or exclude. Can't be combined with demographics.automatic.

Show child attributes

bid_type · enum<string>

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

Example:

"average_target"

budget_amount · number

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

Example:

40

budget_type · enum<string>

Whether budget_amount is spent per day (daily) or over the ad group's full run (lifetime).

Available options: daily, lifetime

Example:

"daily"

conversion_event · enum<string> string

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

Available options: purchase, add_to_cart, initiated_checkout, add_payment_info, complete_registration, lead, content_view, search, contact, customize_product, donate, find_location, schedule, start_trial, submit_application, subscribe

Example:

"purchase"

conversion_location · enum<string>

Where the outcome being optimized for occurs, such as a website visit, social-profile visit, messaging conversation, ad interaction, or lead-form submission. The lead form itself is set on the ad.

Available options: website, profile, instagram_and_facebook, instagram_profile, messaging, on_ad, instant_forms, instant_forms_and_messenger, website_and_instant_forms

Example:

"website"

demographics · Demographics · object

Age, gender, and automatic-audience targeting.

Show child attributes

desired_cost_per_result · number

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

Example:

35

detailed_targeting · Detailed targeting · object

Interest, behavior, and demographic targeting, using categories from the ad platform's targeting taxonomy. Entries across interests, behaviors, and demographics are OR'd together (anyone matching any entry is reached), matching Ads Manager's detailed-targeting box. At most 100 entries per section. Can't be combined with demographics.automatic, and unavailable to campaigns with special_ad_categories. Send the complete intended state — a section you omit is cleared.

Show child attributes

devices · Devices · object

Device platforms and operating systems to target.

Show child attributes

dynamic_creative · boolean

Let the ad platform automatically mix and match this ad group's creatives and copy to find the best-performing combinations. Set at creation; can't be changed afterward.

Example:

false

ends_at · string

When the ad group stops delivering, as an ISO 8601 timestamp. Omit to run until paused.

Example:

"2026-01-01T12:00:00.000Z"

frequency_cap · object

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

Show child attributes

languages · string[]

Languages to target, as ISO 639 codes such as en or es. Empty or omitted targets all languages.

message_apps · enum<string>[]

Apps the conversation opens in. Required when setting conversion_location to messaging, and rejected unless the ad group's conversion location is messaging.

Available options: messenger, instagram, whatsapp

minimum_daily_spend · number

Minimum the ad group tries to spend each day.

Example:

20

optimization_goal · enum<string>

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

Example:

"reach"

placements · enum<string> object[]

automatic to let the ad platform choose placements, or the list of platforms and positions to target. Omit a platform's positions to target all of them.

Valid positions per platform:

• facebook: feed, right_hand_column, marketplace, search, profile_feed, notification, story, instream_video, facebook_reels, facebook_reels_overlay, biz_disco_feed
• instagram: stream, story, explore, explore_home, reels, profile_feed, profile_reels, ig_search
• messenger: story
• audience_network: classic, rewarded_video
• threads: threads_stream
• whatsapp: status

Available options: automatic

Example:

"automatic"

regions · Regions · object

Locations to target and exclude.

Show child attributes

starts_at · string

When the ad group starts delivering, as an ISO 8601 timestamp. Omit to start as soon as it's active.

Example:

"2026-01-01T12:00:00.000Z"

status · enum<string>

Initial status (default: active).

Available options: active, paused

Example:

"paused"

title · string

The display name of the ad group.

Example:

"North America — brand prospecting"

Response

200

application/json

ad group created

ad_campaign · object · required

The ad campaign this ad group belongs to.

Show child attributes

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.

Example:

12650

added_to_carts · number · required

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

Example:

165

audiences · object · required

Saved audiences this ad group delivers to or excludes.

Show child attributes

bid_type · enum<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, null

Example:

"average_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.

Example:

60

budget_type · enum<string> | null · required

Whether budget_amount is spent per day (daily) or over the ad group's full run (lifetime).

Available options: daily, lifetime, null

Example:

"daily"

click_through_rate · number · required

Clicks divided by impressions, between 0 and 1.

Example:

0.025

clicks · number · required

The number of clicks.

Example:

5500

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.

Example:

1650

completed_registrations · number · required

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

Example:

55

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.

Example:

2640

contacts · number · required

Whop pixel-attributed contact events, last-click.

Example:

88

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.

Example:

8

cost_per_click · number · required

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

Example:

0.24

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.

Example:

24

cost_per_contact · number | null · required

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

Example:

15

cost_per_lead · number | null · required

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

Example:

10

cost_per_mille · number · required

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

Example:

6

cost_per_purchase · number | null · required

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

Example:

30

cost_per_result · number | null · required

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

Example:

40

cost_per_schedule · number | null · required

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

Example:

22

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.

Example:

120

cost_per_unique_click · number | null · required

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

Example:

0.4

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.

Example:

1.1

created_at · string · required

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

Example:

"2026-01-01T12:00:00.000Z"

custom_conversions · number · required

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

Example:

41

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.

Example:

{
  "gift_card_purchased": 5,
  "quote_requested": 33
}

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.

Example:

{
  "gift_card_purchased": 750,
  "quote_requested": 0
}

delivery_status · enum<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

Example:

"no_ads"

demographics · object · required

Age, gender, and automatic-audience targeting.

Show child attributes

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.

Example:

40

detailed_targeting · object · required

Interest, behavior, and demographic targeting, using categories from the ad platform's targeting taxonomy. Entries across interests, behaviors, and demographics are OR'd together (anyone matching any entry is reached), matching Ads Manager's detailed-targeting box. Can't be combined with automatic audience targeting, and unavailable to campaigns with special_ad_categories.

Show child attributes

devices · object · required

Device platforms and operating systems targeted.

Show child attributes

ends_at · string | null · required

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

Example:

"2026-01-01T12:00:00.000Z"

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 on campaigns with the awareness objective; null when uncapped.

Show child attributes

id · string · required

Unique identifier for the ad group, prefixed adgrp_.

Example:

"adgrp_xxxxxxxxxxxxxx"

impressions · number · required

The number of impressions.

Example:

220000

issues · object[] · required

Show child attributes

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.

Example:

3960

leads · number · required

Whop pixel-attributed leads, last-click.

Example:

132

optimization_goal · enum<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, null

Example:

"conversions"

placements · object[] · required

Show child attributes

purchase_value · number · required

USD value of pixel-attributed purchases.

Example:

7920

purchases · number · required

Whop pixel-attributed purchases, last-click.

Example:

44

reach · number · required

The number of unique people who saw this.

Example:

0

regions · object · required

Locations targeted and excluded.

Show child attributes

result_event · enum<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, null

Example:

"custom"

result_event_name · string | null · required

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

Example:

"quote_requested"

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.

Example:

33

return_on_ad_spend · number · required

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

Example:

6

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.

Example:

5400

schedules · number · required

Whop pixel-attributed schedule events, last-click.

Example:

60

spend · number · required

The amount charged, in spend_currency.

Example:

1320

spend_currency · string | null · required

The ISO 4217 currency code of all monetary metrics.

Example:

"usd"

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.

Example:

"2026-01-01T12:00:00.000Z"

status · enum<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

Example:

"active"

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.

Example:

1320

submitted_applications · number · required

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

Example:

11

title · string | null · required

Display name of the ad group.

Example:

"Austin ceramic coating — repeat customers"

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.

Example:

3300

updated_at · string · required

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

Example:

"2026-01-01T12:00:00.000Z"

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.

Example:

8400

viewed_contents · number · required

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

Example:

1200

conversion_event · enum<string> string

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

Available options: purchase, add_to_cart, initiated_checkout, add_payment_info, complete_registration, lead, content_view, search, contact, customize_product, donate, find_location, schedule, start_trial, submit_application, subscribe

Example:

"purchase"

conversion_location · enum<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, null

Example:

"website"

dynamic_creative · boolean

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

Example:

false

message_apps · enum<string>[]

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

Available options: messenger, instagram, whatsapp

minimum_daily_spend · number | null

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

Example:

25