Ad - Whop Docs

An Ad is the individual creative unit delivered by an ad group. It holds the copy, creative assets, and destination URL for one ad. Use the Ads API to list ads for an account, create ads inside ad groups, retrieve or update creative details, delete ads that should stop running, and pause or resume delivery.

Endpoints

Endpoint	Request
List Ads	GET `/ads`
Retrieve an Ad	GET `/ads/{id}`
Create an Ad	POST `/ads`
Duplicate an Ad	POST `/ads/{id}/duplicate`
Pause an Ad	POST `/ads/{id}/pause`
Unpause an Ad	POST `/ads/{id}/unpause`
Update an Ad	PATCH `/ads/{id}`
Delete an Ad	DELETE `/ads/{id}`

Attributes

string

required

Unique identifier for the ad, prefixed ad_.

object

required

The ad campaign this ad belongs to.

Properties

string

required

The referenced entity’s id.

object

required

The ad group this ad 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.

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, donate_now, see_more, visit_site

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.

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 was created, as an ISO 8601 timestamp.

object[]

required

The creative assets used by this ad. The original asset has a null format; square, vertical, and horizontal entries are placement-specific variants. A carousel ad returns one format-null entry per attachment, in order.

Properties

string

required

The creative attachment’s file id.

object | null

required

The saved crop window for this creative, in source image pixels. Null for the original asset or a format that has not been cropped.

Properties

number

required

Height of the crop window in source pixels.

number

required

Width of the crop window in source pixels.

number

required

Left edge of the crop window in source pixels.

number

required

Top edge of the crop window in source pixels.

string | null

required

The placement variant this asset covers, or null for the original asset.Available options: square, vertical, horizontal

string | null

required

ISO 639 code of the language this image or video is shown for, such as es. On an ad with translations, the ad’s own creative carries translations.source_language. It’s null on an ad without translations.

string | null

required

The kind of asset, image or video.

string | null

required

CDN url of the asset.

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 the ad is delivering right now, and if not, why. When several states apply at once, the highest-precedence one is returned.Available options: in_appeal, rejected, in_review, draft, campaign_paused, ad_group_paused, paused, processing, issues, scheduled, learning_limited, learning, active

object[]

required

The description shown on the ad. Entries with a null language are the ad’s own copy; a Meta ad with translations also carries one entry per other language.

Properties

string | null

required

ISO 639 code of the language this text is in, such as es. On an ad with translations, the ad’s own copy carries translations.source_language. It’s null on an ad without translations.

string

required

The text shown to viewers.

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.

object[]

required

The external accounts the ad runs under — its Facebook page and Instagram profile — each referenced by ID, prefixed sacc_.

Properties

string

required

The referenced entity’s id.

number | null

required

Platform-reported impressions divided by reach.

object[]

required

The headline shown on the ad. Entries with a null language are the ad’s own copy; a Meta ad with translations also carries one entry per other language.

Properties

string | null

required

ISO 639 code of the language this text is in, such as es. On an ad with translations, the ad’s own copy carries translations.source_language. It’s null on an ad without translations.

string

required

The text shown to viewers.

number

required

The number of impressions.

object[]

required

Open issues affecting this ad. 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 | 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.

Properties

object | null

required

Screen shown after the form is submitted. null when the form uses the default.

Properties

string | null

required

Text of the follow-up button.

string | null

required

What the follow-up button does. null on forms saved before the button was configurable.Available options: website, call, download

string | null

required

Body text under the headline.

string | null

required

File the follow-up button opens. Set when button_type is download.

string | null

required

Headline of the completion screen.

string | null

required

Number the follow-up button calls. Set when button_type is call.

string | null

required

Website the follow-up button opens. Set when button_type is website.

object | null

required

Custom consent disclaimer shown before submission. null when the form has none.

Properties

string | null

required

Disclaimer text.

object[]

required

Consent checkboxes the person can tick. Empty when the disclaimer is text-only.

Properties

boolean | null

required

Whether the checkbox starts ticked.

string | null

required

Stable identifier consent responses are stored under.

boolean | null

required

Whether the checkbox must be ticked to submit the form.

string

required

Consent text next to the checkbox.

string | null

required

Disclaimer title.

string

required

more_volume is quickest to submit; higher_intent adds a confirmation step before submission.Available options: more_volume, higher_intent

object | null

required

Intro screen shown before the questions. null when the form has none.

Properties

string | null

required

Body text under the headline.

string | null

required

Headline of the intro screen.

string | null

required

Internal name of the form.

boolean

required

Whether the phone number must be verified by SMS before submitting.

object | null

required

Your privacy policy, linked from the form. null when unset.

Properties

string | null

required

Link text shown for the policy. null uses the platform default.

string

required

URL of your privacy policy.

object[]

required

Questions on the form, in order.

Properties

string

Answer format for custom questions: short_answer, multiple_choice, or appointment. Absent otherwise.

string

Question text for custom questions. Absent for standard prefill questions.

object[]

Choices for multiple_choice questions. Absent for other formats.

Properties

string | null

Stable identifier the choice’s answers are stored under. Absent for simple choices.

object

Where the form goes when this choice is selected. Absent when the form just continues to the next question.

Properties

string

required

What happens when the choice is selected.Available options: go_to_question, submit_form, close_form

number

Zero-based index of the ending screen to jump to.

number

