Overview - Whop Docs

Whop Ads runs paid ads on networks like Meta directly from your Whop account. Ads spend is billed to the account’s configured card or balance across its campaigns. Whop handles the ad account, review, launch, and billing. Two API calls take you from nothing to a live ad: generate a creative, then create the campaign, ad group, and ad in one request.

Resources

Resource	Purpose
Ad Campaign	Top-level container: objective and (optionally) budget.
Ad Group	Targeting, placements, and budget for a set of ads.
Ad	The creative unit — copy, assets, destination URL.
Audience	A custom audience to target or exclude in ad groups.

Billing and payment recovery

Spend is collected at account level across campaigns. A failed payment blocks delivery with delivery_status: "payment_failed" while preserving each campaign’s configured active/paused status. Fix the account’s payment method, then call Retry Failed Ads Payments once for the account. The response queues a background attempt; it does not confirm payment. After settlement, active campaigns can resume and paused campaigns stay paused, subject to other delivery requirements. See Paying for ads for the dashboard flow, request example, duplicate-request behavior, and legacy campaign handling.

One-time setup

Scopes: media:generate, media:read, ad_campaign:create, ad_campaign:update, ad_campaign:basic:read, social_account:read.
Facebook page: GET /social_accounts must have a "platform": "facebook" entry. If not, link your Meta Business account with POST /social_accounts/connect {"platform": "meta_business", "scopes": ["advertise"], "redirect_url": "..."} → send the user to the returned authorize_url — or, if you don’t have a page at all, have Whop create one with POST /social_accounts {"platform": "facebook"}.
Ads payment method: connected in the dashboard (balance or card). Only launching needs it — drafts work without.

Generate a creative

curl -X POST "https://api.whop.com/api/v1/media/generate" \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "image", "prompt": "A running club jogging across a bridge at sunrise, warm light, joyful energy"}'

Billed from your balance (amount_charged; not enough balance → 402 with a deposit_url). Poll GET /media/{id} until status is ready, then use file.id:

{
	"id": "media_Hx7qg4tZc97o",
	"status": "ready",
	"file": { "id": "file_Zsv4DYkrbWE7h" }
}

failed refunds the charge — tweak the prompt and retry. Video: "type": "video" plus optional duration_seconds (5/10/15), resolution (480p–4k), and up to 4 reference_media file IDs (first one seeds the opening frame).

Create and launch the ad — one request

POST /ads with an inline ad_group and ad_campaign creates the whole tree in one transaction and launches it:

curl -X POST "https://api.whop.com/api/v1/ads" \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Run club launch ad",
    "primary_texts": ["Join 10,000 runners chasing their next PR together."],
    "headlines": ["Find your stride"],
    "call_to_action": "sign_up",
    "url": "https://whop.com/your-store-page",
    "creatives": [{"id": "file_Zsv4DYkrbWE7h"}],
    "social_accounts": [{"id": "sacc_XXXXXXXX"}],
    "ad_group": {
      "title": "US broad",
      "conversion_location": "website",
      "budget_amount": 25,
      "budget_type": "daily",
      "regions": {"include": {"countries": ["US"]}},
      "ad_campaign": {"title": "Run club growth", "platform": "meta", "objective": "sales"}
    }
  }'

Not ready to spend? Add "status": "draft" to ad_campaign, then launch later with PATCH /ad_campaigns/{id} {"status": "active"}.

Field	Rule
`creatives`	One entry with no `format` is required (the base asset). `square` / `vertical` / `horizontal` are optional crops on top.
`url`	Required for website ads. Your whop.com store page works as-is; an external page needs your Whop pixel installed.
Budget	One level owns it: `budget_amount` on the ad group (default), or on the campaign with `budget_optimization: "ad_campaign"` — never both.
Currency	`budget_amount` is USD, which budgets are stored and billed in. To state a budget in the account’s `ads_reporting_currency` instead, send `budget_amount_local`; Whop converts it at the current rate and stores the USD result. Send one or the other, never both. Responses carry `budget_amount`, `budget_amount_local`, and `budget_currency`.
Targeting	Omit `demographics` / `placements` / `devices` for automatic optimization. `regions` uses ISO 3166 (`"US"`, `"US-CA"`).
`lead_form`	Only with an instant-form `conversion_location`.

To reuse existing containers, pass ad_group_id instead of ad_group, or ad_campaign_id instead of ad_campaign.

Monitor

Poll GET /ads/{id}: delivery_status is the live state (a brief in_review for content moderation is normal), and issues[] carries a human-readable message for anything Meta rejected asynchronously.Control delivery with pause / unpause on ads, ad groups, or campaigns. Edit copy or creatives with PATCH /ads/{id} — sending creatives replaces the whole set, so include the base entry.

Errors

Every gate is a 400 whose message says what to fix:

Error contains	Fix
`The Whop pixel was not detected on <url>`	Use your own whop.com store page, or install the pixel on the landing page.
`A Facebook page is required`	Connect one via `POST /social_accounts` (human OAuth step), pass it in `social_accounts`.
`Connect an ads payment method before launching`	Create with `ad_campaign.status: "draft"`, have the user connect a payment method in the dashboard, then `PATCH` to `active`.
`Include a base creative`	Add a `creatives` entry with no `format`.
`A destination URL is required`	Pass `url`.
`budget_amount is required` / `can't be set`	Move the budget to the right level (see the earlier field rules).
`Provide either budget_amount (USD) or budget_amount_local`	The two fields named different budgets; send one. An echoed `GET` body, whose local amount restates the stored one, is fine.
`503` `Exchange rate for <currency> is unavailable`	Whop has no fresh rate for the account’s reporting currency right now; retry in a few minutes.
`402` + `deposit_url` (media)	Send the user to `deposit_url` to top up, then retry.

​Resources

​Billing and payment recovery

​One-time setup

​Errors

Resources

Billing and payment recovery

One-time setup

Errors