Sign in

v9

OpenAPI 3.1.02026-08-043703845.2 MB
Promo Codes

Create Promo Code

Creates a promo code for an account. First-party sessions may attach an affiliate.

post/promo_codes

Headers

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

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

Request body

account_idstring required
amount_offnumber required
base_currency'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' required
churned_users_onlyboolean
codestring required
existing_memberships_onlyboolean
expires_atstring nullable
new_users_onlyboolean required
one_per_customerboolean
plan_idsstring[]
product_idstring nullable
promo_duration_monthsinteger required
promo_type'percentage' | 'flat_amount' required
stockinteger nullable
unlimited_stockboolean

Response

promo code created

amount_offnumber required

Discount amount. Percentage discounts are represented as a decimal fraction.

churned_users_onlyboolean required

Whether the promo code is restricted to churned customers.

codestring nullable required

Code entered at checkout.

created_atstring required

When the promo code was created, as an ISO 8601 timestamp.

currency'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' required

Currency used for a fixed-amount discount.

duration'forever' | 'once' | 'repeating' required

How long the discount applies.

existing_memberships_onlyboolean required

Whether the promo code applies only to existing memberships.

expires_atstring nullable required

When the promo code expires, as an ISO 8601 timestamp.

idstring required

Promo code ID, prefixed promo_.

metadataobject required

Custom key-value metadata stored on the promo code.

new_users_onlyboolean required

Whether the promo code is restricted to new customers.

one_per_customerboolean required

Whether each customer may redeem the promo code only once.

promo_duration_monthsinteger nullable required

Billing intervals the discount applies to.

promo_type'percentage' | 'flat_amount' required

Whether the discount is percentage-based or a fixed amount.

status'active' | 'inactive' | 'archived' required

Promo code lifecycle status.

stockinteger required

Maximum uses when stock is limited.

unlimited_stockboolean required

Whether the promo code has no redemption limit.

updated_atstring required

When the promo code was updated, as an ISO 8601 timestamp.

usesinteger required

Memberships that used the promo code.

Example response

{
  "currency": "usd",
  "duration": "forever",
  "promo_type": "percentage",
  "status": "active"
}