> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ad

An Ad is the individual creative unit delivered by an [ad group](/api-reference/beta/ad-groups/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](/api-reference/beta/ads/list-ads)          | <Badge color="blue" size="sm" stroke>GET</Badge> `/ads`                |
| [Create Ad](/api-reference/beta/ads/create-an-ad)     | <Badge color="green" size="sm" stroke>POST</Badge> `/ads`              |
| [Retrieve Ad](/api-reference/beta/ads/retrieve-an-ad) | <Badge color="blue" size="sm" stroke>GET</Badge> `/ads/{id}`           |
| [Update Ad](/api-reference/beta/ads/update-an-ad)     | <Badge color="orange" size="sm" stroke>PATCH</Badge> `/ads/{id}`       |
| [Delete Ad](/api-reference/beta/ads/delete-an-ad)     | <Badge color="red" size="sm" stroke>DELETE</Badge> `/ads/{id}`         |
| [Pause Ad](/api-reference/beta/ads/pause-an-ad)       | <Badge color="green" size="sm" stroke>POST</Badge> `/ads/{id}/pause`   |
| [Unpause Ad](/api-reference/beta/ads/unpause-an-ad)   | <Badge color="green" size="sm" stroke>POST</Badge> `/ads/{id}/unpause` |

## Attributes

