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

# Memberships

> Manage subscription lifecycle. Pause, resume, cancel, uncancel, and add free days.

A Membership is the active relationship between a user and a product. It tracks access, billing status, and renewal schedule. You don't create memberships directly; checkout does that for you. Once a membership exists, you can read it, pause or cancel billing, comp time, or update metadata.

<Tip>
  Most apps don't need to manage memberships at all. Reach for these methods when you're building admin tools, customer support flows, or self-serve dashboards that let users pause or cancel.
</Tip>

## Lifecycle at a glance

| Action          | Method                                                                           | What it does                                                |
| --------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Pause billing   | [`memberships.pause`](/api-reference/memberships/pause-membership)               | Stops future renewals until resumed. Existing access stays. |
| Resume billing  | [`memberships.resume`](/api-reference/memberships/resume-membership)             | Reverses a pause.                                           |
| Cancel          | [`memberships.cancel`](/api-reference/memberships/cancel-membership)             | At period end (default) or immediate.                       |
| Uncancel        | [`memberships.uncancel`](/api-reference/memberships/uncancel-membership)         | Reverses a pending `cancel_at_period_end`.                  |
| Comp time       | [`memberships.addFreeDays`](/api-reference/memberships/add-free-days-membership) | Extends the next renewal date by N days.                    |
| Update metadata | [`memberships.update`](/api-reference/memberships/update-membership)             | Patch metadata or other writable fields.                    |

## Retrieve and list

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

  // List with auto-pagination
  for await (const page of client.memberships.list({
    company_id: "biz_xxxxxxxxxxxxx",
  })) {
    console.log(page);
  }
  ```

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

  for page in client.memberships.list(company_id="biz_xxxxxxxxxxxxx"):
      print(page)
  ```

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

  client.memberships.list(company_id: "biz_xxxxxxxxxxxxx").each do |page|
    puts page
  end
  ```
</CodeGroup>

## Pause and resume

Pausing stops the next billing cycle. The user keeps their existing access until the current period ends, but the renewal won't fire. `void_payments: true` voids any pending charges.

<CodeGroup>
  ```typescript TypeScript theme={null}
  await client.memberships.pause("mem_xxxxxxxxxxxxx", {
    void_payments: false, // optional, default false
  });

  // Later
  await client.memberships.resume("mem_xxxxxxxxxxxxx");
  ```

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

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

  ```ruby Ruby theme={null}
  client.memberships.pause("mem_xxxxxxxxxxxxx", void_payments: false)

  # Later
  client.memberships.resume("mem_xxxxxxxxxxxxx")
  ```
</CodeGroup>

## Cancel

Two cancellation modes. Default is `at_period_end`, which keeps access until the current renewal date and then deactivates.

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Cancel at the end of the current billing period (default)
  await client.memberships.cancel("mem_xxxxxxxxxxxxx", {
    cancellation_mode: "at_period_end",
  });

  // Cancel immediately. Access ends now.
  await client.memberships.cancel("mem_xxxxxxxxxxxxx", {
    cancellation_mode: "immediate",
  });
  ```

  ```python Python theme={null}
  client.memberships.cancel(
      "mem_xxxxxxxxxxxxx",
      cancellation_mode="at_period_end",
  )

  client.memberships.cancel(
      "mem_xxxxxxxxxxxxx",
      cancellation_mode="immediate",
  )
  ```

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

  # Cancel immediately. Access ends now.
  client.memberships.cancel(
    "mem_xxxxxxxxxxxxx",
    cancellation_mode: "immediate",
  )
  ```
</CodeGroup>

<Note>
  `at_period_end` flips `cancel_at_period_end` to `true` on the membership. The user keeps access until renewal, then the membership deactivates and `membership.deactivated` fires.
</Note>

## Uncancel

If the user changes their mind before the period ends, undo a pending `at_period_end` cancellation. Has no effect if the membership wasn't scheduled to cancel.

<CodeGroup>
  ```typescript TypeScript theme={null}
  await client.memberships.uncancel("mem_xxxxxxxxxxxxx");
  ```

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

  ```ruby Ruby theme={null}
  client.memberships.uncancel("mem_xxxxxxxxxxxxx")
  ```
</CodeGroup>

## Add free days

Comp the user with extra time on their current period. The next renewal date moves forward by `free_days`. Useful for service interruptions, support gestures, or referral rewards.

<CodeGroup>
  ```typescript TypeScript theme={null}
  await client.memberships.addFreeDays("mem_xxxxxxxxxxxxx", {
    free_days: 7,
  });
  ```

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

  ```ruby Ruby theme={null}
  client.memberships.add_free_days("mem_xxxxxxxxxxxxx", free_days: 7)
  ```
</CodeGroup>

`free_days` accepts 1 through 1095 (3 years).

## Update metadata

Patch arbitrary metadata or other writable fields on the membership.

<CodeGroup>
  ```typescript TypeScript theme={null}
  await client.memberships.update("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(
    "mem_xxxxxxxxxxxxx",
    metadata: { internal_user_id: "user_12345", tier: "gold" },
  )
  ```
</CodeGroup>

## Listen for lifecycle events

Subscribe via [webhooks](/developer/guides/webhooks). These are the events that fire across the lifecycle:

| Event                                                                                                           | When it fires                                                                                          |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [`membership.activated`](/api-reference/memberships/membership-activated)                                       | Membership becomes valid (initial purchase or renewal payment succeeds).                               |
| [`membership.deactivated`](/api-reference/memberships/membership-deactivated)                                   | Membership goes invalid (failed payment, immediate cancel, period-end cancel landing, or user leaves). |
| [`membership.cancel_at_period_end_changed`](/api-reference/memberships/membership-cancel-at-period-end-changed) | The user toggled cancellation on or off (pairs with `cancel` and `uncancel`).                          |

For `pause` / `resume` / `add_free_days`, the membership status doesn't flip, so no activation/deactivation event fires. If you need to confirm the mutation succeeded, retrieve the membership after the call or poll on your own schedule.

## Next steps

<CardGroup cols={2}>
  <Card title="Accept payments" href="/developer/guides/accept-payments">
    Where memberships come from. One-time and recurring checkouts.
  </Card>

  <Card title="Save payment methods" href="/developer/guides/save-payment-methods">
    On-file cards for future renewals and off-session billing.
  </Card>

  <Card title="Listen to webhooks" href="/developer/guides/webhooks">
    React to activation, deactivation, and cancellation toggles.
  </Card>

  <Card title="Memberships API reference" href="/api-reference/memberships/membership">
    Full resource: fields, statuses, and every endpoint.
  </Card>
</CardGroup>