Membership - Whop Docs

A Membership is a customer’s purchase of a variant: the subscription or one-time grant that gives them access to a product. It tracks billing state (active, trialing, past_due, and so on), the current period, pending cancellations, custom metadata, and the software license key when the product includes licensing. Use the Memberships API to list an account’s memberships or your own, retrieve one by ID or license key, invite a recipient to join through a free variant, and manage the lifecycle: cancel immediately or at period end, reverse a scheduled cancellation, pause and resume payment collection, extend or reactivate access, apply a promo code or affiliate, change renewal cadence, resync access, generate a transfer link, and update metadata.

Replaces the Legacy Memberships resource. Existing Legacy integrations keep working; see API versions for the stability contract.

Endpoints

Endpoint	Request
List Memberships	GET `/memberships`
Retrieve Membership	GET `/memberships/{id}`
Apply Promo Code to Membership	POST `/memberships/{id}/apply_promo_code`
Assign Affiliate to Membership	POST `/memberships/{id}/assign_affiliate`
Cancel Membership	POST `/memberships/{id}/cancel`
Extend Membership	POST `/memberships/{id}/extend`
Pause Membership	POST `/memberships/{id}/pause`
Reactivate Membership	POST `/memberships/{id}/reactivate`
Resume Membership	POST `/memberships/{id}/resume`
Resync Membership Access	POST `/memberships/{id}/resync_access`
Transfer Membership	POST `/memberships/{id}/transfer`
Invite to a Membership	POST `/memberships/invite`
Update Membership	PATCH `/memberships/{id}`

Attributes

string

required

Membership ID, prefixed mem_.

object

required

The account (seller) this membership belongs to.

Properties

string

required

Account ID, prefixed biz_.

string | null

required

Account logo image URL. null when the account has not set one.

string

required

Account public route identifier — the whop.com/\{route} storefront path.

string

required

Account display name.

object | null

required

The membership’s affiliate commission. null without an affiliate, without affiliate:basic:read on the account, and always in webhooks.

Properties

string

required

Affiliate ID, prefixed aff_.

string

required

Whether the commission is paid on the membership’s first payment only or on all its payments.Available options: first_payment, all_payments

object | null

required

The flat fee commission in the membership currency, or null for a percentage.

Properties

string

required

The amount in major units, as an exact decimal string — "10.00" is ten dollars. A string so no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount CARRIES — the precision the charge itself runs at.

integer

required

How many decimal places to SHOW. Usually equal to decimals, and deliberately not always: COP is charged in centavos but written in whole pesos, so it is 2 and 0. Format the number in your own locale using this.

number | null

required

The percentage commission in percentage points, so 20 means 20%, or null for a flat fee.

string

required

Whether the commission is a percentage or a flat fee.Available options: flat_fee, percentage

boolean

required

Whether this membership pays affiliate commissions. false means the affiliate is kept on the membership but is no longer paid.

string

required

ID of the affiliate’s user, prefixed user_.

integer | null

required

Number of days between recurring charges. null for non-renewing memberships or memberships with multiple renewal schedules.

boolean

required

Whether the membership is set to cancel when the current billing period ends. Only meaningful for recurring variants.

string | null

required

When cancellation was requested, or when the membership was canceled if no request time is recorded, as an ISO 8601 timestamp. null when neither is recorded.

string | null

required

Free-text explanation provided when canceling. null when no reason was provided.

string | null

required

How renewals are collected. charge_automatically charges the saved payment method each period; send_invoice emails the buyer an invoice each period. null when not set.Available options: charge_automatically, send_invoice

string

required

When the membership was created, as an ISO 8601 timestamp.

string | null

required

When the current billing period renews, or when a non-renewing membership expires, as an ISO 8601 timestamp. null for one-time purchases with no expiration.

string | null

required

When the current billing period started, as an ISO 8601 timestamp. null when no billing period is recorded.

string | null

required

When access ends for a membership with a fixed expiration, as an ISO 8601 timestamp. null when the membership has no expiration, such as a renewing membership.

object

required

The variant’s current up-front price, in the variant’s currency. A list price, not necessarily what the buyer paid. amount is "0.00" when the first charge is free.

Properties

string

required

The amount in major units, as an exact decimal string — "10.00" is ten dollars. A string so no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount CARRIES — the precision the charge itself runs at.

integer

required

string | null

required

The software license key for this membership. Only present when the product includes a software licensing experience.

string | null

required

URL where the buyer can sign in to manage billing. null without a member record or unless the caller is the buyer or has member:manage on the account.

object | null

required

The caller’s member row on the account. Present only when the membership belongs to the caller; null on seller-side reads.

Properties

string

required

What the member can reach on the account: customer for paying members, admin for team members, no_access once every grant has lapsed.Available options: no_access, admin, customer

string | null

required

When the member last opened the account’s content, as an ISO 8601 timestamp. null if they never have.

number | null

required

The member’s sort position in the buyer’s own account list. null until they arrange it.

string | null

required

The buyer’s member record on the account, prefixed mber_. null when the membership has no member record, such as an unclaimed membership.

object

required

Custom key-value pairs stored on the membership, commonly used for software licensing.

string | null

required

The membership’s latest lifecycle event, such as renewing_on or canceled_on. Pair it with most_recent_action_at. null when none is recorded.Available options: 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

string | null

required

When most_recent_action happened or is scheduled to happen, as an ISO 8601 timestamp. A future time for upcoming events such as renewing_on. null when no action is recorded.

string | null

required

The buyer’s phone number recorded for this membership, or null. The number collected (or verified) at checkout when the seller’s phone collection is on; falls back to the buyer’s account number when they have shared one with this seller.

string

required

The variant the buyer purchased, prefixed plan_.

object

required

The product this membership grants access to.

Properties

string

required

Product ID, prefixed prod_.

string | null

required

Product logo image URL. null when the product has no logo.

string

required

Product display name.

string

required

The product this membership grants access to, prefixed prod_.

The promo code discounting this membership, prefixed promo_. null when none is applied. Set at checkout or by Apply Promo Code to Membership.

object | null

required

What the next renewal charges, after any promo code that still applies. null for non-renewing memberships.

Properties

string

required

The amount in major units, as an exact decimal string — "10.00" is ten dollars. A string so no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount CARRIES — the precision the charge itself runs at.

integer

required

integer | null

required

Paid installments counted so far on a split pay membership. null when the membership is not on split pay, or before its first installment is counted.

integer | null

required

Installment payments required before the membership stops billing. null when the membership is not on split pay.

string

required

Billing state of the membership. active/trialing memberships grant access; past_due is the grace period after a failed payment; completed one-time purchases keep access; canceled/expired do not.Available options: trialing, active, past_due, completed, canceled, expired, unresolved

string

required

When the membership was last changed, as an ISO 8601 timestamp. Reflects the most recent change to the membership itself, so you can reconcile against webhook retries, replays, and backfills.

string | null

required

The buyer, prefixed user_. null when the buyer is another business or the membership is unclaimed.

Membership

{
	"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",
	"plan_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,
	"cancellation_reason": null,
	"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"
	}
}

​Endpoints

​Attributes

Endpoints

Attributes