v1

latestOpenAPI 3.0.12026-08-062532117.6 KB

Create a coupon

Creates a coupon — the discount definition that promotional codes are built on.

Only name is required. Set couponType to PERCENTAGE and supply percentOff (1–100), or set it to FLAT and supply both amountOff and currency. When couponType is omitted the coupon is stored as PERCENTAGE, so send percentOff alongside it.

duration controls how long the discount keeps applying to a subscription: once, forever (the default here), or repeating — which additionally requires durationInMonths.

Fires the coupon.created webhook.

post/coupons

Request body

namestring required

Name of the coupon

couponType'PERCENTAGE' | 'FLAT'

Whether the discount is a percentage or a fixed amount

percentOffnumber float

Percentage taken off, 1–100. Required when couponType is PERCENTAGE.

amountOffnumber float

Fixed amount taken off. Required when couponType is FLAT.

currencystring

Currency for amountOff. Required when couponType is FLAT.

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

How long the discount keeps applying to a subscription

durationInMonthsinteger

Number of months the discount repeats for. Required when duration is repeating.

maxRedemptionsinteger

Total redemptions allowed across every promotional code on this coupon. Omit for unlimited.

limitToProductsboolean

Restrict the coupon to productIds

productIdsstring[]

Products the coupon applies to

validboolean

Whether the coupon can be redeemed straight away

redeemBystring date-time

Last date the coupon can be redeemed

externalIdstring

The coupon's ID in the connected billing provider. Must be unique.

The billing provider this coupon is synced with

Example request

{
  "name": "Launch 20%",
  "currency": "USD"
}

Response

The created coupon.

idstring uuid

The coupon ID

namestring nullable

Name of the coupon

externalIdstring nullable

The coupon's ID in the connected billing provider, for example a Stripe coupon ID

couponType'PERCENTAGE' | 'FLAT'

Whether the discount is a percentage or a fixed amount

percentOffnumber float nullable

Percentage taken off, 1–100. Used when couponType is PERCENTAGE.

amountOffnumber float nullable

Fixed amount taken off. Used when couponType is FLAT.

currencystring nullable

Currency for amountOff, for example USD

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

How long the discount keeps applying to a subscription

durationInMonthsinteger nullable

Number of months the discount repeats for. Only set when duration is repeating.

maxRedemptionsinteger nullable

Total redemptions allowed across every promotional code on this coupon. null means unlimited.

timesRedeemedinteger

How many times this coupon has been redeemed so far

couponCategory'CUSTOMER' | 'PAYOUT'

Whether the coupon discounts customers or is used to pay affiliates as a non-cash reward

limitToProductsboolean

Whether the coupon only applies to productIds

productIdsstring[]

Products the coupon is restricted to

collectionIdsstring[]

Collections the coupon is restricted to

validboolean

Whether the coupon can currently be redeemed

redeemBystring date-time nullable

Last date the coupon can be redeemed

The billing provider this coupon is synced with

affiliateProgramIdstring uuid

The affiliate program this coupon belongs to

createdAtstring date-time

When the coupon was created

updatedAtstring date-time

When the coupon was last updated

autoCouponRuleobject nullable

Rule used to generate codes automatically for affiliates, if configured