Skip to main content
POST
Create a coupon

Authorizations

Authorization
string
header
required

Your account's secret key: Authorization: Bearer sk_test_… or sk_live_…. Server-side only.

Body

application/json

A new coupon's details.

code
string
required

Coupon code: 3 to 32 characters from uppercase letters, digits, _ and - (e.g. BLACKFRIDAY-20).

percentOff
string
required

Discount percentage, as a decimal string, above 0 and up to 100.

duration
enum<string>
required

once (first invoice only), repeating (for durationInCycles cycles) or forever (every invoice).

Available options:
once,
repeating,
forever
durationInCycles
integer | null

Required (1 or more) when duration is repeating; omit it otherwise.

maxRedemptions
integer | null

Total redemption limit. Omit for no limit.

redeemBy
string<date-time> | null

Deadline for applying the coupon. Omit for no deadline.

Response

Created.

A percentage discount the buyer applies at checkout with its code. On subscriptions, duration sets how many cycles the discount lasts.

id
string<uuid>
required
code
string
required

The code the buyer enters at checkout.

percentOff
string
required

Discount percentage, as a decimal string ("15" = 15%).

duration
enum<string>
required

once (first invoice only), repeating (for durationInCycles cycles) or forever (every invoice).

Available options:
once,
repeating,
forever
timesRedeemed
integer
required

How many times the coupon has been used.

status
enum<string>
required

active (accepted at checkout) or archived (no longer accepted).

Available options:
active,
archived
createdAt
string<date-time>
required
updatedAt
string<date-time>
required
durationInCycles
integer | null

How many cycles the discount lasts. Only on repeating coupons.

maxRedemptions
integer | null

How many times the coupon can be used in total. null = no limit.

redeemBy
string<date-time> | null

Last moment the coupon can be applied. null = no deadline.