<Columns cols={2}>
  <Column>
    <ResponseField name="ad_campaign" type="object" required>
      The ad campaign this ad belongs to, an object with an id.

      <Accordion title="Properties" defaultOpen={true}>
        <ResponseField name="id" type="string" required>
          The referenced entity's id.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="ad_group" type="object" required>
      The ad group this ad belongs to, an object with an id.

      <Accordion title="Properties" defaultOpen={true}>
        <ResponseField name="id" type="string" required>
          The referenced entity's id.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="added_to_carts" type="number" required>
      Whop pixel-attributed add-to-cart events, last-click.
    </ResponseField>

    <ResponseField name="call_to_action" type="string,null | 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`
    </ResponseField>

    <ResponseField name="click_through_rate" type="number" required>
      Clicks divided by impressions, between 0 and 1.
    </ResponseField>

    <ResponseField name="clicks" type="number" required>
      The number of clicks.
    </ResponseField>

    <ResponseField name="completed_registrations" type="number" required>
      Whop pixel-attributed complete-registration events, last-click.
    </ResponseField>

    <ResponseField name="contacts" type="number" required>
      Whop pixel-attributed contact events, last-click.
    </ResponseField>

    <ResponseField name="cost_per_added_to_cart" type="number | null" required>
      Spend divided by attributed add-to-cart events; null when they are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_click" type="number" required>
      Spend divided by clicks; 0 when there are no clicks.
    </ResponseField>

    <ResponseField name="cost_per_completed_registration" type="number | null" required>
      Spend divided by attributed complete-registration events; null when they are
      not the goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_contact" type="number | null" required>
      Spend divided by attributed contact events; null when contacts are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_lead" type="number | null" required>
      Spend divided by attributed leads; null when leads are not a goal and none are
      attributed.
    </ResponseField>

    <ResponseField name="cost_per_mille" type="number" required>
      Spend per 1,000 impressions; 0 when there are no impressions.
    </ResponseField>

    <ResponseField name="cost_per_purchase" type="number | null" required>
      Spend divided by attributed purchases; null when purchases are not a goal and
      none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_result" type="number | null" required>
      Spend divided by Whop pixel-attributed results; null when nothing
      Whop-attributable is being optimized for.
    </ResponseField>

    <ResponseField name="cost_per_schedule" type="number | null" required>
      Spend divided by attributed schedule events; null when schedules are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_submitted_application" type="number | null" required>
      Spend divided by attributed submit-application events; null when they are not
      the goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_viewed_content" type="number | null" required>
      Spend divided by attributed view-content events; null when they are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      When the ad was created, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="creatives" type="object[]" required>
      The creatives used by this ad. The original/uncropped asset has a null format; square, vertical, and horizontal entries are its per-placement crops.

      <Accordion title="Properties" defaultOpen={true}>
        <ResponseField name="format" type="string,null | null" required>
          The placement crop this asset covers, or null for the original/uncropped asset.

          Available options: `square`, `vertical`, `horizontal`
        </ResponseField>

        <ResponseField name="id" type="string" required>
          The creative attachment's file id.
        </ResponseField>

        <ResponseField name="media_type" type="string | null" required>
          The kind of asset, image or video.
        </ResponseField>

        <ResponseField name="url" type="string | null" required>
          CDN url of the asset.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="custom_conversions" type="number" required>
      Whop pixel-attributed custom (merchant-defined) conversion events, last-click,
      across all custom event names.
    </ResponseField>

    <ResponseField name="descriptions" type="string[]" required>
      The description variants shown on the ad.
    </ResponseField>

    <ResponseField name="frequency" type="number | null" required>
      Platform-reported impressions divided by reach.
    </ResponseField>

    <ResponseField name="headlines" type="string[]" required>
      The headline variants shown on the ad.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Unique identifier for the ad.
    </ResponseField>

    <ResponseField name="impressions" type="number" required>
      The number of impressions.
    </ResponseField>

    <ResponseField name="issues" type="object[]" required>
      Open issues affecting this ad. Empty when there are none.

      <Accordion title="Properties" defaultOpen={true}>
        <ResponseField name="id" type="string" required>
          Unique identifier for the issue.
        </ResponseField>

        <ResponseField name="message" type="string" required>
          A description of what the issue is and how it can be resolved.
        </ResponseField>

        <ResponseField name="resource_id" type="string | null" required>
          The ID of the campaign, ad group, or ad the issue is attached to.
        </ResponseField>

        <ResponseField name="resource_type" type="string" required>
          The type of resource the issue is attached to.

          Available options: `ad_campaign`, `ad_group`, `ad`
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="lead_form" type="object | null" required>
      The instant lead form on the ad (Meta lead ads), or null when the ad group's
      conversion\_location is not an instant-form destination. An object with name,
      form\_type (more\_volume or higher\_intent), an optional intro, questions, a
      privacy\_policy, an optional completion screen, and phone\_verification.
    </ResponseField>

    <ResponseField name="leads" type="number" required>
      Whop pixel-attributed leads, last-click.
    </ResponseField>

    <ResponseField name="messaging_config" type="object | null" required>
      The click-to-message welcome copy, an object with message and keyword, or null
      when the ad has none.
    </ResponseField>

    <ResponseField name="multi_advertiser_ads" type="boolean" required>
      Whether the ad can appear alongside other advertisers' ads in the same unit.
      Defaults to true.
    </ResponseField>

    <ResponseField name="post_id" type="string | null" required>
      The existing post this ad promotes (a Facebook post or Instagram media), or
      null when it uses uploaded creatives.
    </ResponseField>

    <ResponseField name="primary_texts" type="string[]" required>
      The primary text variants shown in the ad body.
    </ResponseField>

    <ResponseField name="purchase_value" type="number" required>
      USD value of pixel-attributed purchases.
    </ResponseField>

    <ResponseField name="purchases" type="number" required>
      Whop pixel-attributed purchases, last-click.
    </ResponseField>

    <ResponseField name="reach" type="number" required>
      The number of unique people who saw this.
    </ResponseField>

    <ResponseField name="result_event" type="string,null | 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`
    </ResponseField>

    <ResponseField name="result_event_name" type="string | null" required>
      The merchant-defined event name when result\_event is custom; null for the
      standard events.
    </ResponseField>

    <ResponseField name="return_on_ad_spend" type="number" required>
      Purchase value divided by spend; 0 when there is no spend.
    </ResponseField>

    <ResponseField name="schedules" type="number" required>
      Whop pixel-attributed schedule events, last-click.
    </ResponseField>

    <ResponseField name="social_accounts" type="object[]" required>
      The social accounts (Facebook page, Instagram profile) the ad runs under, each
      an object with an id.
    </ResponseField>

    <ResponseField name="spend" type="number" required>
      The amount charged, in spend\_currency.
    </ResponseField>

    <ResponseField name="spend_currency" type="string | null" required>
      The ISO 4217 currency code of all monetary metrics.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      The delivery status of the ad.

      Available options: `active`, `paused`, `in_review`, `rejected`
    </ResponseField>

    <ResponseField name="submitted_applications" type="number" required>
      Whop pixel-attributed submit-application events, last-click.
    </ResponseField>

    <ResponseField name="title" type="string | null" required>
      The display title of the ad. Falls back to the creative set caption when
      unset.
    </ResponseField>

    <ResponseField name="unique_click_through_rate" type="number | null" required>
      Unique clicks divided by impressions, between 0 and 1.
    </ResponseField>

    <ResponseField name="unique_clicks" type="number" required>
      The number of unique clicks.
    </ResponseField>

    <ResponseField name="updated_at" type="string" required>
      When the ad was last updated, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="url" type="string | null" required>
      The URL the ad links to.
    </ResponseField>

    <ResponseField name="url_parameters" type="object" required>
      Query parameters appended to the URL, as a string-to-string map.
    </ResponseField>

    <ResponseField name="viewed_contents" type="number" required>
      Whop pixel-attributed view-content events, last-click.
    </ResponseField>
  </Column>

  <Column>
    <div className="api-resource-sticky-example">
      ```json Ad theme={null}
      {
      	"ad_campaign": {
      		"id": "adcamp_xxxxxxxxxx"
      	},
      	"ad_group": {
      		"id": "adgrp_xxxxxxxxxxx"
      	},
      	"added_to_carts": 18,
      	"call_to_action": "shop_now",
      	"click_through_rate": 0.034,
      	"clicks": 420,
      	"completed_registrations": 12,
      	"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_viewed_content": 0.54,
      	"created_at": "2026-06-01T12:00:00Z",
      	"creatives": [
      		{
      			"format": "square",
      			"id": "file_xxxxxxxxxxxx",
      			"media_type": "image",
      			"url": "https://img.whop.com/file_xxxxxxxxxxxx.jpg"
      		}
      	],
      	"custom_conversions": 4,
      	"descriptions": ["Limited spots available this week."],
      	"frequency": 1.8,
      	"headlines": ["Join Pickaxe Pro"],
      	"id": "ad_xxxxxxxxxxxxx",
      	"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,
      	"leads": 14,
      	"messaging_config": null,
      	"multi_advertiser_ads": true,
      	"post_id": null,
      	"primary_texts": ["Build sharper trading habits with daily lessons."],
      	"purchase_value": 1820,
      	"purchases": 6,
      	"reach": 5000,
      	"result_event": "purchase",
      	"result_event_name": null,
      	"return_on_ad_spend": 14,
      	"schedules": 0,
      	"social_accounts": [
      		{
      			"id": "sacc_xxxxxxxxxxxx"
      		}
      	],
      	"spend": 130,
      	"spend_currency": "usd",
      	"status": "active",
      	"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_contents": 240
      }
      ```
    </div>
  </Column>
</Columns>