Skip to main content

A plan defines pricing and billing terms for a checkout. Plans can optionally belong to a product, where they represent different pricing options such as one-time payments, recurring subscriptions, or free trials.

​
id
string
required

The unique identifier for the plan.

Example:

"plan_xxxxxxxxxxxxx"

​
created_at
string<date-time>
required

The datetime the plan was created.

Example:

"2023-12-01T05:00:00.401Z"

​
updated_at
string<date-time>
required

The datetime the plan was last updated.

Example:

"2023-12-01T05:00:00.401Z"

​
visibility
enum<string>
required

Controls whether the plan is visible to customers. When set to 'hidden', the plan is only accessible via direct link.

Available options:
visible,
hidden,
archived,
quick_link
​
plan_type
enum<string>
required

The billing model for this plan: 'renewal' for recurring subscriptions or 'one_time' for single payments.

Available options:
renewal,
one_time
​
release_method
enum<string>
required

The method used to sell this plan: 'buy_now' for immediate purchase or 'waitlist' for waitlist-based access.

Available options:
buy_now,
waitlist
​
currency
enum<string>
required

The currency used for all prices on this plan (e.g., 'usd', 'eur'). All monetary amounts on the plan are denominated in this currency.

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
​
company
object
required

The company that sells this plan. Null for standalone invoice plans not linked to a company.

​
product
object
required

The product that this plan belongs to. Null for standalone one-off purchases not linked to a product.

​
invoice
object
required

The invoice this plan was generated for. Null if the plan was not created for a specific invoice.

​
billing_period
integer | null
required

The number of days between each recurring charge. Null for one-time plans. For example, 30 for monthly or 365 for annual billing.

Example:

42

​
title
string | null
required

The display name of the plan shown to customers on the product page and at checkout. Maximum 30 characters. Null if no title has been set.

Example:

"Pro Monthly"

​
description
string | null
required

A text description of the plan visible to customers. Maximum 500 characters. Null if no description is set.

Example:

"Monthly access to all premium analytics dashboards and data exports."

​
purchase_url
string
required

The full URL where customers can purchase this plan directly, bypassing the product page.

Example:

"https://whop.com/pickaxe-analytics/checkout/plan_abc123"

​
expiration_days
integer | null
required

The number of days until the membership expires (for expiration-based plans). For example, 365 for a one-year access pass.

Example:

42

​
initial_price
number
required

The initial purchase price in the plan's base_currency (e.g., 49.99 for $49.99). For one-time plans, this is the full price. For renewal plans, this is charged on top of the first renewal_price.

Example:

6.9

​
renewal_price
number
required

The recurring price charged every billing_period in the plan's base_currency (e.g., 9.99 for $9.99/period). Zero for one-time plans.

Example:

6.9

​
trial_period_days
integer | null
required

The number of free trial days before the first charge on a renewal plan. Null if no trial is configured or the current user has already used a trial for this plan.

Example:

42

​
member_count
integer | null
required

The number of users who currently hold an active membership through this plan. Only visible to authorized team members.

Example:

42

​
internal_notes
string | null
required

Private notes visible only to the company owner and team members. Not shown to customers. Null if no notes have been added.

Example:

"Black Friday 2024 promo plan - expires Dec 1"

​
stock
integer | null
required

The number of units available for purchase. Only visible to authorized team members. Null if the requester lacks permission.

Example:

42

​
unlimited_stock
boolean
required

When true, the plan has unlimited stock (stock field is ignored). When false, purchases are limited by the stock field.

​
split_pay_required_payments
integer | null
required

The total number of installment payments required before the subscription pauses. Null if split pay is not configured. Must be greater than 1.

Example:

42

​
payment_method_configuration
object
required

The explicit payment method configuration specifying which payment methods are enabled or disabled for this plan. Null if the plan uses default settings.

​
tax_type
enum<string>
required

How tax is handled for this plan: 'inclusive' (tax included in price), 'exclusive' (tax added at checkout), or 'unspecified' (tax not configured).

Available options:
inclusive,
exclusive,
unspecified
​
collect_tax
boolean
required

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

​
custom_fields
object[]
required

Custom input fields displayed on the checkout form that collect additional information from the buyer.