Skip to main content
POST
Create Variant

Autorisations

Authorization
string
header
requis

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.

Scopes

plan:create

En-têtes

Idempotency-Key
string

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

Maximum string length: 255
Exemple:

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

Api-Version-Date
string

Pins the request to a dated API version.

Exemple:

"2026-11-17"

Corps

application/json
account_id
string

The unique identifier of the account to create this variant for. Required when authenticating as a user; an account API key supplies its own account.

Exemple:

"biz_xxxxxxxxxxxxxx"

adaptive_pricing_enabled
boolean | null

Whether this variant accepts local currency payments via adaptive pricing.

Exemple:

true

allow_multiple_quantity
boolean

Whether more than one unit can be purchased in an order. Renewal variants cannot enable it. When false, checkouts, carts, and invoices reject a quantity above 1.

attributes
object | null

Attribute values that make this variant one variant of its product, as a map of attribute name to value, e.g. {"size": "Large", "color": "Blue"}. Names are normalized to snake_case identifiers (Ring Size becomes ring_size) and come back in alphabetical order. Every variant on a product must carry the same attribute names and a distinct set of values. Send null to make the variant an ordinary pricing option again.

Exemple:
billing_period
integer | null

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

Exemple:

30

billing_type
string

Variant billing type, such as one_time or renewal.

Exemple:

"renewal"

cancel_discount_intervals
integer | null

How long the retention discount lasts: 0 forever, 1 the next payment only, or a number of calendar months from when the customer accepts it. Required when offer_cancel_discount is true.

Exemple:

3

cancel_discount_percentage
integer | null

Percentage taken off each discounted renewal, as a whole number from 1 to 100. Required when offer_cancel_discount is true.

Plage requise: 1 <= x <= 100
Exemple:

20

checkout_styling
object | null

Checkout styling overrides for this variant.

Exemple:
currency
string

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

Exemple:

"usd"

custom_fields
object[] | null

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

description
string | null

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

Exemple:

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

Exemple:

365

image
object | null

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

initial_price
number | null

Initial amount charged in the variant's currency, e.g. 10.43 for $10.43. A paid fiat variant charges at least 1.00 in its currency; use 0 for free.

Exemple:

0

internal_notes
string | null

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

Exemple:

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

metadata
object | null

Custom key-value pairs to store on the variant. 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 variant and are validated on save.

Exemple:
offer_cancel_discount
boolean | null

Whether to offer a retention discount when a customer attempts to cancel.

Exemple:

true

override_tax_type
string

Override the default tax classification for this specific variant.

Exemple:

"inclusive"

payment_method_configuration
object | null

Explicit payment method configuration for the variant. When not provided, the account's defaults apply. Send at least one of enabled or disabled; an omitted one is empty.

product_id
string

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

Exemple:

"prod_xxxxxxxxxxxxxx"

release_method
string

Sales method for this variant.

Exemple:

"buy_now"

renewal_price
number | null

The amount charged each billing period for recurring variants, in the variant's currency. A paid fiat variant charges at least 1.00 in its currency.

Exemple:

59

sku
string | null

Stock keeping unit for this variant. Maximum 100 characters. Free text, not enforced unique.

Exemple:

"TEE-LARGE-BLUE"

split_pay_required_payments
integer | null

Installment payments required before the subscription pauses, from 2 to 115. Only valid on renewal variants.

Plage requise: 2 <= x <= 115
Exemple:

4

stock
integer | null

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

Exemple:

25

three_ds_level
enum<string> | null

3D Secure behavior for supported on-session card payments. mandate_challenge requires a 3DS challenge before payment processing; mandate_if_required mandates a challenge only when the payment processor requires it; frictionless_if_required uses the regular frictionless 3DS flow. Payments of $1,000 or more use mandate_if_required unless mandate_challenge is selected. Risk and authentication recovery requirements can override the preference. Send null to inherit the account default.

Options disponibles:
mandate_challenge,
mandate_if_required,
frictionless_if_required,
null
Exemple:

"frictionless_if_required"

title
string | null

The display name of the variant shown to customers on the product page. Maximum 30 characters.

Maximum string length: 30
Exemple:

"Unlimited Wash Club"

trial_period_days
integer | null

Free trial duration before the first recurring charge.

Exemple:

7

unlimited_stock
boolean | null

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

Exemple:

false

visibility
string

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

Exemple:

"visible"

Réponse

variant created

account
object | null
requis

Account that sells this variant; null for standalone invoice variants.

adaptive_pricing_enabled
boolean
requis

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

Exemple:

true

allow_multiple_quantity
boolean
requis

Whether more than one unit can be purchased in an order. Renewal variants cannot enable it. When false, checkouts, carts, and invoices reject a quantity above 1.

Exemple:

false

attributes
object | null
requis

