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

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# Overzicht van de Ads API

> Lanceer Whop Ads via de API door een creative te genereren en vervolgens de campagne, advertentiegroep en advertentie in één verzoek aan te maken.

Whop Ads toont betaalde advertenties op externe advertentienetwerken, rechtstreeks vanuit je Whop-account. Advertentie-uitgaven worden over alle campagnes gefactureerd aan de geconfigureerde kaart of het saldo van het account. Whop regelt het advertentieaccount, de beoordeling, de lancering en de facturering.

Twee API-aanroepen brengen je van niets naar een live advertentie: genereer een creative en maak vervolgens de campagne, advertentiegroep en advertentie aan in één verzoek.

## Resources

| Resource | Doel |
| - | - |
| [Ad Campaign](https://docs.whop.com/nl/api-reference/ad-campaigns/ad-campaign) | Container op het hoogste niveau: doel en (optioneel) budget. |
| [Ad Group](https://docs.whop.com/nl/api-reference/ad-groups/ad-group) | Targeting en budget voor een set advertenties. |
| [Ad](https://docs.whop.com/nl/api-reference/ads/ad) | De creatieve eenheid — tekst, assets, bestemmings-URL. |
| [Audience](https://docs.whop.com/nl/api-reference/audiences/audience) | Een aangepaste doelgroep om in advertentiegroepen te targeten of uit te sluiten. |

## Facturering en betalingsherstel

Uitgaven worden op accountniveau over alle campagnes geïnd. Een mislukte betaling blokkeert de levering met `delivery_status: "payment_failed"`, terwijl de geconfigureerde active/paused `status` van elke campagne behouden blijft. Herstel de betaalmethode van het account en roep vervolgens [Retry Failed Ads Payments](https://docs.whop.com/nl/api-reference/accounts/retry-failed-ads-payments.md) één keer aan voor het account. Het antwoord plaatst een poging op de achtergrond in de wachtrij; het bevestigt de betaling niet. Na verrekening kunnen actieve campagnes hervatten en blijven gepauzeerde campagnes gepauzeerd, afhankelijk van andere leveringsvereisten.

Zie [Betalen voor advertenties](https://docs.whop.com/nl/developer/ads/overview.md#paying-for-ads) voor de flow in het dashboard, een voorbeeldverzoek, het gedrag bij dubbele verzoeken en de afhandeling van legacy-campagnes.

## Eenmalige installatie

* **Scopes**: `media:generate`, `media:read`, `ad_campaign:create`, `ad_campaign:update`, `ad_campaign:basic:read`.
* **Betaalmethode voor advertenties**: gekoppeld in het dashboard (saldo of kaart). Alleen het lanceren vereist deze — concepten werken zonder.

**1. Genereer een creative**

```bash theme={null}
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"}'
```

Gefactureerd vanuit je saldo (`amount_charged`; onvoldoende saldo → `402` met een `deposit_url`). Poll [`GET /media/{id}`](https://docs.whop.com/nl/api-reference/media/retrieve-media-asset) totdat `status` `ready` is en gebruik vervolgens `file.id`:

```json theme={null}
{
	"id": "media_Hx7qg4tZc97o",
	"status": "ready",
	"file": { "id": "file_Zsv4DYkrbWE7h" }
}
```

`failed` betaalt de kosten terug — pas de prompt aan en probeer het opnieuw. Video: `"type": "video"` plus optioneel `duration_seconds` (5/10/15), `resolution` (`480p`–`4k`) en maximaal 4 `reference_media`-bestands-ID's (de eerste vormt de basis voor het openingsframe).

**2. Maak de advertentie aan en lanceer deze — één verzoek**

[`POST /ads`](https://docs.whop.com/nl/api-reference/ads/create-an-ad) met een inline `ad_group` en `ad_campaign` maakt de hele boomstructuur aan in één transactie en lanceert deze:

```bash theme={null}
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"}],
    "ad_group": {
      "title": "US broad",
      "budget_amount": 25,
      "budget_type": "daily",
      "regions": {"include": {"countries": ["US"]}},
      "ad_campaign": {"title": "Run club growth", "objective": "sales"}
    }
  }'
```

Nog niet klaar om uit te geven? Voeg `"status": "draft"` toe aan `ad_campaign` en lanceer later met [`PATCH /ad_campaigns/{id}`](https://docs.whop.com/nl/api-reference/ad-campaigns/update-an-ad-campaign) `{"status": "active"}`.

| Veld | Regel |
| - | - |
| `creatives` | Eén item zonder `format` is verplicht (het basis-asset). `square` / `vertical` / `horizontal` zijn optionele uitsneden daarbovenop. |
| `url` | Verplicht voor website-advertenties. Je whop.com-winkelpagina werkt zoals ze is; een externe pagina vereist dat je [Whop-pixel](https://docs.whop.com/nl/developer/ads/pixel.md) is geïnstalleerd. |
| Budget | Eén niveau is eigenaar: `budget_amount` op de advertentiegroep (standaard), of op de campagne met `budget_optimization: "ad_campaign"` — nooit beide. |
| Valuta | `budget_amount` is in USD, de valuta waarin budgetten worden opgeslagen en gefactureerd. Wil je een budget in plaats daarvan uitdrukken in de `ads_reporting_currency` van het account, stuur dan `budget_amount_local`; Whop rekent dit om tegen de actuele koers en slaat het USD-resultaat op. Stuur het een of het ander, nooit beide. Antwoorden bevatten `budget_amount`, `budget_amount_local` en `budget_currency`. |
| Targeting | Laat `demographics` / `devices` weg voor automatische optimalisatie. `regions` gebruikt ISO 3166 (`"US"`, `"US-CA"`). |

Om bestaande containers te hergebruiken, geef je `ad_group_id` door in plaats van `ad_group`, of `ad_campaign_id` in plaats van `ad_campaign`.

**3. Monitoren**

Poll [`GET /ads/{id}`](https://docs.whop.com/nl/api-reference/ads/retrieve-an-ad): `delivery_status` is de live status (een korte `in_review` voor contentmoderatie is normaal), en `issues[]` bevat een leesbaar `message` voor alles wat het advertentienetwerk asynchroon heeft afgewezen.

Beheer de levering met [`pause`](https://docs.whop.com/nl/api-reference/ads/pause-an-ad) / [`unpause`](https://docs.whop.com/nl/api-reference/ads/unpause-an-ad) op advertenties, advertentiegroepen of campagnes. Bewerk tekst of creatives met [`PATCH /ads/{id}`](https://docs.whop.com/nl/api-reference/ads/update-an-ad) — het meesturen van `creatives` vervangt de hele set, dus neem het basisitem op.

## Fouten

Elke controle is een `400` waarvan het bericht aangeeft wat je moet oplossen:

| Fout bevat | Oplossing |
| - | - |
| `The Whop pixel was not detected on <url>` | Gebruik je eigen whop.com-winkelpagina, of [installeer de pixel](https://docs.whop.com/nl/developer/ads/pixel.md) op de landingspagina. |
| `Connect an ads payment method before launching` | Maak aan met `ad_campaign.status: "draft"`, laat de gebruiker een betaalmethode koppelen in het dashboard en voer vervolgens een `PATCH` uit naar `active`. |
| `Include a base creative` | Voeg een `creatives`-item toe zonder `format`. |
| `A destination URL is required` | Geef `url` door. |
| `budget_amount is required` / `can't be set` | Verplaats het budget naar het juiste niveau (zie de veldregels hierboven). |
| `Provide either budget_amount (USD) or budget_amount_local` | De twee velden gaven verschillende budgetten op; stuur er één. Een teruggestuurde `GET`-body, waarvan het lokale bedrag het opgeslagen bedrag herhaalt, is prima. |
| `503` `Exchange rate for <currency> is unavailable` | Whop heeft op dit moment geen actuele koers voor de rapportagevaluta van het account; probeer het over een paar minuten opnieuw. |
| `402` + `deposit_url` (media) | Stuur de gebruiker naar `deposit_url` om op te waarderen en probeer het daarna opnieuw. |


## Related topics

- [Adverteren met Whop Ads](https://docs.whop.com/nl/developer/ads/overview.md)
- [Overzicht van de Whop API](https://docs.whop.com/nl/api-reference/overview.md)
- [Kernconcepten van de Whop API](https://docs.whop.com/nl/developer/concepts.md)
