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

# Descripción general de la API de Ads

> Lanza Whop Ads a través de la API generando una creatividad y luego creando la campaña, el grupo de anuncios y el anuncio en una sola solicitud.

Whop Ads ejecuta anuncios pagados en redes publicitarias externas directamente desde tu cuenta de Whop. El gasto en anuncios se cobra a la tarjeta o al saldo configurados en la cuenta, en todas sus campañas. Whop se encarga de la cuenta publicitaria, la revisión, el lanzamiento y la facturación.

Dos llamadas a la API te llevan de cero a un anuncio activo: genera una creatividad y luego crea la campaña, el grupo de anuncios y el anuncio en una sola solicitud.

## Recursos

| Recurso | Propósito |
| - | - |
| [Ad Campaign](https://docs.whop.com/es/api-reference/ad-campaigns/ad-campaign) | Contenedor de nivel superior: objetivo y (opcionalmente) presupuesto. |
| [Ad Group](https://docs.whop.com/es/api-reference/ad-groups/ad-group) | Segmentación y presupuesto para un conjunto de anuncios. |
| [Ad](https://docs.whop.com/es/api-reference/ads/ad) | La unidad creativa: textos, recursos y URL de destino. |
| [Audience](https://docs.whop.com/es/api-reference/audiences/audience) | Una audiencia personalizada para incluir o excluir en los grupos de anuncios. |

## Facturación y recuperación de pagos

El gasto se cobra a nivel de cuenta en todas las campañas. Un pago fallido bloquea la entrega con `delivery_status: "payment_failed"` y conserva el `status` activo/en pausa configurado de cada campaña. Corrige el método de pago de la cuenta y luego llama a [Reintentar pagos de anuncios fallidos](https://docs.whop.com/es/api-reference/accounts/retry-failed-ads-payments.md) una vez para la cuenta. La respuesta pone en cola un intento en segundo plano; no confirma el pago. Tras la liquidación, las campañas activas pueden reanudarse y las campañas en pausa siguen en pausa, sujetas a otros requisitos de entrega.

Consulta [Pagar los anuncios](https://docs.whop.com/es/developer/ads/overview.md#paying-for-ads) para ver el flujo en el panel, un ejemplo de solicitud, el comportamiento ante solicitudes duplicadas y el manejo de campañas heredadas.

## Configuración única

* **Scopes**: `media:generate`, `media:read`, `ad_campaign:create`, `ad_campaign:update`, `ad_campaign:basic:read`.
* **Método de pago de anuncios**: se conecta en el panel (saldo o tarjeta). Solo se necesita para lanzar; los borradores funcionan sin él.

**1. Genera una creatividad**

```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"}'
```

Se cobra de tu saldo (`amount_charged`; si el saldo no alcanza → `402` con un `deposit_url`). Consulta periódicamente [`GET /media/{id}`](https://docs.whop.com/es/api-reference/media/retrieve-media-asset) hasta que `status` sea `ready` y luego usa `file.id`:

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

`failed` reembolsa el cargo: ajusta el prompt y vuelve a intentarlo. Video: `"type": "video"` más, opcionalmente, `duration_seconds` (5/10/15), `resolution` (`480p`–`4k`) y hasta 4 IDs de archivo en `reference_media` (el primero define el fotograma inicial).

**2. Crea y lanza el anuncio en una sola solicitud**

[`POST /ads`](https://docs.whop.com/es/api-reference/ads/create-an-ad) con un `ad_group` y un `ad_campaign` en línea crea todo el árbol en una sola transacción y lo lanza:

```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"}
    }
  }'
```

¿Todavía no quieres gastar? Añade `"status": "draft"` a `ad_campaign` y lánzalo más tarde con [`PATCH /ad_campaigns/{id}`](https://docs.whop.com/es/api-reference/ad-campaigns/update-an-ad-campaign) `{"status": "active"}`.

| Campo | Regla |
| - | - |
| `creatives` | Se requiere una entrada sin `format` (el recurso base). `square` / `vertical` / `horizontal` son recortes opcionales adicionales. |
| `url` | Obligatorio para anuncios de sitio web. Tu página de tienda en whop.com funciona tal cual; una página externa necesita tener instalado tu [píxel de Whop](https://docs.whop.com/es/developer/ads/pixel.md). |
| Presupuesto | Solo un nivel lo posee: `budget_amount` en el grupo de anuncios (predeterminado), o en la campaña con `budget_optimization: "ad_campaign"`, nunca en ambos. |
| Moneda | `budget_amount` está en USD, la moneda en la que se almacenan y facturan los presupuestos. Para indicar un presupuesto en el `ads_reporting_currency` de la cuenta, envía `budget_amount_local`; Whop lo convierte al tipo de cambio actual y almacena el resultado en USD. Envía uno u otro, nunca ambos. Las respuestas incluyen `budget_amount`, `budget_amount_local` y `budget_currency`. |
| Segmentación | Omite `demographics` / `devices` para la optimización automática. `regions` usa ISO 3166 (`"US"`, `"US-CA"`). |

Para reutilizar contenedores existentes, pasa `ad_group_id` en lugar de `ad_group`, o `ad_campaign_id` en lugar de `ad_campaign`.

**3. Supervisa**

Consulta periódicamente [`GET /ads/{id}`](https://docs.whop.com/es/api-reference/ads/retrieve-an-ad): `delivery_status` es el estado en vivo (un breve `in_review` para la moderación de contenido es normal), e `issues[]` incluye un `message` legible para cualquier cosa que la red publicitaria haya rechazado de forma asíncrona.

Controla la entrega con [`pause`](https://docs.whop.com/es/api-reference/ads/pause-an-ad) / [`unpause`](https://docs.whop.com/es/api-reference/ads/unpause-an-ad) en anuncios, grupos de anuncios o campañas. Edita los textos o las creatividades con [`PATCH /ads/{id}`](https://docs.whop.com/es/api-reference/ads/update-an-ad): enviar `creatives` reemplaza todo el conjunto, así que incluye la entrada base.

## Errores

Cada validación es un `400` cuyo mensaje indica qué corregir:

| El error contiene | Solución |
| - | - |
| `The Whop pixel was not detected on <url>` | Usa tu propia página de tienda en whop.com, o [instala el píxel](https://docs.whop.com/es/developer/ads/pixel.md) en la página de destino. |
| `Connect an ads payment method before launching` | Crea con `ad_campaign.status: "draft"`, haz que el usuario conecte un método de pago en el panel y luego haz `PATCH` a `active`. |
| `Include a base creative` | Añade una entrada en `creatives` sin `format`. |
| `A destination URL is required` | Pasa `url`. |
| `budget_amount is required` / `can't be set` | Mueve el presupuesto al nivel correcto (consulta las reglas de campos anteriores). |
| `Provide either budget_amount (USD) or budget_amount_local` | Los dos campos indicaban presupuestos distintos; envía uno. Un cuerpo de `GET` reenviado, cuyo importe local repite el almacenado, es válido. |
| `503` `Exchange rate for <currency> is unavailable` | Whop no tiene ahora un tipo de cambio actualizado para la moneda de informes de la cuenta; vuelve a intentarlo en unos minutos. |
| `402` + `deposit_url` (media) | Envía al usuario a `deposit_url` para recargar saldo y luego vuelve a intentarlo. |


## Related topics

- [Descripción general de la API de Whop](https://docs.whop.com/es/api-reference/overview.md)
- [Conceptos principales de la API de Whop](https://docs.whop.com/es/developer/concepts.md)
- [API de Ads](https://docs.whop.com/es/api-reference/ads/ad.md)