Attribute values that distinguish this variant within its product, as a map of attribute name to value, e.g. {"color": "Blue", "size": "Large"}. Names are snake_case identifiers and come back in alphabetical order. Every attributed variant on a product carries the same attribute names and a distinct set of values; the product lists the full option set as variant_attributes. null when the variant has no attributes.

Exemple:
billing_period
number | null
requis

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

Exemple:

30

billing_type
enum<string>
requis

Billing model for this variant.

Options disponibles:
renewal,
one_time
Exemple:

"renewal"

cancel_discount_intervals
number | null
requis

How long the cancellation discount lasts: 0 forever, 1 the next payment only, or a number of calendar months from when the customer accepts it. null when none is offered or the actor lacks the plan:basic:read scope.

Exemple:

3

cancel_discount_percentage
number | null
requis

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

Exemple:

20

checkout_styling
object | null
requis

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

Exemple:
collect_tax
boolean
requis

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

Exemple:

false

created_at
string
requis

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

Exemple:

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

currency
string
requis

Three-letter ISO 4217 code of the currency every price on this variant is stated in, lowercase: the variant's own currency, or the presentment_currency the read asked for when the variant can be converted into it.

Exemple:

"usd"

custom_fields
object[]
requis
deletable
boolean | null
requis

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

Exemple:

true

description
string | null
requis

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

Exemple:

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

effective_payment_method_configuration
object | null
requis

The configuration governing a checkout for this variant, resolved through every layer (the variant'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 variant's own editable override.

expiration_days
number | null
requis

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

Exemple:

365

formatted_price
string
requis

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

Exemple:

"$59.00 / month"

id
string
requis

Variant ID, prefixed plan_.

Exemple:

"plan_xxxxxxxxxxxxxx"

image
object | null
requis

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

Exemple:
initial_price
number
requis

Initial purchase price, in currency.

Exemple:

0

initial_price_due
object
requis

Total charged at checkout for one unit, before promo codes and tax: initial_price plus the first renewal_price for recurring variants, or initial_price alone while a free trial applies. The trial does not apply when the viewing user has already used one for this variant. Stated in currency.

internal_notes
string | null
requis

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

Exemple:

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

invoice
object | null
requis

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

Exemple:

null

member_count
number | null
requis

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

Exemple:

0

metadata
object | null
requis

Custom key-value pairs stored on the variant. 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 variant.

Exemple:
offer_cancel_discount
boolean | null
requis

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

Exemple:

true

payment_method_configuration
object | null
requis

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

Exemple:
product
object | null
requis

Product this variant belongs to; null for standalone variants.

Exemple:
purchase_url
string
requis

URL where customers can purchase this variant directly.

Exemple:

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

redirect_url
string | null
requis

Where the customer is sent after paying for this variant. null when none is set, or unless the actor has the plan:basic:read scope on the variant's account.

Exemple:

null

release_method
enum<string>
requis

Sales method for this variant.

Options disponibles:
buy_now,
waitlist
Exemple:

"buy_now"

renewal_price
number
requis

Recurring price charged every billing period, in currency.

Exemple:

59

sku
string | null
requis

Stock keeping unit, free text set by the seller (e.g. TSHIRT-LARGE-BLUE). Not enforced unique. null when unset.

Exemple:

"WASH-CLUB-TEE-LARGE-BLUE"

split_pay_required_payments
number | null
requis

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

Exemple:

4

stock
number | null
requis

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

Exemple:

0

strike_through_initial_price
number | null
requis

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

Exemple:

99

strike_through_renewal_price
number | null
requis

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

Exemple:

79

tax_type
enum<string>
requis

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

Options disponibles:
inclusive,
exclusive,
unspecified
Exemple:

"unspecified"

three_ds_level
enum<string> | null
requis

3D Secure behavior for supported on-session card payments. mandate_challenge requires a 3DS challenge before payment processing; mandate_if_required mandates a challenge only when the payment processor requires it; frictionless_if_required uses the regular frictionless 3DS flow. Payments of $1,000 or more use mandate_if_required unless mandate_challenge is selected. Risk and authentication recovery requirements can override the preference. null inherits the account default.

Options disponibles:
mandate_challenge,
mandate_if_required,
frictionless_if_required,
null
Exemple:

"frictionless_if_required"

title
string | null
requis

Variant display name shown to customers. Maximum 30 characters. A variant created without one defaults to its attribute values joined with /. null if no title has been set.

Exemple:

"Unlimited Wash Club"

trial_period_days
number | null
requis

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

Exemple:

7

unlimited_stock
boolean
requis

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

Exemple:

false

unpaid_invoice_count
integer | null
requis

Number of issued invoices for this variant that are not paid or void. While it is above 0, you can't change the variant's prices, billing period, trial, number of payments, currency or billing type. null unless the actor has the plan:basic:read scope on the variant's account.

Exemple:

0

updated_at
string
requis

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

Exemple:

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

visibility
enum<string>
requis

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

Options disponibles:
visible,
hidden,
archived,
quick_link
Exemple:

"visible"