Create a promotional code

Creates a promotional code against an existing coupon. couponId is always required — the coupon supplies the discount.

There are two ways to create a code:

Give it yourself. Send code with the exact string you want. It must be unique within the program.
Have it generated. Set isAutoGenerated to true and send codeStructure describing which pieces to combine — the affiliate's first name, last name, email prefix, the discount value, the coupon name, and/or random characters. An affiliate is required in this mode, and you can shape the result further with prefix, randomCharsLength and randomCharsCase.

Assign the code to an affiliate with affiliateId or affiliateEmail so their redemptions are tracked. Assigned codes are also connected to that affiliate's links automatically in the background.

Fires the promotional_code.created webhook.

Request body

couponIdstring uuid required

The coupon ID this promotional code belongs to

codestring

The exact code string customers will type. Required unless isAutoGenerated is true. Must be unique within the program.

affiliateIdstring uuid

Assign the code to this affiliate so their redemptions are credited. Required when isAutoGenerated is true unless affiliateEmail is supplied.

affiliateEmailstring email

Assign the code to the affiliate with this email address. Alternative to affiliateId.

externalIdstring

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

activeboolean

Whether the code is active (default: true)

expiresAtstring date-time

Expiration date

maxRedemptionsinteger

Maximum redemptions

firstTimeOrderboolean

Limit to first-time orders (default: false)

minimumAmountnumber float

Minimum purchase amount

minimumAmountCurrencystring

Currency for minimum amount

limitToCustomersboolean

Limit to specific customers (default: false)

customerIdstring

Specific customer ID

limitToAffiliateboolean

Only affiliate can use (default: false)

isAutoGeneratedboolean

Generate the code from codeStructure instead of using code. Requires an affiliate.

prefixstring

String placed at the front of a generated code

randomCharsLengthinteger

Length of random characters (default: 4)

randomCharsCase'uppercase' | 'lowercase' | 'mixed'

Case for random characters (default: mixed)

Example request

{
  "code": "JANE20"
}

Response

The created promotional code, with its parent coupon and assigned affiliate.

idstring uuid

The promotional code ID

codestring

The actual promotional code string

couponIdstring uuid

The parent coupon ID

affiliateIdstring uuid nullable

The affiliate ID this code is assigned to

externalIdstring nullable

External ID (e.g., Stripe promotion code ID)

activeboolean

Whether the promotional code is active

expiresAtstring date-time nullable

Expiration date for the code

maxRedemptionsinteger nullable

How many times this code can be redeemed. null means unlimited. Redemptions are also capped by the parent coupon's own limit.

timesRedeemedinteger

Number of times this code has been redeemed

firstTimeOrderboolean

Whether this code is limited to first-time orders

minimumAmountnumber float nullable

Minimum purchase amount required

minimumAmountCurrencystring nullable

Currency for minimum amount

limitToCustomersboolean

Whether code is limited to specific customers

customerIdstring nullable

Specific customer ID this code is limited to

limitToAffiliateboolean

Whether only the assigned affiliate may redeem this code

isAutoGeneratedboolean

Whether this code was generated from a codeStructure rather than supplied by hand

createdAtstring date-time

Timestamp when the code was created

updatedAtstring date-time

Timestamp when the code was last updated

isAffiliateGeneratedboolean

Whether the affiliate created this code themselves from their portal

v1

Create a promotional code

Request body

Example request

Response