Sign in
Ads

Update an Ad

Updates an ad's editable fields.

patch/ads/{id}

Request body

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 Meta instant form instead of creating one — the form's Meta 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. Replaces a stored 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'

Which network post_id refers to — facebook (a page post) or instagram (a media id). Authoritative; when omitted the source is inferred from the id shape.

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, as a string-to-string map.

Response

ad updated

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

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

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_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 broken out by merchant-defined event name, last-click, as a { event_name => count } map over the stats window. 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.

delivery_status'rejected' | 'in_review' | 'draft' | 'campaign_paused' | 'ad_group_paused' | 'paused' | 'processing' | 'issues' | 'learning_limited' | 'learning' | 'active' required

The current delivery state, mirroring the Delivery column in the ads dashboard. 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.

impressionsnumber required

The number of impressions.

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

lead_form_idstring nullable required

The Meta lead 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 Meta at launch.

leadsnumber required

Whop pixel-attributed leads, last-click.

messaging_configobject nullable required

The click-to-message welcome copy, an object with message and keyword, or null when the ad has none.

multi_advertiser_adsboolean required

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), or null when it uses uploaded creatives.

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

Which network post_id refers to — facebook (a page post) or instagram (a media id) — or 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.

schedulesnumber required

Whop pixel-attributed schedule events, last-click.

social_accountsobject[] required
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

The delivery status of the ad.

submitted_applicationsnumber required

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

titlestring nullable required

The display title of the ad. Falls back to the creative set caption when unset.

unique_click_through_ratenumber nullable required

Unique clicks divided by impressions, between 0 and 1.

unique_clicksnumber required

The number of unique clicks.

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, as a string-to-string map.

viewed_contentsnumber required

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

Example response

{
  "call_to_action": "learn_more",
  "creatives": [
    {
      "format": "square"
    }
  ],
  "delivery_status": "rejected",
  "issues": [
    {
      "resource_type": "ad_campaign"
    }
  ],
  "post_source": "facebook",
  "result_event": "purchase",
  "status": "active"
}

Changes