Create Plan

Create a new pricing plan for a product. The plan defines the billing interval, price, and availability for customers.

POST /plans

JavaScript

JavaScript

import Whop from '@whop/sdk';

const client = new Whop({
  apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted
});

const plan = await client.plans.create();

console.log(plan.id);

200

{
  "account": {
    "id": "biz_xxxxxxxxxxxxxx",
    "title": "Shine Time Auto Detailing"
  },
  "adaptive_pricing_enabled": true,
  "billing_period": 30,
  "cancel_discount_intervals": 3,
  "cancel_discount_percentage": 20,
  "checkout_styling": {
    "background_color": "#0f172a",
    "border_style": "rounded",
    "button_color": "#f59e0b",
    "font_family": "roboto"
  },
  "collect_tax": false,
  "created_at": "2026-01-01T12:00:00.000Z",
  "currency": "usd",
  "custom_fields": [
    {
      "field_type": "text",
      "id": "field_xxxxxxxxxxxxxx",
      "name": "Vehicle make and model",
      "order": 0,
      "placeholder": "2021 Audi S5",
      "required": true
    }
  ],
  "deletable": true,
  "description": "Two hand washes a month, interior vacuum, and a quarterly sealant top-up.",
  "effective_payment_method_configuration": {
    "disabled": [
      "card"
    ],
    "enabled": [
      "card"
    ],
    "include_platform_defaults": true
  },
  "expiration_days": 365,
  "formatted_price": "$59.00 / month",
  "id": "plan_xxxxxxxxxxxxxx",
  "image": {
    "blurhash": "LA6bDXT$E3b:R6i+RibEIWbp%ej1",
    "url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  },
  "initial_price": 0,
  "internal_notes": "Maintenance tier. Upsell the interior shampoo add-on at renewal.",
  "invoice": {
    "id": "inv_xxxxxxxxxxxxxx"
  },
  "member_count": 0,
  "metadata": {
    "custom_cta": "subscribe",
    "custom_cta_url": "https://shinetime.example/wash-club"
  },
  "offer_cancel_discount": true,
  "payment_method_configuration": {
    "disabled": [
      "crypto"
    ],
    "enabled": [
      "card"
    ],
    "include_platform_defaults": true
  },
  "plan_type": "renewal",
  "product": {
    "id": "prod_xxxxxxxxxxxxxx",
    "title": "Ceramic Coating Package"
  },
  "purchase_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx",
  "release_method": "buy_now",
  "renewal_price": 59,
  "split_pay_required_payments": 4,
  "stock": 0,
  "strike_through_initial_price": 99,
  "strike_through_renewal_price": 79,
  "tax_type": "unspecified",
  "three_ds_level": "frictionless",
  "title": "Unlimited Wash Club",
  "trial_period_days": 7,
  "unlimited_stock": false,
  "updated_at": "2026-01-01T12:00:00.000Z",
  "visibility": "visible"
}

Authorizations

Authorization · string · header · required

An Account API key, account-scoped JWT, App API key, or user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************.

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-08-21"

Body

application/json

account_id · string

The unique identifier of the account to create this plan for. Defaults to the caller's account.

Example:

"biz_xxxxxxxxxxxxxx"

adaptive_pricing_enabled · boolean | null

Whether this plan accepts local currency payments via adaptive pricing.

Example:

true

billing_period · integer | null

Recurring billing interval in days, such as 30 for monthly or 365 for annual.

Example:

30

checkout_styling · object | null

Checkout styling overrides for this plan.

Example:

{
  "background_color": "#0f172a",
  "border_style": "rounded",
  "button_color": "#f59e0b",
  "font_family": "roboto"
}

currency · string

The three-letter ISO currency code for the plan's pricing. Defaults to USD.

Example:

"usd"

custom_fields · object[] | null

An array of custom field definitions to collect from customers at checkout. Omitting this field clears existing custom fields.

Show child attributes

description · string | null

A text description of the plan displayed to customers on the product page.

Example:

"Two hand washes a month, interior vacuum, and a quarterly sealant top-up."

expiration_days · integer | null

Access duration in days before the membership expires.

Example:

365

image · object | null

An image displayed on the product page to represent this plan.

Show child attributes

initial_price · number | null

Initial amount charged in the plan's currency, e.g. 10.43 for $10.43.

Example:

0

internal_notes · string | null

Private notes visible only to the account owner. Not shown to customers.

Example:

"Maintenance tier. Upsell the interior shampoo add-on at renewal."

metadata · object | null

Custom key-value pairs to store on the plan. Included in webhook payloads for payment and membership events. Max 50 keys, 100 chars per key, 500 chars per string value. The reserved keys custom_cta (a checkout call-to-action button label — one of the product custom CTA values, e.g. subscribe, get_offer) and custom_cta_url (a URL the button links to; web or tel:) override the product's call to action for this plan and are validated on save.

Example:

{
  "bay": "2",
  "custom_cta": "subscribe",
  "custom_cta_url": "https://shinetime.example/wash-club",
  "route": "north-austin"
}

override_tax_type · string

Override the default tax classification for this specific plan.

Example:

"inclusive"

payment_method_configuration · object | null

Explicit payment method configuration for the plan. When not provided, the account's defaults apply.

Show child attributes

plan_type · string

Plan billing type, such as one_time or renewal.

Example:

"renewal"

product_id · string

The unique identifier of the product to attach this plan to.

Example:

"prod_xxxxxxxxxxxxxx"

release_method · string

Sales method for this plan.

Example:

"buy_now"

renewal_price · number | null

The amount charged each billing period for recurring plans, in the plan's currency.

Example:

59

split_pay_required_payments · integer | null

Installment payments required before the subscription pauses.

Example:

4

stock · integer | null

The maximum number of units available for purchase. Ignored when unlimited_stock is true.

Example:

25

three_ds_level · enum<string> | null

3D Secure behavior for this plan. Send null to inherit the account default.

Available options: mandate_challenge, frictionless

Example:

"frictionless"

title · string | null

The display name of the plan shown to customers on the product page.

Example:

"Unlimited Wash Club"

trial_period_days · integer | null

Free trial duration before the first recurring charge.

Example:

7

unlimited_stock · boolean | null

Whether the plan has unlimited stock. When true, the stock field is ignored.

Example:

false

visibility · string

Whether the plan is visible to customers or hidden from public view.

Example:

"visible"

Response

200

application/json

plan created

account · object | null · required

Account that sells this plan; null for standalone invoice plans.

Show child attributes

adaptive_pricing_enabled · boolean · required

Whether adaptive pricing is enabled for this plan. Raw setting — does not check processor compatibility or feature flags.

Example:

true

billing_period · number | null · required

Number of days between recurring charges, such as 30 for monthly or 365 for annual. null for one-time plans.

Example:

30

cancel_discount_intervals · number | null · required

Billing intervals the cancellation discount applies to (0 forever, 1 first payment, or a month count). null when none is offered or the actor lacks the plan:basic:read scope.

Example:

3

cancel_discount_percentage · number | null · required

Cancellation discount as a whole-number percentage. null when none is offered or the actor lacks the plan:basic:read scope.

Example:

20

checkout_styling · object | null · required

Plan-level checkout styling (background_color, button_color, font_family, border_style); null inherits the account default.

Example:

{
  "background_color": "#0f172a",
  "border_style": "rounded",
  "button_color": "#f59e0b",
  "font_family": "roboto"
}

collect_tax · boolean · required

Whether tax is collected on purchases of this plan, based on the account's tax configuration.

Example:

false

created_at · string · required

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

Example:

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

currency · enum<string> · required

Three-letter ISO currency code for this plan's prices.

Available options: usd, sgd, inr, aud, brl, cad, dkk, eur, nok, gbp, sek, chf, hkd, huf, jpy, mxn, myr, pln, czk, nzd, aed, eth, ape, cop, ron, thb, bgn, idr, dop, php, try, krw, twd, vnd, pkr, clp, uyu, ars, zar, dzd, tnd, mad, kes, kwd, jod, all, xcd, amd, bsd, bhd, bob, bam, khr, crc, xof, egp, etb, gmd, ghs, gtq, gyd, ils, jmd, mop, mga, mur, mdl, mnt, nad, ngn, mkd, omr, pyg, pen, qar, rwf, sar, rsd, lkr, tzs, ttd, uzs, rub, btc, cny, usdt, kzt, awg, whop_usd, xau

Example:

"usd"

custom_fields · object[] · required

Show child attributes

deletable · boolean | null · required

Whether the plan can be deleted (it has no memberships or waitlist entries). null unless the actor has the plan:basic:read scope on the plan's account.

Example:

true

description · string | null · required

Customer-visible plan description. Maximum 1000 characters. null if no description is set.

Example:

"Two hand washes a month, interior vacuum, and a quarterly sealant top-up."

effective_payment_method_configuration · object | null · required

The configuration governing a checkout for this plan, resolved through every layer (the plan's own and the account's) — the shape a session's payment_method_configuration carries. Apply it over the payment method types catalogue for the offerable set. null means platform defaults; payment_method_configuration stays the plan's own editable override.

Show child attributes

expiration_days · number | null · required

Access duration in days for expiration-based plans, such as 365 for a one-year pass. null for plans without an expiration.

Example:

365

formatted_price · string · required

Human-readable price for display (currency + interval), e.g. "$10 / month".

Example:

"$59.00 / month"

id · string · required

Plan ID, prefixed plan_.

Example:

"plan_xxxxxxxxxxxxxx"

image · object | null · required

Pricing-tier image (url, blurhash) shown on the product page; null when no image is set.

Example:

{
  "blurhash": "LA6bDXT$E3b:R6i+RibEIWbp%ej1",
  "url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

initial_price · number · required

Initial purchase price in plan currency.

Example:

0

internal_notes · string | null · required

Private notes not shown to customers. null unless the actor has the plan:basic:read scope on the plan's account.

Example:

"Maintenance tier. Upsell the interior shampoo add-on at renewal."

invoice · object | null · required

Invoice this plan was generated for; null unless created for an invoice.

Example:

{ "id": "inv_xxxxxxxxxxxxxx" }

member_count · number | null · required

Active memberships through this plan. null unless the actor has the plan:basic:read scope on the plan's account.

Example:

0

metadata · object | null · required

Custom key-value pairs stored on the plan. Included in webhook payloads for payment and membership events. Maximum 50 keys, 100 characters per key, 500 characters per value. The reserved keys custom_cta and custom_cta_url, when set, override the product's checkout call to action for this plan.

Example:

{
  "custom_cta": "subscribe",
  "custom_cta_url": "https://shinetime.example/wash-club"
}

offer_cancel_discount · boolean | null · required

Whether a cancellation discount is offered. null unless the actor has the plan:basic:read scope on the plan's account.

Example:

true

payment_method_configuration · object | null · required

Payment method configuration (enabled, disabled, include_platform_defaults); null when plan uses default settings.

Example:

{
  "disabled": ["crypto"],
  "enabled": ["card"],
  "include_platform_defaults": true
}

plan_type · enum<string> · required

Billing model for this plan.

Available options: renewal, one_time

Example:

"renewal"

product · object | null · required

Product this plan belongs to; null for standalone plans.

Example:

{
  "id": "prod_xxxxxxxxxxxxxx",
  "title": "Ceramic Coating Package"
}

purchase_url · string · required

URL where customers can purchase this plan directly.

Example:

"https://whop.com/checkout/plan_xxxxxxxxxxxxxx"

release_method · enum<string> · required

Sales method for this plan.

Available options: buy_now, waitlist

Example:

"buy_now"

renewal_price · number · required

Recurring price charged every billing period.

Example:

59

split_pay_required_payments · number | null · required

Installment payments required before the subscription pauses. Must be greater than 1. null if split pay is not configured.

Example:

4

stock · number | null · required

Units available for purchase. null unless the actor has the plan:basic:read scope on the plan's account.

Example:

0

strike_through_initial_price · number | null · required

Original initial price shown with a strikethrough, in the plan's currency. null when no strikethrough is set.

Example:

99

strike_through_renewal_price · number | null · required

Original renewal price shown with a strikethrough, in the plan's currency. null when no strikethrough is set.

Example:

79

tax_type · enum<string> · required

How tax is handled for this plan, including whether tax is included in the price, added at checkout, or not configured.

Available options: inclusive, exclusive, unspecified

Example:

"unspecified"

three_ds_level · enum<string> | null · required

3D Secure behavior for this plan; null inherits the account default.

Available options: mandate_challenge, frictionless, null

Example:

"frictionless"

title · string | null · required

Plan display name shown to customers. Maximum 30 characters. null if no title has been set.

Example:

"Unlimited Wash Club"

trial_period_days · number | null · required

Free trial days before the first renewal charge. null if no trial is configured or the user has already used a trial for this plan.

Example:

7

unlimited_stock · boolean · required

Whether the plan has unlimited stock. When true, the stock field is ignored; waitlist plans always report true.

Example:

false

updated_at · string · required

When the plan was last updated, as an ISO 8601 timestamp.

Example:

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

visibility · enum<string> · required

Controls where this plan can be seen. When hidden, the plan is reachable only by its direct link.

Available options: visible, hidden, archived, quick_link

Example:

"visible"