Skip to main content
GET
Get promotional codes

Understanding Promotional Codes

Promotional codes are the actual discount codes that customers enter at checkout. Each promotional code is linked to a coupon, which defines the discount structure (amount, type, duration, etc.).

Key Concepts

  • Promotional codes are the customer-facing codes (e.g., “JOHN20”, “SAVE20”, “AFFILIATE10”)
  • They inherit their discount properties from the parent coupon
  • Multiple promotional codes can share the same coupon (same discount, different codes)
  • Each promotional code can be assigned to a specific affiliate for tracking

Query Options

You can retrieve promotional codes by:
  • id: Get a specific promotional code by ID
  • code: Get a promotional code by the actual code string
  • externalId: Get by external ID (e.g., Stripe promotion code ID)
  • couponId: Get all promotional codes for a specific coupon
  • affiliateId: Get all promotional codes for a specific affiliate
  • affiliateEmail: Get all promotional codes for an affiliate by email
If no parameters are provided, all promotional codes for your program are returned.

Authorizations

Authorization
string
header
required

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

Query Parameters

id
string<uuid>

The promotional code's UUID. Returns a single code.

code
string

The code string itself, for example JANE20. Returns a single code.

externalId
string

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

couponId
string<uuid>

Return every code belonging to this coupon.

affiliateId
string<uuid>

Return every code assigned to this affiliate UUID.

affiliateEmail
string<email>

Return every code assigned to the affiliate with this email address.

Response

A single promotional code when filtering by id, code or externalId (null if no match), otherwise an array.

A code customers enter at checkout. Its discount comes from the coupon it belongs to.

id
string<uuid>

The promotional code ID

code
string

The actual promotional code string

couponId
string<uuid>

The parent coupon ID

affiliateId
string<uuid> | null

The affiliate ID this code is assigned to

externalId
string | null

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

active
boolean

Whether the promotional code is active

expiresAt
string<date-time> | null

Expiration date for the code

maxRedemptions
integer | null

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

timesRedeemed
integer

Number of times this code has been redeemed

firstTimeOrder
boolean

Whether this code is limited to first-time orders

minimumAmount
number<float> | null

Minimum purchase amount required

minimumAmountCurrency
string | null

Currency for minimum amount

limitToCustomers
boolean

Whether code is limited to specific customers

customerId
string | null

Specific customer ID this code is limited to

limitToAffiliate
boolean

Whether only the assigned affiliate may redeem this code

isAutoGenerated
boolean

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

createdAt
string<date-time>

Timestamp when the code was created

updatedAt
string<date-time>

Timestamp when the code was last updated

coupon
object

The coupon this code takes its discount from

affiliate
object | null

Affiliate details

isAffiliateGenerated
boolean

Whether the affiliate created this code themselves from their portal

Last modified on July 20, 2026