> ## 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 de Variants

> Una Variant es una configuración comprable de un producto.

Controla el precio, la cadencia de facturación, el stock, el SKU, los atributos, el comportamiento fiscal, los campos del checkout y la visibilidad de compra. Los IDs de variante siguen teniendo el prefijo `plan_`.

Usa la API de Variants para crear variantes de productos, listar las variantes existentes, obtener o actualizar la configuración de una variante, calcular impuestos para el checkout y eliminar las variantes que ya no deban ofrecerse.

## Endpoints

| Endpoint | Solicitud |
| - | - |
| [Listar Variants](https://docs.whop.com/es/api-reference/variants/list-variants.md) | GET `/variants` |
| [Obtener Variant](https://docs.whop.com/es/api-reference/variants/retrieve-variant.md) | GET `/variants/{id}` |
| [Crear Variant](https://docs.whop.com/es/api-reference/variants/create-variant.md) | POST `/variants` |
| [Actualizar Variant](https://docs.whop.com/es/api-reference/variants/update-variant.md) | PATCH `/variants/{id}` |
| [Eliminar Variant](https://docs.whop.com/es/api-reference/variants/delete-variant.md) | DELETE `/variants/{id}` |

## Atributos

**id** `string` *required*

ID de la variante, con el prefijo `plan_`.

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

Cuenta que vende esta variante; `null` para variantes de factura independientes.

> [accordion] Propiedades
>
> **id** `string` *required*
>
> ID de la cuenta, con el prefijo `biz_`.
>
> **title** `string` *required*
>
> Nombre visible de la cuenta.

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

Si los precios adaptativos están habilitados para esta variante. Configuración sin procesar: no comprueba la compatibilidad del procesador ni los feature flags.

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

Si se puede comprar más de una unidad en un pedido. Las variantes de renovación no pueden habilitarlo. Cuando es `false`, los checkouts, carritos y facturas rechazan una cantidad superior a 1.

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

Valores de atributos que distinguen esta variante dentro de su producto, como un mapa de nombre de atributo a valor, p. ej. `\{"color": "Blue", "size": "Large"}`. Los nombres son identificadores en snake\_case y se devuelven en orden alfabético. Todas las variantes con atributos de un producto tienen los mismos nombres de atributo y un conjunto distinto de valores; el producto lista el conjunto completo de opciones como `variant_attributes`. `null` cuando la variante no tiene atributos.

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

Número de días entre cargos recurrentes, como 30 para mensual o 365 para anual. `null` para variantes de pago único.

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

Modelo de facturación de esta variante.

Opciones disponibles: `renewal`, `one_time`

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

Cuánto dura el descuento por cancelación: `0` para siempre, `1` solo el siguiente pago, o un número de meses naturales desde que el cliente lo acepta. `null` cuando no se ofrece ninguno o el actor no tiene el alcance `plan:basic:read`.

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

Descuento por cancelación como porcentaje entero. `null` cuando no se ofrece ninguno o el actor no tiene el alcance `plan:basic:read`.

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

Estilo del checkout a nivel de variante (`background_color`, `button_color`, `font_family`, `border_style`); `null` hereda el valor predeterminado de la cuenta.

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

Si se cobran impuestos en las compras de esta variante, según la configuración fiscal de la cuenta.

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

Cuándo se creó la variante, como marca de tiempo ISO 8601.

**currency** `string` *required*

Código ISO 4217 de tres letras, en minúsculas, de la divisa en la que se expresa cada precio de esta variante: la divisa propia de la variante, o la `presentment_currency` que pidió la lectura cuando la variante se puede convertir a ella.

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

Campos de entrada personalizados recopilados en el formulario del checkout.

> [accordion] Propiedades
>
> **id** `string` *required*
>
> ID del campo personalizado, con el prefijo `field_`.
>
> **field\_type** `string` *required*
>
> Tipo de entrada del campo personalizado.
>
> Opciones disponibles: `text`
>
> **name** `string` *required*
>
> Etiqueta del campo que se muestra al cliente en el checkout.
>
> **order** `number` *required*
>
> Posición del campo en el formulario del checkout.
>
> **placeholder** `string | null` *required*
>
> Texto de marcador de posición que se muestra en el campo vacío. `null` si no se ha establecido ninguno.
>
> **required** `boolean` *required*
>
> Si el cliente debe completar este campo para finalizar la compra.

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

Si la variante se puede eliminar (no tiene membresías ni entradas en la lista de espera). `null` a menos que el actor tenga el alcance `plan:basic:read` en la cuenta de la variante.

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

Descripción de la variante visible para el cliente. Máximo 1000 caracteres. `null` si no se ha establecido ninguna descripción.

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

La configuración que rige un checkout para esta variante, resuelta a través de todas las capas (la de la propia variante y la de la cuenta): la forma que tiene el `payment_method_configuration` de una sesión. Aplícala sobre el catálogo de tipos de métodos de pago para obtener el conjunto ofrecible. `null` significa los valores predeterminados de la plataforma; `payment_method_configuration` sigue siendo la anulación editable propia de la variante.

> [accordion] Propiedades
>
> **disabled** `string[]` *required*
>
> Métodos de pago que este checkout excluye, incluso cuando los valores predeterminados los ofrecerían.
>
> **enabled** `string[]` *required*
>
> Métodos de pago que este checkout ofrece además de los que proporcionan los valores predeterminados.
>
> **include\_platform\_defaults** `boolean` *required*
>
> Si el conjunto predeterminado de Whop es el punto de partida. Cuando es `false`, solo se ofrece `enabled`.

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

Duración del acceso en días para variantes con caducidad, como 365 para un pase de un año. `null` para variantes sin caducidad.

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

Precio legible para mostrar (divisa + intervalo) en `currency`, p. ej. "\$10 / month".

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

Imagen del nivel de precios (`url`, `blurhash`) que se muestra en la página del producto; `null` cuando no se ha establecido ninguna imagen.

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

Precio de la compra inicial, en `currency`.

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

Total cobrado en el checkout por una unidad, antes de códigos promocionales e impuestos: `initial_price` más el primer `renewal_price` para variantes recurrentes, o solo `initial_price` mientras se aplica una prueba gratuita. La prueba no se aplica cuando el usuario que la ve ya ha usado una para esta variante. Expresado en `currency`.

> [accordion] Propiedades
>
> **amount** `string` *required*
>
> El importe en unidades principales, como cadena decimal exacta. Por ejemplo, `"10.00"` son diez dólares. Es una cadena para que ningún número de coma flotante lo redondee en tránsito.
>
> **currency** `string` *required*
>
> Código de divisa ISO 4217 de tres letras, en minúsculas.
>
> **decimals** `integer` *required*
>
> Cuántos decimales tiene el importe. Es la precisión con la que se ejecuta el propio cargo.
>
> **display\_decimals** `integer` *required*
>
> Cuántos decimales se deben MOSTRAR. Normalmente es igual a `decimals`, y deliberadamente no siempre: COP se cobra en centavos pero se escribe en pesos enteros, por lo que es `2` y `0`. Usa esto para dar formato al número en tu propia configuración regional.

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

Notas privadas que no se muestran a los clientes. `null` a menos que el actor tenga el alcance `plan:basic:read` en la cuenta de la variante.

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

Factura para la que se generó esta variante; `null` a menos que se haya creado para una factura.

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

Membresías activas a través de esta variante. `null` a menos que el actor tenga el alcance `plan:basic:read` en la cuenta de la variante.

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

Pares clave-valor personalizados almacenados en la variante. Se incluyen en los payloads de webhook de los eventos de pagos y membresías. Máximo 50 claves, 100 caracteres por clave y 500 caracteres por valor. Las claves reservadas `custom_cta` y `custom_cta_url`, cuando se establecen, anulan la llamada a la acción del checkout del producto para esta variante.

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

Si se ofrece un descuento por cancelación. `null` a menos que el actor tenga el alcance `plan:basic:read` en la cuenta de la variante.

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

Configuración de métodos de pago (`enabled`, `disabled`, `include_platform_defaults`); `null` cuando la variante usa la configuración predeterminada.

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

Producto al que pertenece esta variante; `null` para variantes independientes.

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

URL donde los clientes pueden comprar esta variante directamente.

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

Adónde se envía al cliente después de pagar esta variante. `null` cuando no se ha establecido ninguna, o a menos que el actor tenga el alcance `plan:basic:read` en la cuenta de la variante.

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

Método de venta de esta variante.

Opciones disponibles: `buy_now`, `waitlist`

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

Precio recurrente cobrado en cada periodo de facturación, en `currency`.

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

Stock keeping unit (SKU), texto libre establecido por el vendedor (p. ej. `TSHIRT-LARGE-BLUE`). No se exige que sea único. `null` cuando no está establecido.

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

Pagos a plazos requeridos antes de que la suscripción se pause. Debe ser mayor que 1. `null` si el pago fraccionado no está configurado.

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

Unidades disponibles para la compra. `null` a menos que el actor tenga el alcance `plan:basic:read` en la cuenta de la variante.

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

Precio inicial original mostrado tachado, en `currency`. `null` cuando no se ha establecido un precio tachado.

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

Precio de renovación original mostrado tachado, en `currency`. `null` cuando no se ha establecido un precio tachado.

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

Cómo se gestionan los impuestos para esta variante, incluido si el impuesto está incluido en el precio, se añade en el checkout o no está configurado.

Opciones disponibles: `inclusive`, `exclusive`, `unspecified`

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

Comportamiento de 3D Secure para pagos con tarjeta compatibles en sesión. `mandate_challenge` exige un desafío 3DS antes de procesar el pago; `mandate_if_required` exige un desafío solo cuando el procesador de pagos lo requiere; `frictionless_if_required` usa el flujo 3DS sin fricción habitual. Los pagos de \$1,000 o más usan `mandate_if_required` a menos que se seleccione `mandate_challenge`. Los requisitos de riesgo y de recuperación de autenticación pueden anular la preferencia. `null` hereda el valor predeterminado de la cuenta.

Opciones disponibles: `mandate_challenge`, `mandate_if_required`, `frictionless_if_required`

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

Nombre visible de la variante que se muestra a los clientes. Máximo 30 caracteres. Una variante creada sin nombre usa por defecto sus valores de atributo unidos con `/`. `null` si no se ha establecido ningún título.

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

Días de prueba gratuita antes del primer cargo de renovación. `null` si no hay prueba configurada o el usuario ya ha usado una prueba para esta variante.

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

Si la variante tiene stock ilimitado. Cuando es `true`, se ignora el campo `stock`; las variantes de lista de espera siempre informan `true`.

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

Número de facturas emitidas para esta variante que no están pagadas ni anuladas. Mientras sea mayor que `0`, no puedes cambiar los precios, el periodo de facturación, la prueba, el número de pagos, la divisa ni el tipo de facturación de la variante. `null` a menos que el actor tenga el alcance `plan:basic:read` en la cuenta de la variante.

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

Cuándo se actualizó la variante por última vez, como marca de tiempo ISO 8601.

**visibility** `string` *required*

Controla dónde se puede ver esta variante. Cuando es `hidden`, la variante solo es accesible mediante su enlace directo.

Opciones 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

- [Versiones de la API](https://docs.whop.com/es/developer/api/versioning.md)
- [Inicio rápido de la API de Whop](https://docs.whop.com/es/developer/quickstart.md)
- [Estabilidad de la API](https://docs.whop.com/es/api-reference/stability.md)
