Get Promotional Codes
Returns promotional codes for your program. A promotional code is the string a customer types at checkout; it inherits its discount from the coupon it belongs to, and can be assigned to an affiliate so redemptions are credited to them.
id, code and externalId return a single code. couponId, affiliateId and affiliateEmail return every matching code, newest first. With no parameters, every code in the program is returned.
Each code comes back with its parent coupon and the affiliate it is assigned to.
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
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
The promotional code's UUID. Returns a single code.
The code string itself, for example JANE20. Returns a single code.
The code's ID in the connected billing provider, for example a Stripe promotion code ID. Returns a single code.
Return every code belonging to this coupon.
Return every code assigned to this affiliate UUID.
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.
- object
- object[]
A code customers enter at checkout. Its discount comes from the coupon it belongs to.
The promotional code ID
The actual promotional code string
The parent coupon ID
The affiliate ID this code is assigned to
External ID (e.g., Stripe promotion code ID)
Whether the promotional code is active
Expiration date for the code
How many times this code can be redeemed. null means unlimited. Redemptions are also capped by the parent coupon's own limit.
Number of times this code has been redeemed
Whether this code is limited to first-time orders
Minimum purchase amount required
Currency for minimum amount
Whether code is limited to specific customers
Specific customer ID this code is limited to
Whether only the assigned affiliate may redeem this code
Whether this code was generated from a codeStructure rather than supplied by hand
Timestamp when the code was created
Timestamp when the code was last updated
The coupon this code takes its discount from
Affiliate details
Whether the affiliate created this code themselves from their portal