Sign in
Memberships

Apply Promo Code to Membership

Changed on

Applies a promo code to an active or trialing membership that does not already have one and has exactly one recurring item, for Stripe-billed memberships and memberships billed by Whop's billing engine. The discount lands on the next invoice and follows the code's duration (once, repeating, or forever).

post/memberships/{id}/apply_promo_code

Request

  • Base URL: https://api.whop.com/api/v1
  • URL: https://api.whop.com/api/v1/memberships/{id}/apply_promo_code
  • Auth: HTTP bearer

Headers

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

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

Request body

promo_codestring required

The promo code to apply, as customers enter it at checkout (for example SAVE20). Its stock, variant eligibility, and expiry are checked as at checkout.

Example request

{
  "promo_code": "SAVE20"
}

Response

promo code applied

billing_period_daysinteger nullable required

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

cancel_at_period_endboolean required

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

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

cancellation_reasonstring nullable required

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

created_atstring required

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

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

current_period_startstring nullable required

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

idstring required

Membership ID, prefixed mem_.

license_keystring nullable required

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

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

metadataobject required

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

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

plan_idstring required

The variant the buyer purchased, prefixed plan_.

product_idstring required

The product this membership grants access to, prefixed prod_.

promo_code_idstring nullable required

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

status'trialing' | 'active' | 'past_due' | 'completed' | 'canceled' | 'expired' | 'unresolved' 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.

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

user_idstring nullable required

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

Example response

{
  "account": {
    "id": "biz_xxxxxxxxxxxxxx",
    "logo_url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "route": "shine-time-auto-detailing",
    "title": "Shine Time Auto Detailing"
  },
  "affiliate": {
    "applies_to_payments": "first_payment",
    "commission_amount": {
      "amount": "-1234.56",
      "currency": "usd",
      "decimals": 2,
      "display_decimals": 2
    },
    "commission_type": "flat_fee"
  },
  "billing_period_days": 30,
  "cancel_at_period_end": true,
  "canceled_at": "2026-01-01T12:00:00.000Z",
  "cancellation_reason": "Too expensive",
  "created_at": "2026-01-01T12:00:00.000Z",
  "current_period_end": "2026-01-01T12:00:00.000Z",
  "current_period_start": "2026-01-01T12:00:00.000Z",
  "id": "mem_xxxxxxxxxxxxxx",
  "license_key": "WHOP-XXXX-XXXX-XXXX",
  "manage_url": "https://whop.com/billing/manage/mber_xxxxxxxxxxxxxx",
  "member": {
    "access_level": "customer",
    "last_accessed_at": "2026-01-01T12:00:00.000Z",
    "position": 1767268800000
  },
  "metadata": {},
  "phone_number": "+xxxxxxxxxxx",
  "plan_id": "plan_xxxxxxxxxxxxxx",
  "product_id": "prod_xxxxxxxxxxxxxx",
  "promo_code_id": "promo_xxxxxxxxxxxxxx",
  "status": "active",
  "updated_at": "2026-01-01T12:00:00.000Z",
  "user_id": "user_xxxxxxxxxxxxxx"
}

Changes