Sign in

v8

OpenAPI 3.1.02026-08-033623795.0 MB
Promo codes

Create promo code

Create a new promo code that applies a discount at checkout. Can be scoped to specific products or plans.

Required permissions:

  • promo_code:create
  • access_pass:basic:read
post/promo_codes

Request body

amount_offnumber required

The discount amount. When promo_type is percentage, this is the percent off (e.g., 20 for 20% off). When promo_type is flat_amount, this is the currency amount off (e.g., 10.00 for $10.00 off).

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

The available currencies on the platform

churned_users_onlyboolean nullable

Whether to restrict this promo code to only users who have previously churned from the company.

codestring required

The alphanumeric code customers enter at checkout to apply the discount.

company_idstring required

The unique identifier of the company to create this promo code for.

existing_memberships_onlyboolean nullable

Whether this promo code can only be applied to existing memberships, such as for cancellation retention offers.

expires_atstring date-time nullable

The datetime when the promo code expires and can no longer be used. Null means it never expires.

new_users_onlyboolean required

Whether to restrict this promo code to only users who have never purchased from the company before.

one_per_customerboolean nullable

Whether each customer can only use this promo code once.

plan_idsstring[] nullable

The identifiers of plans this promo code applies to. When product_id is also provided, only plans attached to that product are included.

product_idstring nullable

The identifier of the product to scope this promo code to. When provided, the promo code only applies to plans attached to this product.

promo_duration_monthsinteger required

The number of billing months the discount remains active. For example, 3 means the discount applies to the first 3 billing cycles.

promo_type'percentage' | 'flat_amount' required

The type of promo code used to discount a plan

stockinteger nullable

The maximum number of times this promo code can be used. Ignored when unlimited_stock is true.

unlimited_stockboolean nullable

Whether the promo code can be used an unlimited number of times.

Example request

{
  "amount_off": 6.9,
  "company_id": "biz_xxxxxxxxxxxxxx",
  "expires_at": "2023-12-01T05:00:00.401Z",
  "product_id": "prod_xxxxxxxxxxxxx",
  "promo_duration_months": 42,
  "stock": 42
}

Response

A successful response

amount_offnumber required

The discount amount. Interpretation depends on promo_type: if 'percentage', this is the percentage (e.g., 20 means 20% off); if 'flat_amount', this is dollars off (e.g., 10.00 means $10.00 off).

churned_users_onlyboolean required

Restricts promo use to only users who have churned from the company before.

codestring nullable required

The specific code used to apply the promo at checkout.

created_atstring date-time required

The datetime the promo code was created.

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

The available currencies on the platform

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

The duration setting for the promo code

existing_memberships_onlyboolean required

Restricts promo use to only be applied to already purchased memberships.

expires_atstring date-time nullable required

The date/time of when the promo expires.

idstring required

The unique identifier for the promo code.

new_users_onlyboolean required

Restricts promo use to only users who have never purchased from the company before.

one_per_customerboolean required

Restricts promo use to only be applied once per customer.

promo_duration_monthsinteger nullable required

The number of months the promo is applied for.

promo_type'percentage' | 'flat_amount' required

The type of promo code used to discount a plan

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

Statuses for promo codes

stockinteger required

The quantity limit on the number of uses.

unlimited_stockboolean required

Whether or not the promo code has unlimited stock.

usesinteger required

The amount of times the promo codes has been used.

Example response

{
  "amount_off": 6.9,
  "company": {
    "id": "biz_xxxxxxxxxxxxxx"
  },
  "created_at": "2023-12-01T05:00:00.401Z",
  "expires_at": "2023-12-01T05:00:00.401Z",
  "id": "promo_xxxxxxxxxxxx",
  "product": {
    "id": "prod_xxxxxxxxxxxxx",
    "title": "Pickaxe Analytics"
  },
  "promo_duration_months": 42,
  "stock": 42,
  "uses": 42
}