Memberships

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

Action	Method	What it does
Pause billing	`memberships.pause`	Stops future renewals until resumed. Existing access stays.
Resume billing	`memberships.resume`	Reverses a pause.
Cancel	`memberships.cancel`	At period end (default) or immediate.
Uncancel	`memberships.uncancel`	Reverses a pending `cancel_at_period_end`.
Comp time	`memberships.addFreeDays`	Extends the next renewal date by N days.
Update metadata	`memberships.update`	Patch 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);
}

membership = client.memberships.retrieve("mem_xxxxxxxxxxxxx")

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

membership = client.memberships.retrieve("mem_xxxxxxxxxxxxx")

client.memberships.list(company_id: "biz_xxxxxxxxxxxxx").each do |page|
  puts page
end

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

client.memberships.pause("mem_xxxxxxxxxxxxx", void_payments=False)

client.memberships.resume("mem_xxxxxxxxxxxxx")

client.memberships.pause("mem_xxxxxxxxxxxxx", void_payments: false)

# Later
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",
});

client.memberships.cancel(
    "mem_xxxxxxxxxxxxx",
    cancellation_mode="at_period_end",
)

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

# 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",
)

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

client.memberships.uncancel("mem_xxxxxxxxxxxxx")

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

client.memberships.add_free_days("mem_xxxxxxxxxxxxx", free_days=7)

client.memberships.add_free_days("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" },
});

client.memberships.update(
    "mem_xxxxxxxxxxxxx",
    metadata={"internal_user_id": "user_12345", "tier": "gold"},
)

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:

Event	When it fires
`membership.activated`	Membership becomes valid (initial purchase or renewal payment succeeds).
`membership.deactivated`	Membership goes invalid (failed payment, immediate cancel, period-end cancel landing, or user leaves).
`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

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.

Payments

iOS Payments

Lifecycle at a glance

Retrieve and list

Pause and resume

Cancel

Uncancel

Add free days

Update metadata

Listen for lifecycle events

Next steps

Accept payments

Save payment methods

Listen to webhooks

Memberships API reference

​Lifecycle at a glance

​Retrieve and list

​Pause and resume

​Cancel

​Uncancel

​Add free days

​Update metadata

​Listen for lifecycle events

​Next steps

Accept payments

Save payment methods

Listen to webhooks

Memberships API reference

Lifecycle at a glance

Retrieve and list

Pause and resume

Cancel

Uncancel

Add free days

Update metadata

Listen for lifecycle events

Next steps