Skip to main content
POST
TypeScript

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-09-11-1"

Path Parameters

id
string
required

The ad ID.

Response

ad unpaused

ad_campaign
object
required

The ad campaign this ad belongs to.

ad_group
object
required

The ad group this ad belongs to.

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:

1850

added_to_carts
number
required

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

Example:

74

call_to_action
enum<string> | null
required

The call-to-action button shown on the ad.

Available options:
learn_more,
shop_now,
sign_up,
subscribe,
get_started,
book_now,
apply_now,
contact_us,
download,
order_now,
buy_now,
get_quote,
message_page,
whatsapp_message,
instagram_message,
call_now,
get_directions,
send_updates,
get_offer,
watch_more,
listen_now,
play_game,
open_link,
no_button,
get_offer_view,
get_event_tickets,
see_menu,
request_time,
event_rsvp,
see_details,
view_instagram_profile,
null
Example:

"learn_more"

click_through_rate
number
required

Clicks divided by impressions, between 0 and 1.

Example:

0.0261

clicks
number
required

The number of clicks.

Example:

1337

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:

95

completed_registrations
number
required

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

Example:

19

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:

175

contacts
number
required

Whop pixel-attributed contact events, last-click.

Example:

27

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:

6.515675675675676

cost_per_click
number
required

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

Example:

0.36

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:

25.37684210526316

cost_per_contact
number | null
required

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

Example:

17.85777777777778

cost_per_lead
number | null
required

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

Example:

3.984793388429752

cost_per_mille
number
required

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

Example:

9.42

cost_per_purchase
number | null
required

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

Example:

12.68842105263158

cost_per_result
number | null
required

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

Example:

7.653333333333333

cost_per_schedule
number | null
required

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

Example:

10.48173913043478

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:

40.18

cost_per_unique_click
number | null
required

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

Example:

0.48

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:

0.2253084112149533

created_at
string
required

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

Example:

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

creatives
object[]
required
custom_conversions
number
required

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

Example:

63

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:
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:
delivery_status
enum<string>
required

Whether the ad is delivering right now, and if not, why. When several states apply at once, the highest-precedence one is returned.

Available options:
rejected,
in_review,
draft,
campaign_paused,
ad_group_paused,
paused,
processing,
issues,
scheduled,
learning_limited,
learning,
active
Example:

"paused"

descriptions
string[]
required

The description variants shown on the ad.

existing_post_id
string | null
required

The post you pointed this ad at, when it promotes one you already published — a Facebook post, Instagram media, or TikTok video ID. null when the ad uses uploaded creatives.

Example:

"xxxxxxxxxxxxxxxx_98765"

frequency
number | null
required

Platform-reported impressions divided by reach.

headlines
string[]
required

The headline variants shown on the ad.

id
string
required

Unique identifier for the ad, prefixed ad_.

Example:

"ad_xxxxxxxxxxxxxx"

impressions
number
required

The number of impressions.

Example:

51204

issues
object[]
required
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:

1180

leads
number
required

Whop pixel-attributed leads, last-click.

Example:

121

Clicks on links in the ad that lead to your destination, as reported by the ad platform. A subset of clicks, which also counts likes, comments, and other interactions with the ad.

Example:

1071

post_id
string | null
required

The post the ad network serves for this ad, as pageID_postID on Meta — the post Meta created for an uploaded creative, or the post being promoted. Use it to open the live post, or to promote the same post from another ad. null until the network has created the post.

Example:

"xxxxxxxxxxxxxxxx_98765"

post_source
enum<string> | null
required

Identifies the network that owns existing_post_id; null when the ad uses uploaded creatives.

Available options:
facebook,
instagram,
null
Example:

"facebook"

post_thumbnail_url
string | null
required

Preview image of the post named by existing_post_id. null for ads that use uploaded creatives, or until the post's media has been fetched from the network.

Example:

"https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

primary_texts
string[]
required

The primary text variants shown in the ad body.

purchase_value
number
required

USD value of pixel-attributed purchases.

Example:

9462

purchases
number
required

Whop pixel-attributed purchases, last-click.

Example:

38

reach
number
required

The number of unique people who saw this.

Example:

0

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:

"booked_detail"

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:

63

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:

19.62419113987058

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:

640

schedules
number
required

Whop pixel-attributed schedule events, last-click.

Example:

46

social_accounts
object[]
required
spend
number
required

The amount charged, in spend_currency.

Example:

482.16

spend_currency
string | null
required

The ISO 4217 currency code of all monetary metrics.

Example:

"usd"

status
enum<string>
required

Whether the ad is enabled. active and paused are set by you; in_review and rejected come from ad review.

Available options:
active,
paused,
in_review,
rejected
Example:

"paused"

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:

300

submitted_applications
number
required

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

Example:

12

title
string | null
required

Display title of the ad.

Example:

"Ceramic coating — new 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.

Example:

1012

updated_at
string
required

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

Example:

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

url
string | null
required

The URL the ad links to, without its query string. Parameters belong in url_parameters; any you send on url are moved there.

Example:

"https://shinetime.example/ceramic-coating"

url_parameters
object
required

Every query parameter appended to the URL, keyed by parameter name — including any you sent on url itself. Whop adds its own click-attribution parameters on top; those are reserved and rejected if you set them. Which keys are reserved depends on the ad's network — Meta: utm_meta_ad_id, utm_meta_adset_id, utm_meta_campaign_id, utm_source, utm_placement, utm_medium, utm_content, utm_adset, utm_whop, wacid, wasid, waid, tw_source, tw_adid; TikTok: waid, wasid, wacid, ad_id, adset_id, campaign_id, utm_source, utm_medium, utm_placement, utm_whop, tw_source, tw_adid.

Example:
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:

0

viewed_contents
number
required

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

Example:

2140

lead_form
object | null

The instant lead form shown when someone taps this ad. null when the ad group's conversion_location is not an instant-form destination.

lead_form_id
string | null

The ad platform's ID for the instant form the ad uses. Set when the ad references an existing form via lead_form_id, or once a form built from lead_form has been created on the platform.

Example:

"1037724182084885"

messaging_config
object | null

Welcome message for click-to-message ads, shown when the conversation opens. null when the ad has none.

multi_advertiser_ads
boolean

Whether the ad can appear alongside other advertisers' ads in the same unit. Defaults to true.

Example:

true

music
object | null

The advertiser-uploaded MP3 a TikTok carousel ad plays. TikTok-only; null elsewhere and for non-carousel ads.