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

# Membresías

> Consulta membresías y cambia su facturación con la API, por ejemplo pausando una suscripción o añadiendo días gratis.

Una membresía es la relación activa entre un usuario y un producto. Registra el acceso, el estado de facturación y el calendario de renovación. No creas membresías directamente porque el checkout lo hace por ti. Una vez que existe una membresía, puedes consultarla, pausar o cancelar la facturación, regalar tiempo o actualizar los metadatos.

> [!TIP]
>
> La mayoría de las apps no necesitan gestionar membresías en absoluto. Recurre a estos métodos cuando crees herramientas de administración, flujos de atención al cliente o paneles de autoservicio que permitan a los usuarios pausar o cancelar.

## El ciclo de vida de un vistazo

| Acción | Método | Qué hace |
| - | - | - |
| Pausar la facturación | [`memberships.pause`](https://docs.whop.com/es/api-reference/memberships/pause-membership) | Detiene las renovaciones futuras hasta que se reanuden. El acceso existente se mantiene. |
| Reanudar la facturación | [`memberships.resume`](https://docs.whop.com/es/api-reference/memberships/resume-membership) | Revierte una pausa. |
| Cancelar | [`memberships.cancel`](https://docs.whop.com/es/api-reference/memberships/cancel-membership) | Al final del periodo o de inmediato (predeterminado). |
| Revertir la cancelación | [`memberships.update`](https://docs.whop.com/es/api-reference/memberships/update-membership) | Envía `cancel_at_period_end: false` para revertir una cancelación pendiente. |
| Regalar tiempo | [`memberships.extend`](https://docs.whop.com/es/api-reference/memberships/extend-membership) | Retrasa la próxima fecha de renovación N días. |
| Cambiar el día de facturación | [`memberships.update`](https://docs.whop.com/es/api-reference/memberships/update-membership) | Envía `current_period_end` para mover la próxima renovación. Las membresías facturadas cada 30, 60, 90 … 360 o 365 días siguen renovándose ese día del mes. |
| Actualizar metadatos | [`memberships.update`](https://docs.whop.com/es/api-reference/memberships/update-membership) | Modifica los metadatos u otros campos editables. |

## Obtener y listar

```typescript TypeScript theme={null}
const membership = await client.memberships.retrieve({ id: "mem_xxxxxxxxxxxxx" });

// List with auto-pagination
const memberships = await client.memberships.list({
  account_id: "biz_xxxxxxxxxxxxx",
});

for await (const item of memberships) {
  console.log(item);
}
```

```python Python theme={null}
membership = client.memberships.retrieve("mem_xxxxxxxxxxxxx")

for item in client.memberships.list(account_id="biz_xxxxxxxxxxxxx"):
    print(item)
```

```ruby Ruby theme={null}
membership = client.memberships.retrieve(id: "mem_xxxxxxxxxxxxx")

# list returns an Enumerable that pages for you and yields one membership at a time
client.memberships.list(account_id: "biz_xxxxxxxxxxxxx").each do |item|
  puts item
end
```

```rust Rust theme={null}
let membership = client
    .memberships
    .retrieve(&"mem_xxxxxxxxxxxxx".to_string(), None)
    .await?;

// List one page of memberships for an account
let memberships = client
    .memberships
    .list(
        &MembershipsListQueryRequest {
            account_id: Some("biz_xxxxxxxxxxxxx".to_string()),
            ..Default::default()
        },
        None,
    )
    .await?;

for item in memberships.data {
    println!("{item:?}");
}
```

```go Go theme={null}
membership, err := client.Memberships.Retrieve(context.TODO(), &whopsdk.RetrieveMembershipsRequest{
    ID: "mem_xxxxxxxxxxxxx",
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(membership)

// List with auto-pagination
page, err := client.Memberships.List(context.TODO(), &whopsdk.ListMembershipsRequest{
    AccountID: whopsdk.String("biz_xxxxxxxxxxxxx"),
})
if err != nil {
    log.Fatal(err)
}

iter := page.Iterator()
for iter.Next(context.TODO()) {
    fmt.Println(iter.Current())
}
if err := iter.Err(); err != nil {
    log.Fatal(err)
}
```

## Pausar y reanudar

Pausar detiene el siguiente ciclo de facturación. El usuario conserva su acceso actual hasta que termine el periodo en curso, pero la renovación no se ejecutará. Pasa `until` para programar una reanudación automática.

```typescript TypeScript theme={null}
await client.memberships.pause({
  id: "mem_xxxxxxxxxxxxx",
  until: "2026-09-01T00:00:00Z", // optional, resumes automatically
});

// Later
await client.memberships.resume({ id: "mem_xxxxxxxxxxxxx" });
```

```python Python theme={null}
client.memberships.pause(
    "mem_xxxxxxxxxxxxx",
    until="2026-09-01T00:00:00Z",  # optional, resumes automatically
)

client.memberships.resume("mem_xxxxxxxxxxxxx")
```

```ruby Ruby theme={null}
client.memberships.pause(
  id: "mem_xxxxxxxxxxxxx",
  until: "2026-09-01T00:00:00Z", # optional, resumes automatically
)

# Later
client.memberships.resume(id: "mem_xxxxxxxxxxxxx")
```

```rust Rust theme={null}
client
    .memberships
    .pause(
        &"mem_xxxxxxxxxxxxx".to_string(),
        &PauseMembershipsRequest {
            until: Some("2026-09-01T00:00:00Z".to_string()), // optional, resumes automatically
        },
        None,
    )
    .await?;

// Later
client.memberships.resume(&"mem_xxxxxxxxxxxxx".to_string(), None).await?;
```

```go Go theme={null}
_, err := client.Memberships.Pause(context.TODO(), &whopsdk.PauseMembershipsRequest{
    ID:    "mem_xxxxxxxxxxxxx",
    Until: whopsdk.String("2026-09-01T00:00:00Z"), // optional, resumes automatically
})
if err != nil {
    log.Fatal(err)
}

// Later
if _, err := client.Memberships.Resume(context.TODO(), &whopsdk.ResumeMembershipsRequest{
    ID: "mem_xxxxxxxxxxxxx",
}); err != nil {
    log.Fatal(err)
}
```

## Cancelar

Hay dos modos de cancelación. `cancel_at_period_end: true` mantiene el acceso hasta la fecha de renovación actual y luego desactiva la membresía. Omítelo (o pasa `false`) para revocar el acceso de inmediato.

```typescript TypeScript theme={null}
// Cancel at the end of the current billing period
await client.memberships.cancel({
  id: "mem_xxxxxxxxxxxxx",
  cancel_at_period_end: true,
});

// Cancel immediately. Access ends now.
await client.memberships.cancel({
  id: "mem_xxxxxxxxxxxxx",
  cancel_at_period_end: false,
  reason: "Requested by customer",
});
```

```python Python theme={null}
# Cancel at the end of the current billing period
client.memberships.cancel(
    "mem_xxxxxxxxxxxxx",
    cancel_at_period_end=True,
)

# Cancel immediately. Access ends now.
client.memberships.cancel(
    "mem_xxxxxxxxxxxxx",
    cancel_at_period_end=False,
    reason="Requested by customer",
)
```

```ruby Ruby theme={null}
# Cancel at the end of the current billing period
client.memberships.cancel(
  id: "mem_xxxxxxxxxxxxx",
  cancel_at_period_end: true,
)

# Cancel immediately. Access ends now.
client.memberships.cancel(
  id: "mem_xxxxxxxxxxxxx",
  cancel_at_period_end: false,
  reason: "Requested by customer",
)
```

```rust Rust theme={null}
// Cancel at the end of the current billing period
client
    .memberships
    .cancel(
        &"mem_xxxxxxxxxxxxx".to_string(),
        &CancelMembershipsRequest {
            cancel_at_period_end: Some(true),
            ..Default::default()
        },
        None,
    )
    .await?;

// Cancel immediately. Access ends now.
client
    .memberships
    .cancel(
        &"mem_xxxxxxxxxxxxx".to_string(),
        &CancelMembershipsRequest {
            cancel_at_period_end: Some(false),
            reason: Some("Requested by customer".to_string()),
        },
        None,
    )
    .await?;
```

```go Go theme={null}
// Cancel at the end of the current billing period
_, err := client.Memberships.Cancel(context.TODO(), &whopsdk.CancelMembershipsRequest{
    ID:                "mem_xxxxxxxxxxxxx",
    CancelAtPeriodEnd: whopsdk.Bool(true),
})
if err != nil {
    log.Fatal(err)
}

// Cancel immediately. Access ends now.
_, err = client.Memberships.Cancel(context.TODO(), &whopsdk.CancelMembershipsRequest{
    ID:                "mem_xxxxxxxxxxxxx",
    CancelAtPeriodEnd: whopsdk.Bool(false),
    Reason:            whopsdk.String("Requested by customer"),
})
if err != nil {
    log.Fatal(err)
}
```

> [!NOTE]
>
> `cancel_at_period_end: true` cambia `cancel_at_period_end` a `true` en la membresía. El usuario conserva el acceso hasta la renovación; después la membresía se desactiva y se dispara `membership.updated` con `previous_attributes.status` establecido en el estado que dejó. Omitir el campo revoca el acceso de inmediato, así que envíalo explícitamente siempre que quieras cancelar al final del periodo.

## Revertir una cancelación

Si el usuario cambia de opinión antes de que termine el periodo, elimina la cancelación pendiente al final del periodo con una actualización. No tiene efecto si la membresía no estaba programada para cancelarse.

```typescript TypeScript theme={null}
await client.memberships.update({
  id: "mem_xxxxxxxxxxxxx",
  cancel_at_period_end: false,
});
```

```python Python theme={null}
client.memberships.update("mem_xxxxxxxxxxxxx", cancel_at_period_end=False)
```

```ruby Ruby theme={null}
client.memberships.update(id: "mem_xxxxxxxxxxxxx", cancel_at_period_end: false)
```

```rust Rust theme={null}
client
    .memberships
    .update(
        &"mem_xxxxxxxxxxxxx".to_string(),
        &UpdateMembershipsRequest {
            cancel_at_period_end: Some(false),
            ..Default::default()
        },
        None,
    )
    .await?;
```

```go Go theme={null}
if _, err := client.Memberships.Update(context.TODO(), &whopsdk.UpdateMembershipsRequest{
    ID:                "mem_xxxxxxxxxxxxx",
    CancelAtPeriodEnd: whopsdk.Bool(false),
}); err != nil {
    log.Fatal(err)
}
```

## Añadir días gratis

Regala al usuario tiempo extra en su periodo actual. La próxima fecha de renovación se retrasa `days` días. Es útil para interrupciones del servicio, gestos de atención al cliente o recompensas por referidos.

```typescript TypeScript theme={null}
await client.memberships.extend({
  id: "mem_xxxxxxxxxxxxx",
  days: 7,
});
```

```python Python theme={null}
client.memberships.extend("mem_xxxxxxxxxxxxx", days=7)
```

```ruby Ruby theme={null}
client.memberships.extend(id: "mem_xxxxxxxxxxxxx", days: 7)
```

```rust Rust theme={null}
client
    .memberships
    .extend(
        &"mem_xxxxxxxxxxxxx".to_string(),
        &ExtendMembershipsRequest { days: 7 },
        None,
    )
    .await?;
```

```go Go theme={null}
if _, err := client.Memberships.Extend(context.TODO(), &whopsdk.ExtendMembershipsRequest{
    ID:   "mem_xxxxxxxxxxxxx",
    Days: 7,
}); err != nil {
    log.Fatal(err)
}
```

`days` acepta valores de 1 a 1095 (3 años).

## Actualizar metadatos

Modifica metadatos arbitrarios u otros campos editables de la membresía.

```typescript TypeScript theme={null}
await client.memberships.update({
  id: "mem_xxxxxxxxxxxxx",
  metadata: { internal_user_id: "user_12345", tier: "gold" },
});
```

```python Python theme={null}
client.memberships.update(
    "mem_xxxxxxxxxxxxx",
    metadata={"internal_user_id": "user_12345", "tier": "gold"},
)
```

```ruby Ruby theme={null}
client.memberships.update(
  id: "mem_xxxxxxxxxxxxx",
  metadata: { internal_user_id: "user_12345", tier: "gold" },
)
```

```rust Rust theme={null}
client
    .memberships
    .update(
        &"mem_xxxxxxxxxxxxx".to_string(),
        &UpdateMembershipsRequest {
            metadata: Some(HashMap::from([
                ("internal_user_id".to_string(), json!("user_12345")),
                ("tier".to_string(), json!("gold")),
            ])),
            ..Default::default()
        },
        None,
    )
    .await?;
```

```go Go theme={null}
if _, err := client.Memberships.Update(context.TODO(), &whopsdk.UpdateMembershipsRequest{
    ID: "mem_xxxxxxxxxxxxx",
    Metadata: map[string]any{
        "internal_user_id": "user_12345",
        "tier":             "gold",
    },
}); err != nil {
    log.Fatal(err)
}
```

## Escucha los eventos del ciclo de vida

Suscríbete mediante [webhooks](https://docs.whop.com/es/developer/guides/webhooks.md). Estos son los eventos que se disparan a lo largo del ciclo de vida:

| Evento | Cuándo se dispara |
| - | - |
| [`membership.activated`](https://docs.whop.com/es/api-reference/memberships/membership-activated) | La membresía pasa a ser válida (la compra inicial o el pago de renovación se completan correctamente). |
| [`membership.updated`](https://docs.whop.com/es/api-reference/memberships/membership-updated) | Algo cambió en la membresía. Dejó de ser válida (pago fallido, cancelación inmediata, cancelación al final del periodo que se hace efectiva o el usuario se fue). El usuario activó o desactivó la cancelación. El vendedor editó el periodo de facturación, el precio o la fecha de renovación. `previous_attributes` contiene los valores anteriores al cambio. Las activaciones también se entregan como `membership.updated`. |

Con `pause` / `resume` / `extend`, el estado de la membresía no cambia, así que no se dispara ningún evento de activación/desactivación. Si necesitas confirmar que la mutación se completó, obtén la membresía después de la llamada o consulta periódicamente según tu propio calendario.

## Próximos pasos

> [card] [Acepta pagos](https://docs.whop.com/es/developer/guides/accept-payments.md)
>
> De dónde vienen las membresías. Checkouts de pago único y recurrentes.

> [card] [Guardar métodos de pago](https://docs.whop.com/es/developer/guides/save-payment-methods.md)
>
> Tarjetas guardadas para futuras renovaciones y cobros fuera de sesión.

> [card] [Escucha webhooks](https://docs.whop.com/es/developer/guides/webhooks.md)
>
> Reacciona a activaciones, desactivaciones y cambios en la cancelación.

> [card] [Referencia de la API de membresías](https://docs.whop.com/es/api-reference/memberships/membership)
>
> El recurso completo: campos, estados y todos los endpoints.


## Related topics

- [API de membresías](https://docs.whop.com/es/api-reference/memberships/membership.md)
- [Comprueba los entitlements](https://docs.whop.com/es/developer/guides/ios/check-entitlements.md)
- [Migra desde versiones anteriores](https://docs.whop.com/es/developer/api/migrate-from-previous-versions.md)
