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

> Une variante est une configuration achetable d'un produit.

Elle contrôle le prix, la fréquence de facturation, le stock, le SKU, les attributs, le comportement fiscal, les champs du checkout et la visibilité à l'achat. Les ID de variante restent préfixés par `plan_`.

Utilisez l'API Variantes pour créer des variantes de produits, lister les variantes existantes, récupérer ou mettre à jour la configuration d'une variante, calculer la taxe pour le checkout, et supprimer les variantes qui ne doivent plus être proposées.

## Endpoints

| Endpoint | Requête |
| - | - |
| [Lister les variantes](https://docs.whop.com/fr/api-reference/variants/list-variants.md) | GET `/variants` |
| [Récupérer une variante](https://docs.whop.com/fr/api-reference/variants/retrieve-variant.md) | GET `/variants/{id}` |
| [Créer une variante](https://docs.whop.com/fr/api-reference/variants/create-variant.md) | POST `/variants` |
| [Mettre à jour une variante](https://docs.whop.com/fr/api-reference/variants/update-variant.md) | PATCH `/variants/{id}` |
| [Supprimer une variante](https://docs.whop.com/fr/api-reference/variants/delete-variant.md) | DELETE `/variants/{id}` |

## Attributs

**id** `string` *required*

ID de la variante, préfixé par `plan_`.

**account** `object | null` *required*

Compte qui vend cette variante ; `null` pour les variantes de facture autonomes.

> [accordion] Propriétés
>
> **id** `string` *required*
>
> ID du compte, préfixé par `biz_`.
>
> **title** `string` *required*
>
> Nom d'affichage du compte.

**adaptive\_pricing\_enabled** `boolean` *required*

Indique si la tarification adaptative est activée pour cette variante. Paramètre brut — ne vérifie pas la compatibilité avec le processeur ni les feature flags.

**allow\_multiple\_quantity** `boolean` *required*

Indique si plusieurs unités peuvent être achetées dans une commande. Les variantes à renouvellement ne peuvent pas l'activer. Lorsque `false`, les checkouts, paniers et factures refusent une quantité supérieure à 1.

**attributes** `object | null` *required*

Valeurs d'attributs qui distinguent cette variante au sein de son produit, sous forme de correspondance entre nom d'attribut et valeur, par exemple `\{"color": "Blue", "size": "Large"}`. Les noms sont des identifiants en snake\_case et sont renvoyés par ordre alphabétique. Chaque variante dotée d'attributs sur un produit porte les mêmes noms d'attributs et un ensemble distinct de valeurs ; le produit liste l'ensemble complet des options dans `variant_attributes`. `null` lorsque la variante n'a pas d'attributs.

**billing\_period** `number | null` *required*

Nombre de jours entre les prélèvements récurrents, par exemple 30 pour un abonnement mensuel ou 365 pour un abonnement annuel. `null` pour les variantes à paiement unique.

**billing\_type** `string` *required*

Modèle de facturation de cette variante.

Options disponibles : `renewal`, `one_time`

**cancel\_discount\_intervals** `number | null` *required*

Durée de la remise d'annulation : `0` pour toujours, `1` pour le prochain paiement uniquement, ou un nombre de mois calendaires à compter de son acceptation par le client. `null` lorsqu'aucune n'est proposée ou que l'acteur ne dispose pas de la portée `plan:basic:read`.

**cancel\_discount\_percentage** `number | null` *required*

Remise d'annulation sous forme de pourcentage entier. `null` lorsqu'aucune n'est proposée ou que l'acteur ne dispose pas de la portée `plan:basic:read`.

**checkout\_styling** `object | null` *required*

Style du checkout au niveau de la variante (`background_color`, `button_color`, `font_family`, `border_style`) ; `null` hérite de la valeur par défaut du compte.

**collect\_tax** `boolean` *required*

Indique si la taxe est perçue sur les achats de cette variante, selon la configuration fiscale du compte.

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

Date de création de la variante, sous forme d'horodatage ISO 8601.

**currency** `string` *required*

Code ISO 4217 à trois lettres, en minuscules, de la devise dans laquelle tous les prix de cette variante sont exprimés : la devise propre de la variante, ou la `presentment_currency` demandée lors de la lecture lorsque la variante peut y être convertie.

**custom\_fields** `object[]` *required*

Champs de saisie personnalisés collectés sur le formulaire du checkout.

> [accordion] Propriétés
>
> **id** `string` *required*
>
> ID du champ personnalisé, préfixé par `field_`.
>
> **field\_type** `string` *required*
>
> Type de saisie du champ personnalisé.
>
> Options disponibles : `text`
>
> **name** `string` *required*
>
> Libellé du champ affiché au client lors du checkout.
>
> **order** `number` *required*
>
> Position du champ sur le formulaire du checkout.
>
> **placeholder** `string | null` *required*
>
> Texte indicatif affiché dans le champ vide. `null` si aucun n'est défini.
>
> **required** `boolean` *required*
>
> Indique si le client doit remplir ce champ pour finaliser le checkout.

**deletable** `boolean | null` *required*

Indique si la variante peut être supprimée (elle n'a ni adhésions ni entrées de liste d'attente). `null` sauf si l'acteur dispose de la portée `plan:basic:read` sur le compte de la variante.

**description** `string | null` *required*

Description de la variante visible par le client. 1000 caractères maximum. `null` si aucune description n'est définie.

**effective\_payment\_method\_configuration** `object | null` *required*

La configuration régissant un checkout pour cette variante, résolue à travers chaque niveau (celui de la variante et celui du compte) — la forme que porte le `payment_method_configuration` d'une session. Appliquez-la au catalogue des types de moyens de paiement pour obtenir l'ensemble proposable. `null` signifie les valeurs par défaut de la plateforme ; `payment_method_configuration` reste la surcharge modifiable propre à la variante.

> [accordion] Propriétés
>
> **disabled** `string[]` *required*
>
> Moyens de paiement que ce checkout exclut, même lorsque les valeurs par défaut les proposeraient.
>
> **enabled** `string[]` *required*
>
> Moyens de paiement que ce checkout propose en plus de ceux fournis par les valeurs par défaut.
>
> **include\_platform\_defaults** `boolean` *required*
>
> Indique si l'ensemble par défaut de Whop sert de point de départ. Lorsque `false`, seuls les moyens de `enabled` sont proposés.

**expiration\_days** `number | null` *required*

Durée d'accès en jours pour les variantes à expiration, par exemple 365 pour un pass d'un an. `null` pour les variantes sans expiration.

**formatted\_price** `string` *required*

Prix lisible destiné à l'affichage (devise + intervalle) en `currency`, par exemple « \$10 / month ».

**image** `object | null` *required*

Image du niveau tarifaire (`url`, `blurhash`) affichée sur la page produit ; `null` lorsqu'aucune image n'est définie.

**initial\_price** `number` *required*

Prix d'achat initial, en `currency`.

**initial\_price\_due** `object` *required*

Total prélevé au checkout pour une unité, avant codes promo et taxes : `initial_price` plus le premier `renewal_price` pour les variantes récurrentes, ou `initial_price` seul lorsqu'un essai gratuit s'applique. L'essai ne s'applique pas lorsque l'utilisateur qui consulte en a déjà utilisé un pour cette variante. Exprimé en `currency`.

> [accordion] Propriétés
>
> **amount** `string` *required*
>
> Le montant en unités principales, sous forme de chaîne décimale exacte. Par exemple, `"10.00"` correspond à dix dollars. Il s'agit d'une chaîne afin qu'aucun nombre à virgule flottante ne l'arrondisse pendant le transfert.
>
> **currency** `string` *required*
>
> Code de devise ISO 4217 à trois lettres, en minuscules.
>
> **decimals** `integer` *required*
>
> Le nombre de décimales du montant. Il s'agit de la précision avec laquelle le prélèvement lui-même est effectué.
>
> **display\_decimals** `integer` *required*
>
> Le nombre de décimales à AFFICHER. Généralement égal à `decimals`, mais délibérément pas toujours : le COP est prélevé en centavos mais exprimé en pesos entiers, il vaut donc `2` et `0`. Utilisez cette valeur pour formater le nombre selon votre propre locale.

**internal\_notes** `string | null` *required*

Notes privées non affichées aux clients. `null` sauf si l'acteur dispose de la portée `plan:basic:read` sur le compte de la variante.

**invoice** `object | null` *required*

Facture pour laquelle cette variante a été générée ; `null` sauf si elle a été créée pour une facture.

**member\_count** `number | null` *required*

Adhésions actives via cette variante. `null` sauf si l'acteur dispose de la portée `plan:basic:read` sur le compte de la variante.

**metadata** `object | null` *required*

Paires clé-valeur personnalisées stockées sur la variante. Incluses dans les payloads de webhook pour les événements de paiement et d'adhésion. 50 clés maximum, 100 caractères par clé, 500 caractères par valeur. Les clés réservées `custom_cta` et `custom_cta_url`, lorsqu'elles sont définies, remplacent l'appel à l'action du checkout du produit pour cette variante.

**offer\_cancel\_discount** `boolean | null` *required*

Indique si une remise d'annulation est proposée. `null` sauf si l'acteur dispose de la portée `plan:basic:read` sur le compte de la variante.

**payment\_method\_configuration** `object | null` *required*

Configuration des moyens de paiement (`enabled`, `disabled`, `include_platform_defaults`) ; `null` lorsque la variante utilise les paramètres par défaut.

**product** `object | null` *required*

Produit auquel appartient cette variante ; `null` pour les variantes autonomes.

**purchase\_url** `string` *required*

URL où les clients peuvent acheter directement cette variante.

**redirect\_url** `string | null` *required*

Page vers laquelle le client est redirigé après avoir payé cette variante. `null` lorsqu'aucune n'est définie, ou sauf si l'acteur dispose de la portée `plan:basic:read` sur le compte de la variante.

**release\_method** `string` *required*

Méthode de vente de cette variante.

Options disponibles : `buy_now`, `waitlist`

**renewal\_price** `number` *required*

Prix récurrent prélevé à chaque période de facturation, en `currency`.

**sku** `string | null` *required*

Unité de gestion de stock (SKU), texte libre défini par le vendeur (par exemple `TSHIRT-LARGE-BLUE`). Son unicité n'est pas imposée. `null` lorsqu'il n'est pas défini.

**split\_pay\_required\_payments** `number | null` *required*

Paiements échelonnés requis avant la mise en pause de l'abonnement. Doit être supérieur à 1. `null` si le paiement fractionné n'est pas configuré.

**stock** `number | null` *required*

Unités disponibles à l'achat. `null` sauf si l'acteur dispose de la portée `plan:basic:read` sur le compte de la variante.

**strike\_through\_initial\_price** `number | null` *required*

Prix initial d'origine affiché barré, en `currency`. `null` lorsqu'aucun prix barré n'est défini.

**strike\_through\_renewal\_price** `number | null` *required*

Prix de renouvellement d'origine affiché barré, en `currency`. `null` lorsqu'aucun prix barré n'est défini.

**tax\_type** `string` *required*

Mode de gestion de la taxe pour cette variante, y compris si la taxe est incluse dans le prix, ajoutée au checkout ou non configurée.

Options disponibles : `inclusive`, `exclusive`, `unspecified`

**three\_ds\_level** `string | null` *required*

Comportement 3D Secure pour les paiements par carte en session pris en charge. `mandate_challenge` exige un challenge 3DS avant le traitement du paiement ; `mandate_if_required` impose un challenge uniquement lorsque le processeur de paiement l'exige ; `frictionless_if_required` utilise le flux 3DS frictionless habituel. Les paiements de 1 000 \$ ou plus utilisent `mandate_if_required` sauf si `mandate_challenge` est sélectionné. Les exigences de gestion des risques et de récupération de l'authentification peuvent prévaloir sur cette préférence. `null` hérite de la valeur par défaut du compte.

Options disponibles : `mandate_challenge`, `mandate_if_required`, `frictionless_if_required`

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

Nom d'affichage de la variante présenté aux clients. 30 caractères maximum. Une variante créée sans nom prend par défaut ses valeurs d'attributs jointes par `/`. `null` si aucun titre n'a été défini.

**trial\_period\_days** `number | null` *required*

Jours d'essai gratuit avant le premier prélèvement de renouvellement. `null` si aucun essai n'est configuré ou si l'utilisateur a déjà utilisé un essai pour cette variante.

**unlimited\_stock** `boolean` *required*

Indique si la variante a un stock illimité. Lorsque `true`, le champ `stock` est ignoré ; les variantes avec liste d'attente indiquent toujours `true`.

**unpaid\_invoice\_count** `integer | null` *required*

Nombre de factures émises pour cette variante qui ne sont ni payées ni annulées. Tant qu'il est supérieur à `0`, vous ne pouvez pas modifier les prix, la période de facturation, l'essai, le nombre de paiements, la devise ou le type de facturation de la variante. `null` sauf si l'acteur dispose de la portée `plan:basic:read` sur le compte de la variante.

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

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

**visibility** `string` *required*

Contrôle où cette variante peut être vue. Lorsque `hidden`, la variante n'est accessible que via son lien direct.

Options disponibles : `visible`, `hidden`, `archived`, `quick_link`

```json Variant theme={null}
{
	"id": "plan_xxxxxxxxxxxxx",
	"account": {
		"id": "biz_xxxxxxxxxxxxxx",
		"title": "Pickaxe"
	},
	"adaptive_pricing_enabled": true,
	"allow_multiple_quantity": false,
	"attributes": {
		"seats": "5",
		"tier": "Pro"
	},
	"billing_period": 30,
	"cancel_discount_intervals": null,
	"cancel_discount_percentage": null,
	"checkout_styling": null,
	"collect_tax": true,
	"created_at": "2023-12-01T05:00:00.401Z",
	"currency": "usd",
	"custom_fields": [
		{
			"id": "cusf_xxxxxxxxxxxx",
			"field_type": "text",
			"name": "Discord username",
			"order": 0,
			"placeholder": "e.g. pickaxe_user",
			"required": true
		}
	],
	"deletable": false,
	"description": "Monthly access to Pickaxe Analytics.",
	"expiration_days": null,
	"formatted_price": "$29.00 / month",
	"image": null,
	"initial_price": 29,
	"internal_notes": "Standard monthly variant",
	"redirect_url": null,
	"invoice": null,
	"member_count": 42,
	"metadata": {
		"external_plan_id": "monthly",
		"custom_cta": "subscribe",
		"custom_cta_url": "https://example.com/wash-club"
	},
	"offer_cancel_discount": false,
	"payment_method_configuration": {
		"enabled": ["card"],
		"disabled": [],
		"include_platform_defaults": true
	},
	"effective_payment_method_configuration": {
		"enabled": ["card"],
		"disabled": [],
		"include_platform_defaults": true
	},
	"billing_type": "renewal",
	"product": {
		"id": "prod_xxxxxxxxxxxxx",
		"title": "Pickaxe Analytics"
	},
	"purchase_url": "https://whop.com/pickaxe-analytics/checkout/plan_xxxxxxxxxxxxx",
	"release_method": "buy_now",
	"renewal_price": 29,
	"initial_price_due": {
		"currency": "usd",
		"amount": "29.00",
		"decimals": 2,
		"display_decimals": 2
	},
	"sku": "PICKAXE-PRO-5-MONTHLY",
	"split_pay_required_payments": null,
	"stock": null,
	"strike_through_initial_price": null,
	"strike_through_renewal_price": null,
	"tax_type": "exclusive",
	"three_ds_level": "frictionless_if_required",
	"title": "Pro / 5 seats",
	"trial_period_days": 7,
	"unlimited_stock": true,
	"unpaid_invoice_count": 0,
	"updated_at": "2023-12-01T05:00:00.401Z",
	"visibility": "visible"
}
```


## Related topics

- [Variantes](https://docs.whop.com/fr/api-reference/legacy/variants/variant.md)
- [API Payments](https://docs.whop.com/fr/api-reference/payments/payment.md)
- [API Memberships](https://docs.whop.com/fr/api-reference/memberships/membership.md)
