Sign in
Ads

Create an Ad

Creates an ad in an ad group.

post/ads

Headers

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

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

Request body

ad_groupobject

An inline ad group to create (same shape as POST /ad_groups, including ad_campaign_id). Creates the ad group and the ad together. Provide this OR ad_group_id.

ad_group_idstring

The existing ad group to create the ad in. Provide this OR ad_group, not both.

call_to_action'apply_now' | 'book_now' | 'call_now' | 'contact_us' | 'download' | 'get_directions' | 'get_offer' | 'get_quote' | 'learn_more' | 'listen_now' | 'message_page' | 'no_button' | 'open_link' | 'order_now' | 'request_time' | 'see_details' | 'see_menu' | 'send_updates' | 'shop_now' | 'sign_up' | 'subscribe' | 'watch_more'

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

descriptionsstring[]

The description variants shown on the ad.

existing_post_idstring

Promote a post you already published instead of uploading creatives — a Facebook post or Instagram media id. Mutually exclusive with creatives. Pair with post_source.

headlinesstring[]

The headline variants shown on the ad.

lead_form_idstring

Use an existing instant form instead of creating one — the form's platform ID, from a form already on the ad's Facebook page. Only allowed when the ad group's conversion_location is an instant-form destination. Mutually exclusive with lead_form.

multi_advertiser_adsboolean

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

post_source'facebook' | 'instagram'

Identifies the network that owns existing_post_id. The source is inferred from the ID shape when omitted.

primary_textsstring[]

The primary text variants shown in the ad body.

titlestring

The display name of the ad.

urlstring

The URL the ad links to. Query parameters are merged into url_parameters, so the stored URL is always bare.

url_parametersobject

Query parameters to append to the destination URL, keyed by parameter name. Merged with any query string on url. Whop adds its own click-attribution parameters; 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 request

{
  "ad_group": {
    "ad_campaign_id": "adcamp_xxxxxxxxxxxxxx",
    "budget_amount": 60,
    "optimization_goal": "conversions",
    "title": "Austin — ceramic coating buyers"
  },
  "ad_group_id": "adgrp_xxxxxxxxxxxxxx",
  "call_to_action": "message_page",
  "creatives": [
    {
      "crop": {
        "height": 1000,
        "width": 1000,
        "x": 40
      },
      "format": "square",
      "id": "file_xxxxxxxxxxxxxx"
    }
  ],
  "descriptions": [
    "Two-stage paint correction included"
  ],
  "existing_post_id": "1784512345678901",
  "headlines": [
    "Showroom shine, guaranteed"
  ],
  "lead_form": {
    "completion": {
      "button_text": "See our work",
      "description": "We book coatings two days out, so pick a slot when we ring.",
      "headline": "Thanks — we will call you today",
      "url": "https://shinetime.example/gallery"
    },
    "disclaimer": {
      "body": "Ceramic coating requires the vehicle for two days.",
      "checkboxes": [
        {
          "key": "two_days",
          "required": true,
          "text": "I can leave my vehicle for two days"
        }
      ],
      "title": "Before you submit"
    },
    "form_type": "higher_intent",
    "intro": {
      "description": "Tell us about your vehicle and we will send a fixed price.",
      "headline": "Get a ceramic coating quote"
    },
    "name": "Ceramic coating quote requests",
    "phone_verification": true,
    "privacy_policy": {
      "link_text": "Shine Time privacy policy",
      "url": "https://shinetime.example/privacy"
    },
    "questions": [
      {
        "format": "multiple_choice",
        "label": "What vehicle are we detailing?",
        "options": [
          {
            "key": "sedan",
            "logic": {
              "action": "go_to_question",
              "target_question_index": 3
            },
            "value": "Sedan or coupe"
          }
        ],
        "type": "phone"
      }
    ]
  },
  "lead_form_id": "1037724182084885",
  "messaging_config": {
    "keyword": "Book an interior deep clean",
    "message": "Hi! Tell us your vehicle and ZIP and we will send an interior deep clean quote."
  },
  "post_source": "instagram",
  "primary_texts": [
    "Three-year ceramic coating, booked online in under a minute."
  ],
  "social_accounts": [
    {
      "id": "sacc_xxxxxxxxxxxxxx"
    }
  ],
  "title": "Interior deep clean — DM us",
  "url": "https://shinetime.example/ceramic-coating",
  "url_parameters": {
    "ref": "spring"
  }
}

