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`
Create Ad	POST `/ads`
Retrieve Ad	GET `/ads/{id}`
Update Ad	PATCH `/ads/{id}`
Delete Ad	DELETE `/ads/{id}`
Pause Ad	POST `/ads/{id}/pause`
Unpause Ad	POST `/ads/{id}/unpause`

Attributes

string

required

Unique identifier for the ad, prefixed ad_.

ad_campaign

object

required

The ad campaign this ad belongs to.

Properties

string

required

The referenced entity’s id.

ad_group

object

required

The ad group this ad belongs to.

Properties

string

required

The referenced entity’s id.

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.

added_to_carts

number

required

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

call_to_action

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

click_through_rate

number

required

Clicks divided by impressions, between 0 and 1.

clicks

number

required

The number of clicks.

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.

completed_registrations

number

required

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

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.

contacts

number

required

Whop pixel-attributed contact events, last-click.

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.

cost_per_click

number

required

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

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.

cost_per_contact

number | null

required

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

cost_per_lead

number | null

required

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

cost_per_mille

number

required

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

cost_per_purchase

number | null

required

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

cost_per_result

number | null

required

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

cost_per_schedule

number | null

required

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

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.

cost_per_unique_click

number | null

required

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

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.

created_at

string

required

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

creatives

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.

crop

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

height

number

required

Height of the crop window in source pixels.

width

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.

format

string | null

required

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

media_type

string | null

required

The kind of asset, image or video.

url

string | null

required

CDN url of the asset.

custom_conversions

number

required

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

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.

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.

delivery_status

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, learning_limited, learning, active

descriptions

string[]

required

The description variants shown on the ad.

frequency

number | null

required

Platform-reported impressions divided by reach.

headlines

string[]

required

The headline variants shown on the ad.

impressions

number

required

The number of impressions.

issues

object[]

required

Open issues affecting this ad. Empty when there are none.

Properties

string

required

Unique identifier for the issue.

message

string

required

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

resource_id

string | null

required

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

resource_type

string

required

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

lead_form

object | null

required

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

completion

object | null

required

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

Properties

button_text

string | null

required

Text of the follow-up button.

description

string | null

required

Body text under the headline.

headline

string | null

required

Headline of the completion screen.

url

string | null

required

Website the follow-up button opens. null when the screen has no button.

disclaimer

object | null

required

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

Properties

body

string | null

required

Disclaimer text.

checkboxes

object[]

required

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

Properties

checked_by_default

boolean | null

required

Whether the checkbox starts ticked.

key

string | null

required

Stable identifier consent responses are stored under.

required

boolean | null

required

Whether the checkbox must be ticked to submit the form.

text

string

required

Consent text next to the checkbox.

title

string | null

required

Disclaimer title.

form_type

string

required

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

intro

object | null

required

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

Properties

description

string | null

required

Body text under the headline.

headline

string | null

required

Headline of the intro screen.

name

string | null

required

Internal name of the form.

phone_verification

boolean

required

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

privacy_policy

object | null

required

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

Properties

link_text

string | null

required

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

url

string

required

URL of your privacy policy.

questions

object[]

required

Questions on the form, in order.

Properties

format

string

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

label

string

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

options

object[]

Choices for multiple_choice questions. Absent for other formats.

Properties

key

string | null

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

logic

object

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

Properties

action

string

required

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

target_end_page_index

number

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

target_question_index

number

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

value

string

required

Choice text shown to the person.

type

string

required

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

lead_form_id

string | null

required

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.

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.

leads

number

required

Whop pixel-attributed leads, last-click.

messaging_config

object | null

required

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

Properties

keyword

string | null

required

Suggested reply the person can tap to start the conversation.

message

string | null

required

Greeting shown when the conversation opens.

multi_advertiser_ads

boolean

required

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

post_id

string | null

required

The existing post this ad promotes — a Facebook post or Instagram media ID. null when the ad uses uploaded creatives.

post_source

string | null

required

Which network post_id refers to: facebook (a page post) or instagram (a media ID). null when the ad uses uploaded creatives.Available options: facebook, instagram

post_thumbnail_url

string | null

required

Preview image of the existing post this ad promotes. null for ads that use uploaded creatives, or until the post’s media has been fetched from the network.

primary_texts

string[]

required

The primary text variants shown in the ad body.

purchase_value

number

required

USD value of pixel-attributed purchases.

purchases

number

required

Whop pixel-attributed purchases, last-click.

reach

number

required

The number of unique people who saw this.

result_event

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

result_event_name

string | null

required

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

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.

return_on_ad_spend

number

required

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

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.

schedules

number

required

Whop pixel-attributed schedule events, last-click.

The social 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.

spend

number

required

The amount charged, in spend_currency.

spend_currency

string | null

required

The ISO 4217 currency code of all monetary metrics.

status

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

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.

submitted_applications

number

required

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

title

string | null

required

Display title of the ad.

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.

updated_at

string

required

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

url

string | null

required

The URL the ad links to.

url_parameters

object

required

Query parameters appended to the URL, keyed by parameter name.

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.

viewed_contents

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"
		}
	],
	"custom_conversions": 4,
	"custom_event_counts": {
		"QualifiedCall": 3,
		"BookedDemo": 1
	},
	"custom_event_values": {
		"QualifiedCall": 1500,
		"BookedDemo": 0
	},
	"delivery_status": "issues",
	"descriptions": ["Limited spots available this week."],
	"frequency": 1.8,
	"headlines": ["Join Pickaxe Pro"],
	"impressions": 9000,
	"issues": [
		{
			"id": "adiss_xxxxxxxxxxx",
			"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,
	"messaging_config": null,
	"multi_advertiser_ads": true,
	"post_id": null,
	"post_source": null,
	"post_thumbnail_url": null,
	"primary_texts": ["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,
	"social_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
}

Introduction

Reference

Core Resources

Money

Commerce

Partners

Workforce

Tracking

Ads

Media

Identity

Developer

Ad

Endpoints

Attributes

​Endpoints

​Attributes

Endpoints

Attributes