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

# Anuncia con Whop Ads

> Compra anuncios en redes publicitarias externas a través de tu cuenta de Whop, con la facturación gestionada a nivel de cuenta.

La publicidad te permite comprar anuncios en redes publicitarias externas desde tu cuenta de Whop. Whop es propietario de la cuenta publicitaria, del proceso de revisión y lanzamiento, y de la relación de facturación. Creas una campaña a través de la API en lugar de conectar una cuenta publicitaria que gestiones tú mismo.

## Qué puedes crear

* **Ejecutar campañas** con un objetivo, un presupuesto y una programación.
* **Segmentar una audiencia** por ubicación, datos demográficos, intereses, dispositivos e idiomas, o subir una lista de clientes como una [audiencia](https://docs.whop.com/es/api-reference/audiences/audience).
* **Generar creatividades** como imágenes o videos con IA a partir de un prompt, aportar tus propios recursos o promocionar una publicación que ya existe en una cuenta externa conectada.
* **Consultar el rendimiento atribuido**: gasto, resultados, costo por resultado y retorno de la inversión publicitaria, todo en el propio objeto de campaña.

## Países a los que no puedes dirigirte

Whop no permite que las campañas se dirijan a estos países:

| País | Código de país |
| - | - |
| Sudán | `SD` |
| Rusia | `RU` |
| Cuba | `CU` |
| Irán | `IR` |
| Corea del Norte | `KP` |

Las solicitudes para crear un grupo de anuncios o actualizar sus países objetivo se rechazan si incluyen alguno de estos códigos. Elimínalos de tus ubicaciones objetivo antes de enviar la solicitud.

## Antes de gastar

Dos requisitos condicionan un anuncio activo, y ambos son configuraciones únicas:

* **Un método de pago** conectado en el panel, ya sea tu saldo de Whop o una tarjeta. Los borradores funcionan sin uno.
* **El píxel de Whop** en tu destino, a menos que envíes tráfico a una página de tienda de whop.com. Cualquier página de destino externa necesita primero [el píxel](https://docs.whop.com/es/developer/ads/pixel.md).

La [descripción general de la API de anuncios](https://docs.whop.com/es/api-reference/ads/overview.md) cubre cada uno de estos con las llamadas exactas, los permisos requeridos y los mensajes de error que recibes cuando falta alguno.

## Objetos principales

Campaña publicitaria, grupo de anuncios, anuncio, audiencia. Cada uno se define en [Conceptos principales](https://docs.whop.com/es/developer/concepts.md).

La publicidad tiene una sola jerarquía, y cada objeto pertenece al nivel superior.

**ad campaign** `adcamp_`

Contiene el objetivo y la estrategia de presupuesto. Consulta [Campañas publicitarias](https://docs.whop.com/es/api-reference/ad-campaigns/ad-campaign).

**ad group** `adgrp_`

Contiene la segmentación, el objetivo de optimización, la programación y, de forma predeterminada, su propio presupuesto. Consulta [Grupos de anuncios](https://docs.whop.com/es/api-reference/ad-groups/ad-group).

**ad** `ad_`

Contiene las creatividades, las variantes de texto, la llamada a la acción y la URL de destino. Consulta [Anuncios](https://docs.whop.com/es/api-reference/ads/ad).

[`POST /ads`](https://docs.whop.com/es/api-reference/ads/create-an-ad) acepta un `ad_group` en línea, que a su vez acepta un `ad_campaign` en línea, por lo que una sola solicitud crea todo el árbol en una única transacción. Pasa `ad_group_id` en su lugar para asociar el anuncio a un grupo de anuncios que ya existe.

Para lanzar más tarde en lugar de ahora, establece `status` en `draft` en el `ad_campaign` en línea y luego actívalo con [`PATCH /ad_campaigns/{id}`](https://docs.whop.com/es/api-reference/ad-campaigns/update-an-ad-campaign).

El presupuesto vive exactamente en un nivel, nunca en ambos: en el grupo de anuncios de forma predeterminada, o en la campaña cuando estableces `budget_optimization` en `ad_campaign`.

## Cómo se cuentan los resultados

Cada métrica de rendimiento que reporta Whop se atribuye mediante el **píxel de Whop**, no mediante la red publicitaria.

`result_event` indica el evento de conversión con el que se evalúa una campaña, y `results` es el recuento de ese evento atribuido por el píxel. `cost_per_result` divide el gasto entre ese recuento. Cuando los grupos de anuncios de una campaña optimizan hacia objetivos diferentes, no hay un único `result_event`, por lo que es `null` y `results` pasa a ser la suma de los resultados atribuidos de cada grupo de anuncios. Cuando no se optimiza nada atribuible por Whop, ambos son `null` en lugar de cero.

## Costo deseado por resultado

El `desired_cost_per_result` de una campaña es el costo por resultado, en USD, que quieres que alcance. Es solo un objetivo: no es un límite de costo ni un límite de puja, y no cambia la forma en que pujan los anuncios de la campaña. Los afiliados que ejecutan la campaña lo ven como el costo por resultado al que deben apuntar. El `desired_cost_per_result` propio de un grupo de anuncios es un ajuste diferente: ese sí es su límite de costo o límite de puja. Establece el `desired_cost_per_result` de la campaña en `null` para eliminar el objetivo.

## Pago de los anuncios

El gasto se acumula a medida que se entregan los anuncios y se cobra después. **La facturación pertenece a la cuenta, abarcando todas sus campañas.** Cada cobro combina el gasto no pagado elegible de las campañas en un solo pago usando los métodos de pago de anuncios configurados en la cuenta. No configuras un método de pago independiente ni solicitas un reintento independiente para cada campaña. El campo `spend` de una campaña es el importe que se te cobra, en `spend_currency`.

El momento del cobro depende del gasto acumulado y de los umbrales de facturación. La consolidación no significa un pago por día. La generación de creatividades con IA usa su propio pago con saldo. Un saldo insuficiente devuelve un `402` que incluye una `deposit_url`.

### Cuando falla un pago

Un fallo de pago de la cuenta bloquea la entrega en todas sus campañas facturables. Cada campaña afectada reporta `delivery_status: "payment_failed"`, mientras que su `status` configurado sigue siendo `active` o `paused`. Lee `delivery_status` para determinar si una campaña puede entregarse, e `issues` para conocer el motivo del fallo.

La cuenta no puede activar campañas mientras tenga fallos de pago sin resolver. Aún puedes pausar una campaña para que siga desactivada después de recuperar el pago. Whop también programa reintentos automáticos. Puedes solicitar un reintento después de corregir el método de pago.

### Reintentar un pago

1. En el panel de anuncios de tu cuenta, selecciona **Update payment method** en el banner de pago fallido, o abre la configuración de anuncios y selecciona **Billing**. Actualiza la tarjeta de la cuenta o recarga el saldo que utiliza.
2. Selecciona **Retry payment** una vez para la cuenta. Las integraciones con la API deben llamar a [Reintentar pagos de anuncios fallidos](https://docs.whop.com/es/api-reference/accounts/retry-failed-ads-payments.md) con el ID `biz_` de la cuenta y el permiso `ad_campaign:update`.
3. Espera el intento en segundo plano. Una respuesta `202` con `queued: true` confirma que el trabajo fue aceptado, **no que el pago se haya realizado correctamente**. Consulta las [campañas publicitarias](https://docs.whop.com/es/api-reference/ad-campaigns/list-ad-campaigns.md) de la cuenta para ver el resultado.
4. Tras una liquidación exitosa, el bloqueo de pago se elimina. La entrega puede mostrar `processing` mientras se recalcula y sincroniza. Las campañas configuradas como activas pueden reanudarse si se cumplen sus demás requisitos de entrega. Las campañas configuradas como pausadas permanecen pausadas.

```bash theme={null}
curl -X POST "https://api.whop.com/api/v1/accounts/biz_YOUR_ACCOUNT/retry_ads_payment" \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-09-22"
```

```json theme={null}
{ "account_id": "biz_YOUR_ACCOUNT", "queued": true }
```

Las solicitudes repetidas mientras un reintento de la cuenta está en cola o en ejecución devuelven un error que te pide esperar. Si el pago vuelve a fallar, la entrega sigue bloqueada: revisa el motivo del fallo y corrige el método de pago antes de volver a intentarlo. No recorras las campañas para reintentar cada una. El [endpoint anterior de reintento de campaña](https://docs.whop.com/es/api-reference/ad-campaigns/retry-a-failed-ad-campaign-payment.md) aún pone en cola un reintento de la cuenta en versiones de la API anteriores a `2026-09-22`. A partir de `2026-09-22`, devuelve `410 Gone`. Usa el endpoint de cuenta indicado arriba.

Las campañas más antiguas cuyo `status` configurado ya era `payment_failed` vuelven a `paused` después de un reintento exitoso, porque no se conservó su ajuste anterior de activa/pausada.

## Por qué una campaña no se está entregando

`delivery_status` responde esto directamente. Es el primer campo que debes leer cuando una campaña existe pero no ocurre nada. Varios estados pueden ser verdaderos a la vez, por lo que el valor es el más alto en esta escala:

| `delivery_status` | Qué significa |
| - | - |
| `payment_failed` | La facturación de la cuenta falló. La entrega está bloqueada sin cambiar el ajuste configurado de activa/pausada |
| `all_ads_rejected` | Todos los anuncios de la campaña fueron rechazados |
| `draft` | No se ha enviado para entrega |
| `paused` | Pausaste la campaña o todos sus grupos de anuncios, o ya no le quedan anuncios. Eliminar el último anuncio o grupo de anuncios de una campaña la pausa |
| `in_review` | Un anuncio sigue en revisión de contenido y todavía no se entrega nada |
| `learning` | Entregándose, y aún en su período de aprendizaje |
| `processing` | La campaña no ha llegado a la red publicitaria, o todos los grupos de anuncios siguen procesándose |
| `revise_content` | La campaña está esperando para ejecutarse y la revisión de contenido mantiene cada anuncio en espera fuera de al menos una red publicitaria. Lee el `content_review` de cada anuncio |
| `issues` | La campaña tiene incidencias abiertas, o todos los anuncios tienen una. Lee el array `issues` |
| `scheduled` | El inicio de la campaña es en el futuro, o todos los grupos de anuncios están esperando su propio inicio |
| `completed` | La hora de finalización de la campaña ya pasó. Una campaña sin fin nunca se completa |
| `active` | Entregándose |

Los anuncios y los grupos de anuncios tienen su propio `delivery_status` con valores diferentes. Un anuncio nuevo pasa por `in_review` antes de entregarse.

## Próximos pasos

> [card] [Crear y lanzar un anuncio](https://docs.whop.com/es/api-reference/ads/overview.md)
>
> El flujo completo, de la creatividad al anuncio activo, en dos llamadas.

> [card] [Instalar el píxel](https://docs.whop.com/es/developer/ads/pixel.md)
>
> Necesario antes de poder atribuir resultados.

> [card] [Crear una audiencia](https://docs.whop.com/es/api-reference/audiences/create-audience.md)
>
> Sube una lista de clientes para segmentarla o excluirla.

> [card] [Referencia de anuncios](https://docs.whop.com/es/api-reference/ad-campaigns/ad-campaign)
>
> Todos los endpoints de publicidad, con un playground.


## Related topics

- [Ads](https://docs.whop.com/es/elements/latest/ads/overview.md)
- [AdsAgreementElement](https://docs.whop.com/es/elements/latest/ads/ads-agreement.md)
- [Primeros pasos con Elements](https://docs.whop.com/es/elements/latest/getting-started.md)