Response

ad created from an existing post

added_to_cart_valuenumber 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_cartsnumber required

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

call_to_action'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' nullable required

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

click_through_ratenumber required

Clicks divided by impressions, between 0 and 1.

clicksnumber required

The number of clicks.

completed_registration_valuenumber 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_registrationsnumber required

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

contact_valuenumber required

USD value attributed to contact events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.

contactsnumber required

Whop pixel-attributed contact events, last-click.

cost_per_added_to_cartnumber nullable required

Spend divided by attributed add-to-cart events; null when they are not the goal and none are attributed.

cost_per_clicknumber required

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

cost_per_completed_registrationnumber nullable required

Spend divided by attributed complete-registration events; null when they are not the goal and none are attributed.

cost_per_contactnumber nullable required

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

cost_per_leadnumber nullable required

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

cost_per_millenumber required

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

cost_per_purchasenumber nullable required

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

cost_per_resultnumber nullable required

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

cost_per_schedulenumber nullable required

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

cost_per_submitted_applicationnumber nullable required

Spend divided by attributed submit-application events; null when they are not the goal and none are attributed.

cost_per_unique_clicknumber nullable required

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

cost_per_viewed_contentnumber nullable required

Spend divided by attributed view-content events; null when they are not the goal and none are attributed.

created_atstring required

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

custom_conversionsnumber required

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

custom_event_countsobject 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_valuesobject 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'rejected' | 'in_review' | 'draft' | 'campaign_paused' | 'ad_group_paused' | 'paused' | 'processing' | 'issues' | 'scheduled' | 'learning_limited' | 'learning' | 'active' required

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

descriptionsstring[] required
existing_post_idstring nullable 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.

frequencynumber nullable required

Platform-reported impressions divided by reach.

headlinesstring[] required
idstring required

Unique identifier for the ad, prefixed ad_.

impressionsnumber required

The number of impressions.

lead_form_idstring nullable

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_valuenumber required

USD value attributed to lead events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.

leadsnumber required

Whop pixel-attributed leads, last-click.

link_clicksnumber 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.

multi_advertiser_adsboolean

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

post_idstring nullable 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.

post_source'facebook' | 'instagram' | 'null' nullable required

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

post_thumbnail_urlstring nullable 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.

primary_textsstring[] required
purchase_valuenumber required

USD value of pixel-attributed purchases.

purchasesnumber required

Whop pixel-attributed purchases, last-click.

reachnumber required

The number of unique people who saw this.

result_event'purchase' | 'lead' | 'schedule' | 'submit_application' | 'contact' | 'complete_registration' | 'view_content' | 'add_to_cart' | 'custom' | 'messaging_conversation' | 'null' nullable 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.

result_event_namestring nullable required

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

resultsnumber nullable 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_spendnumber required

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

schedule_valuenumber required

USD value attributed to schedule events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.

schedulesnumber required

Whop pixel-attributed schedule events, last-click.

spendnumber required

The amount charged, in spend_currency.

spend_currencystring nullable required

The ISO 4217 currency code of all monetary metrics.

status'active' | 'paused' | 'in_review' | 'rejected' required

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

submitted_application_valuenumber 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_applicationsnumber required

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

titlestring nullable required

Display title of the ad.

unique_click_through_ratenumber nullable required

Unique clicks divided by impressions, between 0 and 1.

unique_clicksnumber required

People who clicked, reported by the Whop pixel, counted once per person.

