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

# Faire de la publicité avec Whop Ads

> Achetez des publicités sur des réseaux publicitaires externes depuis votre compte Whop, avec une facturation gérée au niveau du compte.

La publicité vous permet d'acheter des annonces sur des réseaux publicitaires externes depuis votre compte Whop. Whop détient le compte publicitaire, le processus de vérification et de lancement, ainsi que la relation de facturation. Vous créez une campagne via l'API au lieu de connecter un compte publicitaire que vous gérez vous-même.

## Ce que vous pouvez créer

* **Lancez des campagnes** avec un objectif, un budget et un calendrier.
* **Ciblez une audience** par localisation, données démographiques, centres d'intérêt, appareils et langues, ou importez une liste de clients en tant qu'[audience](https://docs.whop.com/fr/api-reference/audiences/audience).
* **Générez des créations** sous forme d'images ou de vidéos IA à partir d'un prompt, fournissez vos propres ressources, ou mettez en avant une publication qui existe déjà sur un compte externe connecté.
* **Consultez les performances attribuées** : dépenses, résultats, coût par résultat et retour sur dépenses publicitaires, le tout directement sur l'objet campagne.

## Pays que vous ne pouvez pas cibler

Whop n'autorise pas les campagnes à cibler les pays suivants :

| Pays | Code pays |
| - | - |
| Soudan | `SD` |
| Russie | `RU` |
| Cuba | `CU` |
| Iran | `IR` |
| Corée du Nord | `KP` |

Les requêtes de création d'un groupe d'annonces ou de mise à jour de ses pays ciblés sont rejetées si elles incluent l'un de ces codes. Retirez-les de vos localisations ciblées avant d'envoyer la requête.

## Avant de dépenser

Deux éléments conditionnent la diffusion d'une annonce, et tous deux ne se configurent qu'une seule fois :

* **Un moyen de paiement** connecté dans le tableau de bord, soit votre solde Whop, soit une carte. Les brouillons fonctionnent sans.
* **Le pixel Whop** sur votre destination, sauf si vous envoyez le trafic vers une page de boutique whop.com. Toute page de destination externe nécessite d'abord [le pixel](https://docs.whop.com/fr/developer/ads/pixel.md).

La [vue d'ensemble de l'API Ads](https://docs.whop.com/fr/api-reference/ads/overview.md) couvre chacun de ces points avec les appels exacts, les scopes requis et les messages d'erreur que vous obtenez lorsque l'un d'eux manque.

## Objets principaux

Campagne publicitaire, groupe d'annonces, annonce, audience. Chacun est défini dans [Concepts clés](https://docs.whop.com/fr/developer/concepts.md).

La publicité suit une seule hiérarchie, et chaque objet appartient au niveau supérieur.

**ad campaign** `adcamp_`

Contient l'objectif et la stratégie de budget. Voir [Campagnes publicitaires](https://docs.whop.com/fr/api-reference/ad-campaigns/ad-campaign).

**ad group** `adgrp_`

Contient le ciblage, l'objectif d'optimisation, le calendrier et, par défaut, son propre budget. Voir [Groupes d'annonces](https://docs.whop.com/fr/api-reference/ad-groups/ad-group).

**ad** `ad_`

Contient les créations, les variantes de texte, l'appel à l'action et l'URL de destination. Voir [Annonces](https://docs.whop.com/fr/api-reference/ads/ad).

[`POST /ads`](https://docs.whop.com/fr/api-reference/ads/create-an-ad) accepte un `ad_group` en ligne, qui accepte lui-même un `ad_campaign` en ligne, de sorte qu'une seule requête crée toute l'arborescence en une seule transaction. Passez plutôt `ad_group_id` pour rattacher l'annonce à un groupe d'annonces existant.

Pour lancer plus tard plutôt que maintenant, définissez `status` sur `draft` dans l'`ad_campaign` en ligne, puis activez-la avec [`PATCH /ad_campaigns/{id}`](https://docs.whop.com/fr/api-reference/ad-campaigns/update-an-ad-campaign).

Le budget se situe à un seul niveau, jamais aux deux : sur le groupe d'annonces par défaut, ou sur la campagne lorsque vous définissez `budget_optimization` sur `ad_campaign`.

## Comment les résultats sont comptabilisés

Chaque indicateur de performance rapporté par Whop est attribué par le **pixel Whop**, et non par le réseau publicitaire.

`result_event` désigne l'événement de conversion sur lequel une campagne est évaluée, et `results` en est le nombre attribué par le pixel. `cost_per_result` divise les dépenses par ce nombre. Lorsque les groupes d'annonces d'une campagne optimisent vers des objectifs différents, il n'existe pas de `result_event` unique : il vaut donc `null` et `results` devient la somme des résultats attribués de chaque groupe d'annonces. Lorsque rien d'attribuable par Whop n'est optimisé, les deux valent `null` plutôt que zéro.

## Coût par résultat souhaité

Le `desired_cost_per_result` d'une campagne est le coût par résultat, en USD, que vous souhaitez atteindre. Il s'agit uniquement d'un objectif : ce n'est ni un plafond de coût ni un plafond d'enchère, et il ne modifie pas la façon dont les annonces de la campagne enchérissent. Les affiliés qui gèrent la campagne le voient comme le coût par résultat à viser. Le `desired_cost_per_result` propre à un groupe d'annonces est un paramètre différent : celui-ci correspond à son plafond de coût ou d'enchère. Définissez le `desired_cost_per_result` de la campagne sur `null` pour supprimer l'objectif.

## Payer les publicités

Les dépenses s'accumulent au fil de la diffusion des annonces et sont facturées ensuite. **La facturation appartient au compte, pour l'ensemble de ses campagnes.** Chaque encaissement regroupe les dépenses de campagne impayées éligibles en un seul paiement, à l'aide des moyens de paiement publicitaires configurés pour le compte. Vous ne configurez pas de moyen de paiement distinct et ne demandez pas de nouvelle tentative séparée pour chaque campagne. Le champ `spend` d'une campagne correspond au montant qui vous est facturé, en `spend_currency`.

Le moment de l'encaissement dépend des dépenses accumulées et des seuils de facturation. Le regroupement ne signifie pas un paiement par jour. La génération de créations par IA utilise son propre paiement sur le solde. Un solde insuffisant renvoie une erreur `402` contenant une `deposit_url`.

### Lorsqu'un paiement échoue

Un échec de paiement du compte bloque la diffusion de toutes ses campagnes facturables. Chaque campagne concernée indique `delivery_status: "payment_failed"`, tandis que son `status` configuré reste `active` ou `paused`. Lisez `delivery_status` pour déterminer si une campagne peut être diffusée, et `issues` pour connaître la raison de l'échec.

Le compte ne peut pas activer de campagnes tant qu'il a des échecs de paiement non résolus. Vous pouvez toujours mettre une campagne en pause pour qu'elle reste désactivée après le rétablissement du paiement. Whop planifie également des nouvelles tentatives automatiques. Vous pouvez demander une nouvelle tentative après avoir corrigé le moyen de paiement.

### Relancer un paiement

1. Dans le tableau de bord Ads de votre compte, sélectionnez **Update payment method** dans la bannière de paiement échoué, ou ouvrez les paramètres Ads et sélectionnez **Billing**. Mettez à jour la carte du compte ou approvisionnez le solde qu'il utilise.
2. Sélectionnez **Retry payment** une seule fois pour le compte. Les intégrations API doivent appeler [Retry Failed Ads Payments](https://docs.whop.com/fr/api-reference/accounts/retry-failed-ads-payments.md) avec l'ID `biz_` du compte et la permission `ad_campaign:update`.
3. Attendez la tentative en arrière-plan. Une réponse `202` avec `queued: true` confirme que la tâche a été acceptée, **et non que le paiement a réussi**. Consultez les [campagnes publicitaires](https://docs.whop.com/fr/api-reference/ad-campaigns/list-ad-campaigns.md) du compte pour connaître le résultat.
4. Après un règlement réussi, le blocage de paiement est levé. La diffusion peut afficher `processing` pendant son recalcul et sa synchronisation. Les campagnes configurées comme actives peuvent reprendre si leurs autres conditions de diffusion sont remplies. Les campagnes configurées en pause restent en pause.

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

Les requêtes répétées alors qu'une nouvelle tentative du compte est en file d'attente ou en cours renvoient une erreur vous demandant de patienter. Si le paiement échoue à nouveau, la diffusion reste bloquée : vérifiez la raison de l'échec et corrigez le moyen de paiement avant de réessayer. Ne parcourez pas les campagnes pour relancer chacune d'elles. L'ancien [endpoint de nouvelle tentative par campagne](https://docs.whop.com/fr/api-reference/ad-campaigns/retry-a-failed-ad-campaign-payment.md) met toujours en file d'attente une nouvelle tentative du compte sur les versions de l'API antérieures à `2026-09-22`. À partir de `2026-09-22`, il renvoie `410 Gone`. Utilisez l'endpoint de compte ci-dessus.

Les anciennes campagnes dont le `status` configuré était déjà `payment_failed` repassent à `paused` après une nouvelle tentative réussie, car leur précédent réglage actif/en pause n'a pas été conservé.

## Pourquoi une campagne n'est pas diffusée

`delivery_status` répond directement à cette question. C'est le premier champ à consulter lorsqu'une campagne existe mais que rien ne se passe. Plusieurs états peuvent être vrais simultanément ; la valeur est donc la plus haute sur cette échelle :

| `delivery_status` | Signification |
| - | - |
| `payment_failed` | La facturation du compte a échoué. La diffusion est bloquée sans modifier le réglage actif/en pause configuré |
| `all_ads_rejected` | Toutes les annonces de la campagne ont été rejetées |
| `draft` | Non soumise pour diffusion |
| `paused` | Vous avez mis en pause la campagne ou tous ses groupes d'annonces, ou elle n'a plus d'annonces. La suppression de la dernière annonce ou du dernier groupe d'annonces d'une campagne la met en pause |
| `in_review` | Une annonce est encore en cours de vérification du contenu et rien n'est encore diffusé |
| `learning` | En cours de diffusion, et toujours en période d'apprentissage |
| `processing` | La campagne n'a pas encore atteint le réseau publicitaire, ou tous les groupes d'annonces sont encore en cours de traitement |
| `revise_content` | La campagne attend d'être diffusée et la vérification du contenu bloque chaque annonce en attente sur au moins un réseau publicitaire. Consultez le `content_review` de chaque annonce |
| `issues` | La campagne présente des problèmes ouverts, ou chaque annonce en présente un. Consultez le tableau `issues` |
| `scheduled` | Le début de la campagne est dans le futur, ou chaque groupe d'annonces attend son propre début |
| `completed` | La date de fin de la campagne est passée. Une campagne sans date de fin ne se termine jamais |
| `active` | En cours de diffusion |

Les annonces et les groupes d'annonces ont leur propre `delivery_status` avec des valeurs différentes. Une nouvelle annonce passe par `in_review` avant d'être diffusée.

## Pour aller plus loin

> [card] [Créer et lancer une annonce](https://docs.whop.com/fr/api-reference/ads/overview.md)
>
> Le parcours complet, de la création à l'annonce en ligne, en deux appels.

> [card] [Installer le pixel](https://docs.whop.com/fr/developer/ads/pixel.md)
>
> Requis avant que les résultats puissent être attribués.

> [card] [Créer une audience](https://docs.whop.com/fr/api-reference/audiences/create-audience.md)
>
> Importez une liste de clients à cibler ou à exclure.

> [card] [Référence Ads](https://docs.whop.com/fr/api-reference/ad-campaigns/ad-campaign)
>
> Tous les endpoints publicitaires, avec un playground.


## Related topics

- [Vue d'ensemble de l'API Ads](https://docs.whop.com/fr/api-reference/ads/overview.md)
- [AdsAgreementElement](https://docs.whop.com/fr/elements/latest/ads/ads-agreement.md)
- [CampaignCreatorElement](https://docs.whop.com/fr/elements/latest/ads/campaign-creator.md)