Zero-based index of the question to jump to, for go_to_question.

string

required

Choice text shown to the person.

string

required

Question type: a standard prefill type such as email, phone, or full_name, or custom for your own question.

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.

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.

number

required

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.

object | null

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

Properties

string | null

required

Suggested reply the person can tap to start the conversation.

string | null

required

Greeting shown when the conversation opens.

boolean

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

object | null

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

Properties

string

required

The music attachment’s file id.

string | null

required

The uploaded file’s name.

string | null

required

CDN url of the MP3.

string

required

The ad platform this ad runs on.Available options: meta, tiktok, google

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.

string | null

required

Identifies the network that owns existing_post_id; null when the ad uses uploaded creatives.Available options: facebook, instagram

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.

object[]

required

The primary text shown in the ad body. Entries with a null language are the ad’s own copy (several make text variations); a Meta ad with translations also carries one entry per other language.

Properties

string | null

required

ISO 639 code of the language this text is in, such as es. On an ad with translations, the ad’s own copy carries translations.source_language. It’s null on an ad without translations.

string

required

The text shown to viewers.

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.

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

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

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 title of the ad.

object | null

The languages a Meta ad runs in besides its own. Each viewer sees the version for their language, or the ad’s own copy. null when the ad runs in one language.

Properties

string[]

required

ISO 639 codes Meta translates the ad’s own copy into automatically, such as fr.

string

required

ISO 639 code of the language the ad’s own copy is written in, such as en. Viewers whose language has no version of its own see the ad’s own copy.

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 was last updated, as an ISO 8601 timestamp.

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.

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.

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.

{
	"id": "ad_xxxxxxxxxxxxx",
	"ad_campaign": {
		"id": "adcamp_xxxxxxxxxx"
	},
	"ad_group": {
		"id": "adgrp_xxxxxxxxxxx"
	},
	"added_to_cart_value": 540,
	"added_to_carts": 18,
	"call_to_action": "shop_now",
	"click_through_rate": 0.034,
	"clicks": 420,
	"completed_registration_value": 0,
	"completed_registrations": 12,
	"contact_value": 0,
	"contacts": 8,
	"cost_per_added_to_cart": 7.22,
	"cost_per_click": 0.31,
	"cost_per_completed_registration": 10.83,
	"cost_per_contact": 16.25,
	"cost_per_lead": 9.29,
	"cost_per_mille": 14.5,
	"cost_per_purchase": 21.67,
	"cost_per_result": 21.67,
	"cost_per_schedule": null,
	"cost_per_submitted_application": null,
	"cost_per_unique_click": 0.37,
	"cost_per_viewed_content": 0.54,
	"created_at": "2026-06-01T12:00:00Z",
	"creatives": [
		{
			"id": "file_xxxxxxxxxxxx",
			"crop": {
				"height": 1080,
				"width": 1080,
				"x": 120,
				"y": 0
			},
			"format": "square",
			"media_type": "image",
			"url": "https://img.whop.com/file_xxxxxxxxxxxx.jpg",
			"language": null
		}
	],
	"custom_conversions": 4,
	"custom_event_counts": {
		"QualifiedCall": 3,
		"BookedDemo": 1
	},
	"custom_event_values": {
		"QualifiedCall": 1500,
		"BookedDemo": 0
	},
	"delivery_status": "issues",
	"descriptions": [
		{
			"language": null,
			"text": "Limited spots available this week."
		}
	],
	"frequency": 1.8,
	"headlines": [
		{
			"language": null,
			"text": "Join Pickaxe Pro"
		}
	],
	"impressions": 9000,
	"issues": [
		{
			"id": "adiss_xxxxxxxxxxx",
			"category": "error",
			"title": "Ad issue",
			"message": "The ad's creative violates the ad network's policies. Edit the creative and resubmit for review.",
			"resource_id": "ad_xxxxxxxxxxxxx",
			"resource_type": "ad"
		}
	],
	"lead_form": null,
	"lead_form_id": null,
	"lead_value": 700,
	"leads": 14,
	"link_clicks": 336,
	"messaging_config": null,
	"multi_advertiser_ads": true,
	"music": null,
	"post_id": "102938475601928_5647382910",
	"existing_post_id": null,
	"post_source": null,
	"post_thumbnail_url": null,
	"primary_texts": [
		{
			"language": null,
			"text": "Build sharper trading habits with daily lessons."
		}
	],
	"purchase_value": 1820,
	"purchases": 6,
	"reach": 5000,
	"result_event": "purchase",
	"result_event_name": null,
	"results": 6,
	"return_on_ad_spend": 14,
	"schedule_value": 0,
	"schedules": 0,
	"external_accounts": [
		{
			"id": "sacc_xxxxxxxxxxxx"
		}
	],
	"spend": 130,
	"spend_currency": "usd",
	"status": "active",
	"submitted_application_value": 0,
	"submitted_applications": 0,
	"title": "Pickaxe Pro launch ad",
	"unique_click_through_rate": 0.028,
	"unique_clicks": 350,
	"updated_at": "2026-06-02T12:00:00Z",
	"url": "https://whop.com/pickaxe",
	"url_parameters": {
		"utm_campaign": "pickaxe-launch"
	},
	"viewed_content_value": 0,
	"viewed_contents": 240,
	"platform": "meta"
}

​Endpoints

​Attributes

Endpoints

Attributes