Skip to main content
POST
JavaScript

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request body for creating a discount.

code is optional; if not provided, we generate a random 16-char code.

amount
integer<int32>
required

The discount amount in basis points (e.g. 540 means 5.4%, 10000 means 100%).

Must be at least 1.

type
enum<string>
required

The discount type: percentage or flat (flat_per_unit stays blocked).

Available options:
flat,
percentage
code
string | null

Optionally supply a code (will be uppercased).

  • Must be at least 3 characters if provided.
  • If omitted, a random 16-character code is generated.
currency_options
object[] | null

Per-currency options (flat deduction / percentage cap + minimum subtotal). Required for flat codes (must include a resolvable default); optional per-currency caps for percentage codes. Per-row invariants are checked in normalize_currency_options, not via #[validate(nested)].

customer_eligibility
null | enum<string>

Who may redeem this discount code. Defaults to any (unrestricted). specific starts with zero attached customers (fails closed) until customers are attached via POST /discounts/{id}/customers.

Available options:
any,
first_time,
existing,
specific
expires_at
string<date-time> | null

When the discount expires, if ever.

metadata
Metadata · object

Additional metadata for the discount

name
string | null
per_customer_usage_limit
integer<int32> | null

Maximum number of times a single customer may redeem this discount. Must be <= usage_limit when both are set.

preserve_on_plan_change
boolean

Whether this discount should be preserved when a subscription changes plans. Default: false (discount is removed on plan change)

restricted_to
string[] | null

List of product IDs to restrict usage (if any).

starts_at
string<date-time> | null

When the discount becomes active, if scheduled for the future. NULL = active immediately. Must be strictly before expires_at when both are set.

subscription_cycles
integer<int32> | null

Number of subscription billing cycles this discount is valid for. If not provided, the discount will be applied indefinitely to all recurring payments related to the subscription.

usage_limit
integer<int32> | null

How many times this discount can be used (if any). Must be >= 1 if provided.

Response

Created discount

amount
integer<int32>
required

The discount amount in basis points (e.g., 540 => 5.4%).

business_id
string
required

The business this discount belongs to.

code
string
required

The discount code (up to 16 chars).

created_at
string<date-time>
required

Timestamp when the discount is created

customer_eligibility
enum<string>
required

Who may redeem this discount code.

Available options:
any,
first_time,
existing,
specific
discount_id
string
required

The unique discount ID

metadata
Metadata · object
required

Arbitrary key-value metadata. Values can be string, integer, number, or boolean.

preserve_on_plan_change
boolean
required

Whether this discount should be preserved when a subscription changes plans. Default: false (discount is removed on plan change)

restricted_to
string[]
required

List of product IDs to which this discount is restricted.

times_used
integer<int32>
required

How many times this discount has been used.

type
enum<string>
required

The type of discount (percentage or flat).

Available options:
flat,
percentage
currency_options
object[]

Per-currency options (flat deduction / percentage cap + minimum subtotal). Empty for discounts without any configured currency options.

expires_at
string<date-time> | null

Optional date/time after which discount is expired.

name
string | null

Name for the Discount

per_customer_usage_limit
integer<int32> | null

Maximum number of times a single customer may redeem this discount, if any.

starts_at
string<date-time> | null

Optional date/time before which the discount is not yet active. NULL = active immediately.

subscription_cycles
integer<int32> | null

Number of subscription billing cycles this discount is valid for. If not provided, the discount will be applied indefinitely to all recurring payments related to the subscription.

usage_limit
integer<int32> | null

Usage limit for this discount, if any.

Last modified on March 25, 2026