Sign in
Memberships

Assign Affiliate to Membership

Changed on

Assigns an affiliate to a membership and pays them the commission you set on its future payments; past payments are not recalculated. A user who is not yet an affiliate of your account becomes one, which also requires affiliate:create. Send a new commission_type or commission_value for the membership's current affiliate to change their commission; a membership that already has a different affiliate returns a conflict. Works for active or trialing memberships with one recurring variant that bill through Stripe or Whop's billing engine, and not for marketplace memberships, paused payments, or a scheduled cancellation. You cannot assign yourself.

post/memberships/{id}/assign_affiliate

Request

  • Base URL: https://api.whop.com/api/v1
  • URL: https://api.whop.com/api/v1/memberships/{id}/assign_affiliate
  • 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

commission_type'flat_fee' | 'percentage' required

Whether the commission is a percentage of each payment or a fixed amount per payment.

commission_valuenumber required

A whole number from 1 to 90 for percentage, or an amount greater than 1 in the membership currency for flat_fee. The payout cannot exceed 90% of the next renewal amount. Flat fees need matching billing and settlement currencies.

emailstring

Email address of the user to assign. Pass exactly one of user_id, email, or username.

user_idstring

The user to assign, prefixed user_. Pass exactly one of user_id, email, or username.

usernamestring

Whop username of the user to assign. Pass exactly one of user_id, email, or username.

Example request

{
  "commission_type": "percentage",
  "commission_value": 20,
  "email": "affiliate@example.com",
  "user_id": "user_xxxxxxxxxxxxx",
  "username": "affiliate"
}

Response

affiliate assigned

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