updated_atstring required

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

urlstring nullable required

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

url_parametersobject 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.

viewed_content_valuenumber 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_contentsnumber required

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

Example response

{
  "ad_campaign": {
    "id": "adcamp_xxxxxxxxxxxxxx"
  },
  "ad_group": {
    "id": "adcamp_xxxxxxxxxxxxxx"
  },
  "added_to_cart_value": 1850,
  "added_to_carts": 74,
  "call_to_action": "learn_more",
  "click_through_rate": 0.0261,
  "clicks": 1337,
  "completed_registration_value": 95,
  "completed_registrations": 19,
  "contact_value": 175,
  "contacts": 27,
  "cost_per_added_to_cart": 6.515675675675676,
  "cost_per_click": 0.36,
  "cost_per_completed_registration": 25.37684210526316,
  "cost_per_contact": 17.85777777777778,
  "cost_per_lead": 3.984793388429752,
  "cost_per_mille": 9.42,
  "cost_per_purchase": 12.68842105263158,
  "cost_per_result": 7.653333333333333,
  "cost_per_schedule": 10.48173913043478,
  "cost_per_submitted_application": 40.18,
  "cost_per_unique_click": 0.48,
  "cost_per_viewed_content": 0.2253084112149533,
  "created_at": "2026-01-01T12:00:00.000Z",
  "creatives": [
    {
      "crop": {
        "height": 1000,
        "width": 1000,
        "x": 40
      },
      "format": "vertical",
      "id": "file_xxxxxxxxxxxxxx",
      "media_type": "image",
      "url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  ],
  "custom_conversions": 63,
  "custom_event_counts": {
    "booked_detail": 63
  },
  "custom_event_values": {
    "booked_detail": 4820
  },
  "delivery_status": "paused",
  "descriptions": [
    "Paint correction included"
  ],
  "existing_post_id": "xxxxxxxxxxxxxxxx_98765",
  "headlines": [
    "Austin's mobile detailers"
  ],
  "id": "ad_xxxxxxxxxxxxxx",
  "impressions": 51204,
  "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"
    }
  ],
  "lead_form": {
    "completion": {
      "button_text": "See our work",
      "description": "We book coatings two days out, so pick a slot when we ring.",
      "headline": "Thanks — we will call you today",
      "url": "https://shinetime.example/gallery"
    },
    "disclaimer": {
      "body": "Ceramic coating requires the vehicle for two days.",
      "checkboxes": [
        {
          "key": "consent_1",
          "required": true,
          "text": "I agree"
        }
      ],
      "title": "Before you submit"
    },
    "form_type": "higher_intent",
    "intro": {
      "description": "Tell us about your vehicle and we will send a fixed price.",
      "headline": "Get a ceramic coating quote"
    },
    "name": "Ceramic coating quote requests",
    "phone_verification": true,
    "privacy_policy": {
      "link_text": "Shine Time privacy policy",
      "url": "https://shinetime.example/privacy"
    },
    "questions": [
      {
        "format": "multiple_choice",
        "label": "What vehicle are we detailing?",
        "options": [
          {
            "key": "ceramic_coating",
            "logic": {
              "action": "go_to_question",
              "target_question_index": 3
            },
            "value": "Ceramic coating"
          }
        ],
        "type": "custom"
      }
    ]
  },
  "lead_form_id": "1037724182084885",
  "lead_value": 1180,
  "leads": 121,
  "link_clicks": 1071,
  "messaging_config": {
    "keyword": "Book an interior deep clean",
    "message": "Hi! Tell us your vehicle and ZIP and we will send an interior deep clean quote."
  },
  "multi_advertiser_ads": true,
  "post_id": "xxxxxxxxxxxxxxxx_98765",
  "post_source": "facebook",
  "post_thumbnail_url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "primary_texts": [
    "Book a two-day ceramic coating and keep the shine for three years."
  ],
  "purchase_value": 9462,
  "purchases": 38,
  "result_event": "custom",
  "result_event_name": "booked_detail",
  "results": 63,
  "return_on_ad_spend": 19.62419113987058,
  "schedule_value": 640,
  "schedules": 46,
  "social_accounts": [
    {
      "id": "adcamp_xxxxxxxxxxxxxx"
    }
  ],
  "spend": 482.16,
  "spend_currency": "usd",
  "status": "paused",
  "submitted_application_value": 300,
  "submitted_applications": 12,
  "title": "Ceramic coating — new ad group",
  "unique_clicks": 1012,
  "updated_at": "2026-01-01T12:00:00.000Z",
  "url": "https://shinetime.example/ceramic-coating",
  "url_parameters": {},
  "viewed_contents": 2140
}

