Sign in

a84d4905fdbb

latestOpenAPI 3.1.02026-08-143874115.7 MB
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.

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_idstring

Promote an existing post instead of uploading creatives — a Facebook post or Instagram media id. Mutually exclusive with creatives. Pair with post_source.

post_source'facebook' | 'instagram'

Identifies the network that owns 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.

url_parametersobject

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

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"
  ],
  "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_id": "1784512345678901",
  "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' | '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
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.

multi_advertiser_adsboolean

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

post_idstring nullable required

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

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

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

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

url_parametersobject required

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

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://assets-2-rough.whop.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"
  ],
  "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,
  "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://assets-2-rough.whop.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
}