Skip to main content
GET
Get coupons

Understanding Coupons

Coupons define the structure and rules for discounts in your affiliate program. They specify:
  • Discount type (percentage or flat amount)
  • Discount value (e.g., 20% off or $10 off)
  • Duration (one-time, forever, or repeating for X months)
  • Restrictions (product limits, expiration dates, max redemptions)
Think of coupons as the “template” or “definition” of a discount. The actual codes that customers enter at checkout are promotional codes, which are linked to coupons.

Coupons vs Promotional Codes

  • Coupon: The discount definition (e.g., “20% off for 3 months”)
  • Promotional Code: The actual code string (e.g., “JOHN20”, “SAVE20”) that customers use
One coupon can have multiple promotional codes associated with it, allowing different affiliates to share the same discount structure with unique codes.

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 coupon's UUID. Returns a single coupon.

externalId
string

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

name
string

The coupon's name. Returns a single coupon.

Response

A single coupon when filtering by id, externalId or name (null if no match), otherwise every coupon in the program.

A discount definition. Promotional codes point at a coupon for their value.

id
string<uuid>

The coupon ID

name
string | null

Name of the coupon

externalId
string | null

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

couponType
enum<string>

Whether the discount is a percentage or a fixed amount

Available options:
PERCENTAGE,
FLAT
percentOff
number<float> | null

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

amountOff
number<float> | null

Fixed amount taken off. Used when couponType is FLAT.

currency
string | null

Currency for amountOff, for example USD

duration
enum<string>

How long the discount keeps applying to a subscription

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

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

maxRedemptions
integer | null

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

timesRedeemed
integer

How many times this coupon has been redeemed so far

couponCategory
enum<string>

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

Available options:
CUSTOMER,
PAYOUT
limitToProducts
boolean

Whether the coupon only applies to productIds

productIds
string[]

Products the coupon is restricted to

collectionIds
string[]

Collections the coupon is restricted to

valid
boolean

Whether the coupon can currently be redeemed

redeemBy
string<date-time> | null

Last date the coupon can be redeemed

integrationType
enum<string> | null

The billing provider this coupon is synced with

Available options:
NONE,
STRIPE,
CHARGEBEE,
PADDLE,
SHOPIFY,
WOOCOMMERCE,
ZYLVIE,
POLAR
affiliateProgramId
string<uuid>

The affiliate program this coupon belongs to

createdAt
string<date-time>

When the coupon was created

updatedAt
string<date-time>

When the coupon was last updated

promotionalCodes
object[]

Promotional codes that point at this coupon

autoCouponRule
object | null

Rule used to generate codes automatically for affiliates, if configured

Last modified on July 20, 2026