Changes

Changed in 8 of the 42 revisions of this API.8319

  • 16c82685be351See the full diff
    • ○

      added the required property link_clicks to the response with the 200 status

      response-required-property-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 621705ee8f4a12See the full diff
    • ●

      removed the request property post_id

      request-property-removed

    • ○

      added the new optional request property existing_post_id

      new-optional-request-property

    • ○

      added the required property existing_post_id to the response with the 200 status

      response-required-property-added

    This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 4a1a4a5d2c721See the full diff
    • ●

      added the new scheduled enum value to the delivery_status response property for the response status 200

      response-property-enum-value-added

  • c301132dbfd71See the full diff
    • ●

      added the new messaging_conversation enum value to the result_event response property for the response status 200

      response-property-enum-value-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • ae20b30817de1See the full diff
    • ○

      added the non-success response with the status 409

      response-non-success-status-added

  • f1020c3ecda42See the full diff
    • ○

      added the optional property error/code to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property error/code to the response with the 404 status

      response-optional-property-added

    This revision also has 9 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 60bbb4a6ffbc811See the full diff
    • ▲

      the response property lead_form became optional for the status 200

      response-property-became-optional

    • ▲

      the response property lead_form_id became optional for the status 200

      response-property-became-optional

    • ▲

      the response property messaging_config became optional for the status 200

      response-property-became-optional

    • ▲

      the response property multi_advertiser_ads became optional for the status 200

      response-property-became-optional

    • ▲

      added AdLeadForm subschema #2 to the lead_form response property oneOf list for the response status 200

      response-property-one-of-added

    • ▲

      added AdMessagingConfig subschema #2 to the messaging_config response property oneOf list for the response status 200

      response-property-one-of-added

    • ▲

      the lead_form response's property type/format changed from object null/ to / for status 200

      response-property-type-changed

    • ▲

      the messaging_config response's property type/format changed from object null/ to / for status 200

      response-property-type-changed

    • ○

      added the new optional header request parameter Idempotency-Key

      new-optional-request-parameter

    • ○

      added the required property added_to_cart_value to the response with the 200 status

      response-required-property-added

    • ○

      added the required property completed_registration_value to the response with the 200 status

      response-required-property-added

    • ○

      added the required property contact_value to the response with the 200 status

      response-required-property-added

    • ○

      added the required property cost_per_unique_click to the response with the 200 status

      response-required-property-added

    • ○

      added the required property custom_event_values to the response with the 200 status

      response-required-property-added

    • ○

      added the required property lead_value to the response with the 200 status

      response-required-property-added

    • ○

      added the required property schedule_value to the response with the 200 status

      response-required-property-added

    • ○

      added the required property social_accounts/items/id to the response with the 200 status

      response-required-property-added

    • ○

      added the required property submitted_application_value to the response with the 200 status

      response-required-property-added

    • ○

      added the required property viewed_content_value to the response with the 200 status

      response-required-property-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 3a06a605784b2See the full diff
    • ○

      added the required property custom_event_counts to the response with the 200 status

      response-required-property-added

    • ○

      added the required property results to the response with the 200 status

      response-required-property-added