> ## 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 membresías

> Una Membership es la compra de una variante por parte de un cliente: la suscripción o concesión única que le da acceso a un producto.

Registra el estado de facturación (`active`, `trialing`, `past_due`, etc.), el periodo actual, las cancelaciones pendientes, los metadatos personalizados y la clave de licencia de software cuando el producto incluye licencias.

Usa la API de membresías para listar las membresías de una cuenta o las tuyas, recuperar una por ID o clave de licencia, invitar a un destinatario a unirse mediante una variante gratuita y gestionar el ciclo de vida: cancelar de inmediato o al final del periodo, revertir una cancelación programada, pausar y reanudar el cobro de pagos, ampliar o reactivar el acceso, aplicar un código promocional o un afiliado, cambiar la frecuencia de renovación, resincronizar el acceso, generar un enlace de transferencia y actualizar los metadatos.

> [!NOTE]
>
> Reemplaza el recurso heredado [Memberships](https://docs.whop.com/es/api-reference/memberships/membership). Las integraciones heredadas existentes siguen funcionando; consulta [Versiones de la API](https://docs.whop.com/es/developer/api/versioning.md) para conocer el compromiso de estabilidad.

## Endpoints

| Endpoint | Solicitud |
| - | - |
| [Listar membresías](https://docs.whop.com/es/api-reference/memberships/list-memberships.md) | GET `/memberships` |
| [Recuperar membresía](https://docs.whop.com/es/api-reference/memberships/retrieve-membership.md) | GET `/memberships/{id}` |
| [Aplicar código promocional a la membresía](https://docs.whop.com/es/api-reference/memberships/apply-promo-code-to-membership.md) | POST `/memberships/{id}/apply_promo_code` |
| [Asignar afiliado a la membresía](https://docs.whop.com/es/api-reference/memberships/assign-affiliate-to-membership.md) | POST `/memberships/{id}/assign_affiliate` |
| [Cancelar membresía](https://docs.whop.com/es/api-reference/memberships/cancel-membership.md) | POST `/memberships/{id}/cancel` |
| [Ampliar membresía](https://docs.whop.com/es/api-reference/memberships/extend-membership.md) | POST `/memberships/{id}/extend` |
| [Pausar membresía](https://docs.whop.com/es/api-reference/memberships/pause-membership.md) | POST `/memberships/{id}/pause` |
| [Reactivar membresía](https://docs.whop.com/es/api-reference/memberships/reactivate-membership.md) | POST `/memberships/{id}/reactivate` |
| [Reanudar membresía](https://docs.whop.com/es/api-reference/memberships/resume-membership.md) | POST `/memberships/{id}/resume` |
| [Resincronizar acceso de la membresía](https://docs.whop.com/es/api-reference/memberships/resync-membership-access.md) | POST `/memberships/{id}/resync_access` |
| [Transferir membresía](https://docs.whop.com/es/api-reference/memberships/transfer-membership.md) | POST `/memberships/{id}/transfer` |
| [Invitar a una membresía](https://docs.whop.com/es/api-reference/memberships/invite-to-a-membership.md) | POST `/memberships/invite` |
| [Actualizar membresía](https://docs.whop.com/es/api-reference/memberships/update-membership.md) | PATCH `/memberships/{id}` |

## Atributos

**id** `string` *required*

ID de la membresía, con el prefijo `mem_`.

**account** `object` *required*

La cuenta (vendedor) a la que pertenece esta membresía.

> [accordion] Propiedades
>
> **id** `string` *required*
>
> ID de la cuenta, con el prefijo `biz_`.
>
> **logo\_url** `string | null` *required*
>
> URL de la imagen del logotipo de la cuenta. `null` cuando la cuenta no ha establecido uno.
>
> **route** `string` *required*
>
> Identificador de ruta pública de la cuenta, utilizado en la ruta de la tienda `whop.com/\{route}`.
>
> **title** `string` *required*
>
> Nombre visible de la cuenta.

**affiliate** `object | null` *required*

La comisión de afiliado de la membresía. `null` sin un afiliado, sin `affiliate:basic:read` en la cuenta, y siempre en los webhooks.

> [accordion] Propiedades
>
> **id** `string` *required*
>
> ID del afiliado, con el prefijo `aff_`.
>
> **applies\_to\_payments** `string` *required*
>
> Si la comisión se paga solo en el primer pago de la membresía o en todos sus pagos.
>
> Opciones disponibles: `first_payment`, `all_payments`
>
> **commission\_amount** `object | null` *required*
>
> La comisión de tarifa fija en la moneda de la membresía, o `null` si es un porcentaje.
>
> > [accordion] Propiedades
> >
> > **amount** `string` *required*
> >
> > El importe en unidades principales, como una cadena decimal exacta. Por ejemplo, `"10.00"` son diez dólares. Es una cadena para que ningún número de punto flotante lo redondee durante la transmisión.
> >
> > **currency** `string` *required*
> >
> > Código de moneda 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 cobro.
> >
> > **display\_decimals** `integer` *required*
> >
> > Cuántos decimales MOSTRAR. Normalmente igual a `decimals`, y deliberadamente no siempre: COP se cobra en centavos pero se escribe en pesos enteros, así que es `2` y `0`. Usa este valor para dar formato al número en tu propia configuración regional.
>
> **commission\_percentage** `number | null` *required*
>
> La comisión porcentual en puntos porcentuales, así que `20` significa 20 %, o `null` si es una tarifa fija.
>
> **commission\_source** `string` *required*
>
> Cómo se estableció la tasa de comisión: `custom` para una tasa establecida para este afiliado, `member` para la tasa de afiliado de miembros del plan o producto, `global` para la tasa de afiliado global del producto, o `marketplace` para una referencia del marketplace de Whop.
>
> Opciones disponibles: `custom`, `member`, `marketplace`, `global`
>
> **commission\_type** `string` *required*
>
> Si la comisión es un porcentaje o una tarifa fija.
>
> Opciones disponibles: `flat_fee`, `percentage`
>
> **enabled** `boolean` *required*
>
> Si esta membresía paga comisiones de afiliado. `false` significa que el afiliado se mantiene en la membresía pero ya no se le paga.
>
> **user\_id** `string` *required*
>
> ID del usuario del afiliado, con el prefijo `user_`.

**billing\_period\_days** `integer | null` *required*

Número de días entre cobros recurrentes. `null` para membresías que no se renuevan o membresías con varios calendarios de renovación.

**cancel\_at\_period\_end** `boolean` *required*

Si la membresía está configurada para cancelarse cuando termine el periodo de facturación actual. Solo tiene sentido para variantes recurrentes.

**cancel\_option** `string | null` *required*

La categoría que eligió el miembro como motivo de la cancelación. `null` cuando no se eligió ninguna categoría.

Opciones disponibles: `too_expensive`, `switching`, `missing_features`, `technical_issues`, `bad_experience`, `unused`, `other`, `testing`

**canceled\_at** `string | null` *required*

Cuándo se solicitó la cancelación, o cuándo se canceló la membresía si no hay ninguna hora de solicitud registrada, como marca de tiempo ISO 8601. `null` cuando no hay ninguna registrada.

**cancellation\_reason** `string | null` *required*

Explicación en texto libre proporcionada al cancelar. `null` cuando no se proporcionó ningún motivo.

**collection\_method** `string | null` *required*

Cómo se cobran las renovaciones. `charge_automatically` cobra el método de pago guardado en cada periodo; `send_invoice` envía al comprador una factura por correo electrónico en cada periodo. `null` cuando no está establecido.

Opciones disponibles: `charge_automatically`, `send_invoice`

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

Cuándo se creó la membresía, como marca de tiempo ISO 8601.

**current\_period\_end** `string | null` *required*

Cuándo se renueva el periodo de facturación actual, o cuándo vence una membresía que no se renueva, como marca de tiempo ISO 8601. `null` para compras únicas sin vencimiento.

**current\_period\_start** `string | null` *required*

Cuándo comenzó el periodo de facturación actual, como marca de tiempo ISO 8601. `null` cuando no hay ningún periodo de facturación registrado.

**expires\_at** `string | null` *required*

Cuándo termina el acceso de una membresía con un vencimiento fijo, como marca de tiempo ISO 8601. `null` cuando la membresía no tiene vencimiento, como una membresía que se renueva.

**external\_accounts** `object[] | null` *required*

Las cuentas del miembro en plataformas externas, como Discord y Telegram. Vacío cuando el miembro no tiene ninguna vinculada. `null` en los webhooks.

> [accordion] Propiedades
>
> **external\_id** `string` *required*
>
> El ID de usuario del miembro en la plataforma, como un ID de usuario de Discord. Con el prefijo de la plataforma (`discord_\<external_id>`), es el valor `external_account` por el que filtra List Memberships.
>
> **platform** `string` *required*
>
> La plataforma en la que está la cuenta del miembro.
>
> Opciones disponibles: `discord`, `telegram`
>
> **username** `string | null` *required*
>
> El nombre de usuario del miembro en la plataforma. `null` cuando Whop no lo conoce, como en el caso de una membresía importada solo con un ID de Discord.

**feedback\_option** `object | null` *required*

El motivo de cancelación propio de la cuenta que eligió el miembro, tal como lo vio. `null` cuando el miembro eligió una categoría predeterminada o no indicó ningún motivo.

> [accordion] Propiedades
>
> **label** `string` *required*
>
> La etiqueta de la opción cuando el miembro la eligió. Cambiar el nombre de la opción más tarde no la modifica.

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

El precio inicial actual de la variante, en la moneda de la variante. Es un precio de lista, no necesariamente lo que pagó el comprador. `amount` es `"0.00"` cuando el primer cobro es gratuito.

> [accordion] Propiedades
>
> **amount** `string` *required*
>
> El importe en unidades principales, como una cadena decimal exacta. Por ejemplo, `"10.00"` son diez dólares. Es una cadena para que ningún número de punto flotante lo redondee durante la transmisión.
>
> **currency** `string` *required*
>
> Código de moneda 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 cobro.
>
> **display\_decimals** `integer` *required*
>
> Cuántos decimales MOSTRAR. Normalmente igual a `decimals`, y deliberadamente no siempre: COP se cobra en centavos pero se escribe en pesos enteros, así que es `2` y `0`. Usa este valor para dar formato al número en tu propia configuración regional.

**license\_key** `string | null` *required*

La clave de licencia de software de esta membresía. Solo está presente cuando el producto incluye una experiencia de licencias de software.

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

URL donde el comprador puede iniciar sesión para gestionar la facturación. `null` sin un registro de miembro o salvo que el llamador sea el comprador o tenga `member:manage` en la cuenta.

**member** `object | null` *required*

La fila de miembro del llamador en la cuenta. Solo está presente cuando la membresía pertenece al llamador; `null` en las lecturas del lado del vendedor.

> [accordion] Propiedades
>
> **access\_level** `string` *required*
>
> A qué puede acceder el miembro en la cuenta: `customer` para miembros que pagan, `admin` para miembros del equipo, `no_access` una vez que han caducado todas las concesiones.
>
> Opciones disponibles: `no_access`, `admin`, `customer`
>
> **last\_accessed\_at** `string | null` *required*
>
> Cuándo abrió el miembro por última vez el contenido de la cuenta, como marca de tiempo ISO 8601. `null` si nunca lo ha hecho.
>
> **position** `number | null` *required*
>
> La posición de orden del miembro en la propia lista de cuentas del comprador. `null` hasta que la organice.

**member\_id** `string | null` *required*

El registro de miembro del comprador en la cuenta, con el prefijo `mber_`. `null` cuando la membresía no tiene registro de miembro, como una membresía no reclamada.

**metadata** `object` *required*

Pares clave-valor personalizados almacenados en la membresía, utilizados habitualmente para las licencias de software.

**most\_recent\_action** `string | null` *required*

El evento más reciente del ciclo de vida de la membresía, como `renewing_on` o `canceled_on`. Combínalo con `most_recent_action_at`. `null` cuando no hay ninguno registrado.

Opciones disponibles: `canceled_on`, `finished_split_pay_at`, `canceling_on`, `ending_on`, `renewing_on`, `past_due`, `next_payment_attempt`, `paused_at`, `trial_ends_at`, `unresolved_at`, `trial_canceling_on`

**most\_recent\_action\_at** `string | null` *required*

Cuándo ocurrió o está programado que ocurra `most_recent_action`, como marca de tiempo ISO 8601. Una hora futura para eventos próximos como `renewing_on`. `null` cuando no hay ninguna acción registrada.

**phone\_number** `string | null` *required*

El número de teléfono del comprador registrado para esta membresía, o `null`. El número recopilado (o verificado) en el checkout cuando la recopilación de teléfonos del vendedor está activada; en su defecto, el número de la cuenta del comprador cuando lo ha compartido con este vendedor.

**product** `object` *required*

El producto al que esta membresía concede acceso.

> [accordion] Propiedades
>
> **id** `string` *required*
>
> ID del producto, con el prefijo `prod_`.
>
> **logo\_url** `string | null` *required*
>
> URL de la imagen del logotipo del producto. `null` cuando el producto no tiene logotipo.
>
> **title** `string` *required*
>
> Nombre visible del producto.

**product\_id** `string` *required*

El producto al que esta membresía concede acceso, con el prefijo `prod_`.

**promo\_code\_id** `string | null` *required*

El código promocional que descuenta esta membresía, con el prefijo `promo_`. `null` cuando no se ha aplicado ninguno. Se establece en el checkout o mediante Apply Promo Code to Membership.

**renewal\_price** `object | null` *required*

El precio de renovación de la variante, en la moneda de la variante, después de cualquier código promocional que siga aplicándose. A una membresía facturada en la moneda local del comprador se le cobra este precio convertido al tipo de cambio de cada fecha de facturación. `null` para membresías que no se renuevan.

> [accordion] Propiedades
>
> **amount** `string` *required*
>
> El importe en unidades principales, como una cadena decimal exacta. Por ejemplo, `"10.00"` son diez dólares. Es una cadena para que ningún número de punto flotante lo redondee durante la transmisión.
>
> **currency** `string` *required*
>
> Código de moneda 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 cobro.
>
> **display\_decimals** `integer` *required*
>
> Cuántos decimales MOSTRAR. Normalmente igual a `decimals`, y deliberadamente no siempre: COP se cobra en centavos pero se escribe en pesos enteros, así que es `2` y `0`. Usa este valor para dar formato al número en tu propia configuración regional.

**split\_pay\_current\_payments** `integer | null` *required*

Cuotas pagadas contabilizadas hasta ahora en una membresía de pago fraccionado. `null` cuando la membresía no usa pago fraccionado, o antes de que se contabilice su primera cuota.

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

Pagos a plazos requeridos antes de que la membresía deje de facturarse. `null` cuando la membresía no usa pago fraccionado.

**status** `string` *required*

Estado de facturación de la membresía. Las membresías `active`/`trialing` conceden acceso; `past_due` es el periodo de gracia tras un pago fallido; las compras únicas `completed` mantienen el acceso; las `canceled`/`expired` no.

Opciones disponibles: `trialing`, `active`, `past_due`, `completed`, `canceled`, `expired`, `unresolved`

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

Cuándo se modificó la membresía por última vez, como marca de tiempo ISO 8601. Refleja el cambio más reciente en la propia membresía, para que puedas conciliar con los reintentos, repeticiones y rellenos de webhooks.

**user\_id** `string | null` *required*

El comprador, con el prefijo `user_`. `null` cuando el comprador es otra empresa o la membresía no está reclamada.

**variant\_id** `string` *required*

La variante que compró el comprador, con el prefijo `plan_`.

```json Membership theme={null}
{
	"id": "mem_xxxxxxxxxxxxxx",
	"affiliate": null,
	"status": "active",
	"collection_method": "charge_automatically",
	"most_recent_action": "renewing_on",
	"most_recent_action_at": "2026-08-01T00:00:00.000Z",
	"user_id": "user_xxxxxxxxxxxxx",
	"product_id": "prod_xxxxxxxxxxxxx",
	"variant_id": "plan_xxxxxxxxxxxxx",
	"member_id": "mber_xxxxxxxxxxxxx",
	"product": {
		"id": "prod_xxxxxxxxxxxxx",
		"title": "Pickaxe Pro",
		"logo_url": "https://cdn.whop.com/product.png"
	},
	"initial_price": {
		"currency": "usd",
		"amount": "0.00",
		"decimals": 2,
		"display_decimals": 2
	},
	"renewal_price": {
		"currency": "usd",
		"amount": "50.00",
		"decimals": 2,
		"display_decimals": 2
	},
	"split_pay_current_payments": null,
	"split_pay_required_payments": null,
	"expires_at": null,
	"promo_code_id": null,
	"billing_period_days": 30,
	"license_key": "A1B2C3-D4E5F6-G7H8I9",
	"phone_number": "+12025550123",
	"cancel_at_period_end": false,
	"current_period_start": "2026-07-01T00:00:00.000Z",
	"current_period_end": "2026-08-01T00:00:00.000Z",
	"canceled_at": null,
	"cancel_option": null,
	"cancellation_reason": null,
	"feedback_option": null,
	"external_accounts": [
		{
			"platform": "discord",
			"external_id": "123456789012345678",
			"username": "jane"
		}
	],
	"manage_url": "https://whop.com/billing/manage/mber_xxxxxxxxxxxxx",
	"metadata": {
		"external_customer_id": "cus_123"
	},
	"created_at": "2026-07-01T00:00:00.000Z",
	"updated_at": "2026-07-15T00:00:00.000Z",
	"member": {
		"access_level": "customer",
		"last_accessed_at": "2026-07-20T15:30:00.000Z",
		"position": 1
	},
	"account": {
		"id": "biz_xxxxxxxxxxxxxx",
		"title": "Pickaxe",
		"route": "pickaxe",
		"logo_url": "https://cdn.whop.com/account.png"
	}
}
```


## Related topics

- [Membresías](https://docs.whop.com/es/developer/guides/memberships.md)
- [API de miembros](https://docs.whop.com/es/api-reference/members/member.md)
- [API de Search](https://docs.whop.com/es/api-reference/search/search.md)
