Skip to main content

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.

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

​
Lifecycle at a glance

ActionMethodWhat it does
Pause billingmemberships.pauseStops future renewals until resumed. Existing access stays.
Resume billingmemberships.resumeReverses a pause.
Cancelmemberships.cancelAt period end (default) or immediate.
Uncancelmemberships.uncancelReverses a pending cancel_at_period_end.
Comp timememberships.addFreeDaysExtends the next renewal date by N days.
Update metadatamemberships.updatePatch metadata or other writable fields.

​
Retrieve and list

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);
}

​
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. 
await client.memberships.pause("mem_xxxxxxxxxxxxx", {
  void_payments: false, // optional, default false
});

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

​
Cancel

Two cancellation modes. Default is at_period_end, which keeps access until the current renewal date and then deactivates. 
// 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",
});
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.

​
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. 
await client.memberships.uncancel("mem_xxxxxxxxxxxxx");

​
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. 
await client.memberships.addFreeDays("mem_xxxxxxxxxxxxx", {
  free_days: 7,
});
free_days accepts 1 through 1095 (3 years).

​
Update metadata

Patch arbitrary metadata or other writable fields on the membership. 
await client.memberships.update("mem_xxxxxxxxxxxxx", {
  metadata: { internal_user_id: "user_12345", tier: "gold" },
});

​
Listen for lifecycle events

Subscribe via webhooks. These are the events that fire across the lifecycle:
EventWhen it fires
membership.activatedMembership becomes valid (initial purchase or renewal payment succeeds).
membership.deactivatedMembership goes invalid (failed payment, immediate cancel, period-end cancel landing, or user leaves).
membership.cancel_at_period_end_changedThe 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

Accept payments

Where memberships come from. One-time and recurring checkouts.

Save payment methods

On-file cards for future renewals and off-session billing.

Listen to webhooks

React to activation, deactivation, and cancellation toggles.

Memberships API reference

Full resource: fields, statuses, and every endpoint.