Skip to main content
POST
Apply Promo Code to Membership

Authorizations

Authorization
string
header
required

An Account API key, an App API key, an account access token, an account-scoped user token, or a user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************. See Auth & API keys for how to get each one.

Headers

Idempotency-Key
string

A unique key that makes this request safe to retry. See Idempotent requests.

Maximum string length: 255
Example:

"d9105228-4a08-46b1-8b91-42fed586d383"

Api-Version-Date
string

Pins the request to a dated API version.

Example:

"2026-09-29"

Path Parameters

id
string
required

Membership ID (mem_ tag).

Body

application/json
promo_code
string
required

The promo code to apply, as customers enter it at checkout (for example SAVE20).

Example:

"SAVE20"

Response

promo code applied

account
object
required

The account (seller) this membership belongs to.

billing_period_days
integer | null
required

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

Example:

30

cancel_at_period_end
boolean
required

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

Example:

true

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

Example:

"2026-01-01T12:00:00.000Z"

cancellation_reason
string | null
required

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

Example:

"Too expensive"

created_at
string
required

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

Example:

"2026-01-01T12:00:00.000Z"

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

Example:

"2026-01-01T12:00:00.000Z"

current_period_start
string | null
required

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

Example:

"2026-01-01T12:00:00.000Z"

id
string
required

Membership ID, prefixed mem_.

Example:

"mem_xxxxxxxxxxxxxx"

license_key
string | null
required

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

Example:

"WHOP-XXXX-XXXX-XXXX"

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

Example:

"https://whop.com/billing/manage/mber_xxxxxxxxxxxxxx"

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

metadata
object
required

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

Example:
phone_number
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.

Example:

"+xxxxxxxxxxx"

plan_id
string
required

The variant the buyer purchased, prefixed plan_.

Example:

"plan_xxxxxxxxxxxxxx"

product_id
string
required

The product this membership grants access to, prefixed prod_.

Example:

"prod_xxxxxxxxxxxxxx"

promo_code_id
string | null
required

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

Example:

"promo_xxxxxxxxxxxxxx"

status
enum<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
Example:

"active"

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

Example:

"2026-01-01T12:00:00.000Z"

user_id
string | null
required

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

Example:

"user_xxxxxxxxxxxxxx"