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

# API Ads

> Un Ad est l'unité créative individuelle diffusée par un groupe d'annonces. Il contient le texte, les ressources créatives et l'URL de destination d'une annonce.

Un Ad est l'unité créative individuelle diffusée par un [groupe d'annonces](https://docs.whop.com/fr/api-reference/ad-groups/ad-group). Il contient le texte, les ressources créatives et l'URL de destination d'une annonce.

Utilisez l'API Ads pour lister les annonces d'un compte, créer des annonces dans des groupes d'annonces, récupérer ou mettre à jour les détails créatifs, supprimer les annonces qui doivent cesser d'être diffusées, et mettre en pause ou reprendre la diffusion.

## Endpoints

| Endpoint | Requête |
| - | - |
| [List Ads](https://docs.whop.com/fr/api-reference/ads/list-ads.md) | GET `/ads` |
| [Retrieve an Ad](https://docs.whop.com/fr/api-reference/ads/retrieve-an-ad.md) | GET `/ads/{id}` |
| [Create an Ad](https://docs.whop.com/fr/api-reference/ads/create-an-ad.md) | POST `/ads` |
| [Duplicate an Ad](https://docs.whop.com/fr/api-reference/ads/duplicate-an-ad.md) | POST `/ads/{id}/duplicate` |
| [Pause an Ad](https://docs.whop.com/fr/api-reference/ads/pause-an-ad.md) | POST `/ads/{id}/pause` |
| [Unpause an Ad](https://docs.whop.com/fr/api-reference/ads/unpause-an-ad.md) | POST `/ads/{id}/unpause` |
| [Update an Ad](https://docs.whop.com/fr/api-reference/ads/update-an-ad.md) | PATCH `/ads/{id}` |
| [Delete an Ad](https://docs.whop.com/fr/api-reference/ads/delete-an-ad.md) | DELETE `/ads/{id}` |

## Attributs

**id** `string` *required*

Identifiant unique de l'annonce, préfixé par `ad_`.

**ad\_campaign** `object` *required*

La campagne publicitaire à laquelle appartient cette annonce.

> [accordion] Propriétés
>
> **id** `string` *required*
>
> L'id de l'entité référencée.

**ad\_group** `object` *required*

Le groupe d'annonces auquel appartient cette annonce.

> [accordion] Propriétés
>
> **id** `string` *required*
>
> L'id de l'entité référencée.

**added\_to\_cart\_value** `number` *required*

Valeur en USD attribuée aux événements d'ajout au panier. Additionne la valeur envoyée avec chaque événement, normalisée en USD ; les événements sans valeur comptent pour 0.

**added\_to\_carts** `number` *required*

Événements d'ajout au panier attribués par le pixel Whop, au dernier clic.

**call\_to\_action** `string | null` *required*

Le bouton d'appel à l'action affiché sur l'annonce.

Options disponibles : `learn_more`, `shop_now`, `sign_up`, `subscribe`, `get_started`, `book_now`, `apply_now`, `contact_us`, `download`, `order_now`, `buy_now`, `get_quote`, `message_page`, `whatsapp_message`, `instagram_message`, `call_now`, `get_directions`, `send_updates`, `get_offer`, `watch_more`, `listen_now`, `play_game`, `open_link`, `no_button`, `get_offer_view`, `get_event_tickets`, `see_menu`, `request_time`, `event_rsvp`, `see_details`, `view_instagram_profile`, `donate_now`, `see_more`, `visit_site`

**click\_through\_rate** `number` *required*

Clics divisés par les impressions, entre 0 et 1.

**clicks** `number` *required*

Le nombre de clics.

**completed\_registration\_value** `number` *required*

Valeur en USD attribuée aux événements d'inscription terminée. Additionne la valeur envoyée avec chaque événement, normalisée en USD ; les événements sans valeur comptent pour 0.

**completed\_registrations** `number` *required*

Événements d'inscription terminée attribués par le pixel Whop, au dernier clic.

**contact\_value** `number` *required*

Valeur en USD attribuée aux événements de contact. Additionne la valeur envoyée avec chaque événement, normalisée en USD ; les événements sans valeur comptent pour 0.

**contacts** `number` *required*

Événements de contact attribués par le pixel Whop, au dernier clic.

**content\_review** `object` *required*

La vérification du contenu de cette annonce par Whop : si elle est terminée, les réseaux publicitaires pour lesquels l'annonce est recommandée, et les règles de contenu qu'elle enfreint.

> [accordion] Propriétés
>
> **networks** `object[]` *required*
>
> Indique si chaque réseau peut diffuser l'annonce. Vide jusqu'à la fin de la vérification.
>
> > [accordion] Propriétés
> >
> > **recommended** `boolean` *required*
> >
> > Indique si l'annonce respecte la politique de contenu de Whop et celle de ce réseau.
> >
> > **title** `string` *required*
> >
> > Le réseau. `whop` correspond à la politique de contenu propre à Whop, que tous les autres réseaux exigent également.
> >
> > Options disponibles : `whop`, `meta`, `tiktok`, `google`
>
> **status** `string` *required*
>
> `reviewed` une fois la vérification du contenu par Whop terminée, `in_review` pendant son exécution, `not_reviewed` lorsqu'elle n'a jamais eu lieu.
>
> Options disponibles : `reviewed`, `in_review`, `not_reviewed`
>
> **tags** `object[]` *required*
>
> Toutes les règles que la vérification a identifiées comme enfreintes par l'annonce, sur n'importe quel réseau. Vide lorsqu'elle n'en enfreint aucune ou que la vérification n'est pas terminée.
>
> > [accordion] Propriétés
> >
> > **message** `string` *required*
> >
> > Les éléments de preuve enregistrés par la vérification pour cette règle.
> >
> > **title** `string` *required*
> >
> > La règle que la vérification du contenu par Whop a identifiée comme enfreinte par l'annonce.

**cost\_per\_added\_to\_cart** `number | null` *required*

Dépenses divisées par les événements d'ajout au panier attribués ; null lorsqu'ils ne sont pas l'objectif et qu'aucun n'est attribué.

**cost\_per\_click** `number` *required*

Dépenses divisées par les clics ; 0 en l'absence de clics.

**cost\_per\_completed\_registration** `number | null` *required*

Dépenses divisées par les événements d'inscription terminée attribués ; null lorsqu'ils ne sont pas l'objectif et qu'aucun n'est attribué.

**cost\_per\_contact** `number | null` *required*

Dépenses divisées par les événements de contact attribués ; null lorsque les contacts ne sont pas l'objectif et qu'aucun n'est attribué.

**cost\_per\_lead** `number | null` *required*

Dépenses divisées par les leads attribués ; null lorsque les leads ne sont pas un objectif et qu'aucun n'est attribué.

**cost\_per\_mille** `number` *required*

Dépenses pour 1 000 impressions ; 0 en l'absence d'impressions.

**cost\_per\_purchase** `number | null` *required*

Dépenses divisées par les achats attribués ; null lorsque les achats ne sont pas un objectif et qu'aucun n'est attribué.

**cost\_per\_result** `number | null` *required*

Dépenses divisées par les résultats attribués par le pixel Whop ; null lorsque rien d'attribuable par Whop n'est optimisé.

**cost\_per\_schedule** `number | null` *required*

Dépenses divisées par les événements de prise de rendez-vous attribués ; null lorsque les rendez-vous ne sont pas l'objectif et qu'aucun n'est attribué.

**cost\_per\_submitted\_application** `number | null` *required*

Dépenses divisées par les événements de soumission de candidature attribués ; null lorsqu'ils ne sont pas l'objectif et qu'aucun n'est attribué.

**cost\_per\_unique\_click** `number | null` *required*

Dépenses divisées par les clics uniques ; null en l'absence de clics uniques.

**cost\_per\_viewed\_content** `number | null` *required*

Dépenses divisées par les événements de consultation de contenu attribués ; null lorsqu'ils ne sont pas l'objectif et qu'aucun n'est attribué.

**created\_at** `string` *required*

Date de création de l'annonce, sous forme d'horodatage ISO 8601.

**creatives** `object[]` *required*

Les ressources créatives utilisées par cette annonce. La ressource d'origine a un format null ; les entrées square, vertical et horizontal sont des variantes propres à un emplacement. Une annonce carrousel renvoie une entrée de format null par pièce jointe, dans l'ordre.

> [accordion] Propriétés
>
> **id** `string` *required*
>
> L'id de fichier de la pièce jointe créative.
>
> **crop** `object | null` *required*
>
> La fenêtre de recadrage enregistrée pour cette création, en pixels de l'image source. Null pour la ressource d'origine ou pour un format qui n'a pas été recadré.
>
> > [accordion] Propriétés
> >
> > **height** `number` *required*
> >
> > Hauteur de la fenêtre de recadrage en pixels source.
> >
> > **width** `number` *required*
> >
> > Largeur de la fenêtre de recadrage en pixels source.
> >
> > **x** `number` *required*
> >
> > Bord gauche de la fenêtre de recadrage en pixels source.
> >
> > **y** `number` *required*
> >
> > Bord supérieur de la fenêtre de recadrage en pixels source.
>
> **format** `string | null` *required*
>
> La variante d'emplacement couverte par cette ressource, ou null pour la ressource d'origine.
>
> Options disponibles : `square`, `vertical`, `horizontal`
>
> **language** `string | null` *required*
>
> Toujours `null`. Les traductions ne sont plus disponibles.
>
> **media\_type** `string | null` *required*
>
> Le type de ressource, image ou vidéo.
>
> **url** `string | null` *required*
>
> URL CDN de la ressource.

**custom\_conversions** `number` *required*

Événements de conversion personnalisés (définis par le marchand) attribués par le pixel Whop, au dernier clic, tous noms d'événements personnalisés confondus.

**custom\_event\_counts** `object` *required*

Conversions personnalisées attribuées par le pixel Whop, indexées par le nom de votre événement, avec leur nombre au dernier clic comme valeur. Vide lorsqu'aucun événement personnalisé nommé n'est attribué. Les événements personnalisés déclenchés sans nom sont comptés dans custom\_conversions mais omis ici, de sorte que la somme de ces valeurs est au plus égale à custom\_conversions.

**custom\_event\_values** `object` *required*

Valeur de conversion attribuée à chaque événement personnalisé, indexée par nom d'événement comme custom\_event\_counts. Additionne la valeur transmise à whop.track, normalisée en USD ; les événements déclenchés sans valeur comptent pour 0.

**delivery\_status** `string` *required*

Indique si l'annonce est actuellement diffusée et, sinon, pourquoi. Lorsque plusieurs états s'appliquent simultanément, celui ayant la priorité la plus élevée est renvoyé.

Options disponibles : `rejected`, `in_review`, `draft`, `campaign_paused`, `paused`, `processing`, `revise_content`, `issues`, `scheduled`, `learning`, `active`

**descriptions** `object[]` *required*

La description affichée sur l'annonce.

> [accordion] Propriétés
>
> **language** `string | null` *required*
>
> Toujours `null`. Les traductions ne sont plus disponibles.
>
> **text** `string` *required*
>
> Le texte affiché aux spectateurs.

**frequency** `number | null` *required*

Impressions divisées par la couverture.

**headlines** `object[]` *required*

Le titre affiché sur l'annonce.

> [accordion] Propriétés
>
> **language** `string | null` *required*
>
> Toujours `null`. Les traductions ne sont plus disponibles.
>
> **text** `string` *required*
>
> Le texte affiché aux spectateurs.

**impressions** `number` *required*

Le nombre d'impressions.

**issues** `object[]` *required*

Problèmes ouverts affectant cette annonce. Vide lorsqu'il n'y en a aucun.

> [accordion] Propriétés
>
> **id** `string` *required*
>
> Identifiant unique du problème.
>
> **category** `string` *required*
>
> Le type de problème : une information sur la diffusion, un avertissement ou une erreur nécessitant une action.
>
> Options disponibles : `information`, `warning`, `error`
>
> **message** `string` *required*
>
> Une description du problème et de la manière de le résoudre.
>
> **resource\_id** `string | null` *required*
>
> L'ID de la campagne, du groupe d'annonces ou de l'annonce auquel le problème est rattaché.
>
> **resource\_type** `string` *required*
>
> Le type de ressource auquel le problème est rattaché.
>
> Options disponibles : `ad_campaign`, `ad_group`, `ad`
>
> **title** `string` *required*
>
> Un titre court du problème, destiné au créateur : la règle citée par un rejet lors de la vérification du contenu, ou un libellé générique.

**lead\_value** `number` *required*

Valeur en USD attribuée aux événements de lead. Additionne la valeur envoyée avec chaque événement, normalisée en USD ; les événements sans valeur comptent pour 0.

**leads** `number` *required*

Leads attribués par le pixel Whop, au dernier clic.

**link\_clicks** `number` *required*

Pages vues sur votre destination par les personnes ayant cliqué sur l'annonce, enregistrées par le pixel Whop. Comptabilisées de la même manière sur toutes les plateformes publicitaires.

**primary\_texts** `object[]` *required*

Le texte principal affiché dans le corps de l'annonce. Plusieurs entrées créent des variantes de texte.

> [accordion] Propriétés
>
> **language** `string | null` *required*
>
> Toujours `null`. Les traductions ne sont plus disponibles.
>
> **text** `string` *required*
>
> Le texte affiché aux spectateurs.

**purchase\_value** `number` *required*

Valeur en USD des achats attribués par le pixel.

**purchases** `number` *required*

Achats attribués par le pixel Whop, au dernier clic.

**reach** `number` *required*

Le nombre de personnes uniques ayant vu ceci.

**result\_event** `string | null` *required*

L'événement de conversion du pixel Whop dont le nombre attribué représente les résultats : l'objectif d'optimisation, ou l'événement attribué au volume le plus élevé pour les campagnes budgétées par groupe d'annonces. Null lorsque l'objectif n'est pas un événement attribué par Whop.

Options disponibles : `purchase`, `lead`, `schedule`, `submit_application`, `contact`, `complete_registration`, `view_content`, `add_to_cart`, `custom`, `messaging_conversation`

**result\_event\_name** `string | null` *required*

Le nom d'événement défini par le marchand lorsque result\_event vaut custom ; null pour les événements standard.

**results** `number | null` *required*

Le nombre attribué par le pixel Whop derrière result\_event. Lorsque les groupes d'annonces d'une campagne optimisent des objectifs différents, il n'y a pas de result\_event unique (il vaut null), et cette valeur correspond alors à la somme des résultats attribués propres à chaque groupe d'annonces. Null lorsque rien d'attribuable par Whop n'est optimisé.

**return\_on\_ad\_spend** `number` *required*

Valeur des achats divisée par les dépenses, toutes deux en USD (un ratio indépendant de la devise) ; 0 en l'absence de dépenses.

**schedule\_value** `number` *required*

Valeur en USD attribuée aux événements de prise de rendez-vous. Additionne la valeur envoyée avec chaque événement, normalisée en USD ; les événements sans valeur comptent pour 0.

**schedules** `number` *required*

Événements de prise de rendez-vous attribués par le pixel Whop, au dernier clic.

**spend** `number` *required*

Le montant facturé, en spend\_currency.

**spend\_currency** `string | null` *required*

Le code de devise ISO 4217 de toutes les métriques monétaires.

**status** `string` *required*

Indique si l'annonce est activée. `active` et `paused` sont définis par vous ; `in_review` et `rejected` proviennent de la vérification publicitaire.

Options disponibles : `active`, `paused`, `in_review`, `rejected`

**submitted\_application\_value** `number` *required*

Valeur en USD attribuée aux événements de soumission de candidature. Additionne la valeur envoyée avec chaque événement, normalisée en USD ; les événements sans valeur comptent pour 0.

**submitted\_applications** `number` *required*

Événements de soumission de candidature attribués par le pixel Whop, au dernier clic.

**title** `string | null` *required*

Titre d'affichage de l'annonce.

**unique\_click\_through\_rate** `number | null` *required*

Clics uniques divisés par les impressions, entre 0 et 1.

**unique\_clicks** `number` *required*

Personnes ayant cliqué, signalées par le pixel Whop, comptées une seule fois par personne.

**updated\_at** `string` *required*

Date de dernière mise à jour de l'annonce, sous forme d'horodatage ISO 8601.

**url** `string | null` *required*

L'URL vers laquelle renvoie l'annonce, sans sa chaîne de requête. Les paramètres doivent figurer dans `url_parameters` ; ceux que vous envoyez dans `url` y sont déplacés.

**url\_parameters** `object` *required*

Paramètres de requête ajoutés à `url`, indexés par nom. Les paramètres d'attribution des clics de Whop sont réservés.

**viewed\_content\_value** `number` *required*

Valeur en USD attribuée aux événements de consultation de contenu. Additionne la valeur envoyée avec chaque événement, normalisée en USD ; les événements sans valeur comptent pour 0.

**viewed\_contents** `number` *required*

Événements de consultation de contenu attribués par le pixel Whop, au dernier clic.

```json Ad theme={null}
{
	"id": "ad_xxxxxxxxxxxxx",
	"ad_campaign": {
		"id": "adcamp_xxxxxxxxxx"
	},
	"ad_group": {
		"id": "adgrp_xxxxxxxxxxx"
	},
	"added_to_cart_value": 540,
	"added_to_carts": 18,
	"call_to_action": "shop_now",
	"click_through_rate": 0.034,
	"clicks": 420,
	"completed_registration_value": 0,
	"completed_registrations": 12,
	"contact_value": 0,
	"contacts": 8,
	"content_review": {
		"status": "reviewed",
		"networks": [
			{
				"title": "whop",
				"recommended": true
			},
			{
				"title": "meta",
				"recommended": true
			},
			{
				"title": "tiktok",
				"recommended": false
			},
			{
				"title": "google",
				"recommended": true
			}
		],
		"tags": [
			{
				"title": "Unrealistic earnings or investment claims",
				"message": "The ad promises viewers they will make $10,000 a month."
			}
		]
	},
	"cost_per_added_to_cart": 7.22,
	"cost_per_click": 0.31,
	"cost_per_completed_registration": 10.83,
	"cost_per_contact": 16.25,
	"cost_per_lead": 9.29,
	"cost_per_mille": 14.5,
	"cost_per_purchase": 21.67,
	"cost_per_result": 21.67,
	"cost_per_schedule": null,
	"cost_per_submitted_application": null,
	"cost_per_unique_click": 0.37,
	"cost_per_viewed_content": 0.54,
	"created_at": "2026-06-01T12:00:00Z",
	"creatives": [
		{
			"id": "file_xxxxxxxxxxxx",
			"crop": {
				"height": 1080,
				"width": 1080,
				"x": 120,
				"y": 0
			},
			"format": "square",
			"media_type": "image",
			"url": "https://img.whop.com/file_xxxxxxxxxxxx.jpg",
			"language": null
		}
	],
	"custom_conversions": 4,
	"custom_event_counts": {
		"QualifiedCall": 3,
		"BookedDemo": 1
	},
	"custom_event_values": {
		"QualifiedCall": 1500,
		"BookedDemo": 0
	},
	"delivery_status": "issues",
	"descriptions": [
		{
			"language": null,
			"text": "Limited spots available this week."
		}
	],
	"frequency": 1.8,
	"headlines": [
		{
			"language": null,
			"text": "Join Pickaxe Pro"
		}
	],
	"impressions": 9000,
	"issues": [
		{
			"id": "adiss_xxxxxxxxxxx",
			"category": "error",
			"title": "Ad issue",
			"message": "The ad's creative violates the ad network's policies. Edit the creative and resubmit for review.",
			"resource_id": "ad_xxxxxxxxxxxxx",
			"resource_type": "ad"
		}
	],
	"lead_value": 700,
	"leads": 14,
	"link_clicks": 336,
	"primary_texts": [
		{
			"language": null,
			"text": "Build sharper trading habits with daily lessons."
		}
	],
	"purchase_value": 1820,
	"purchases": 6,
	"reach": 5000,
	"result_event": "purchase",
	"result_event_name": null,
	"results": 6,
	"return_on_ad_spend": 14,
	"schedule_value": 0,
	"schedules": 0,
	"spend": 130,
	"spend_currency": "usd",
	"status": "active",
	"submitted_application_value": 0,
	"submitted_applications": 0,
	"title": "Pickaxe Pro launch ad",
	"unique_click_through_rate": 0.028,
	"unique_clicks": 350,
	"updated_at": "2026-06-02T12:00:00Z",
	"url": "https://whop.com/pickaxe",
	"url_parameters": {
		"utm_campaign": "pickaxe-launch"
	},
	"viewed_content_value": 0,
	"viewed_contents": 240
}
```


## Related topics

- [Vue d'ensemble de l'API Ads](https://docs.whop.com/fr/api-reference/ads/overview.md)
- [List Ads](https://docs.whop.com/fr/api-reference/ads/list-ads.md)
- [API Accounts](https://docs.whop.com/fr/api-reference/accounts/account.md)
