--- title: "Get promotional codes" method: GET path: "/promotional-codes" --- # Get promotional codes `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](/api-reference/coupons/get) 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. ## Query parameters - `id` string, uuid - `code` string - `externalId` string - `couponId` string, uuid - `affiliateId` string, uuid - `affiliateEmail` string, email ## Response `200` A single promotional code when filtering by `id`, `code` or `externalId` (`null` if no match), otherwise an array. - union - PromotionalCode — 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, nullable — The affiliate ID this code is assigned to - `externalId` string, nullable — External ID (e.g., Stripe promotion code ID) - `active` boolean — Whether the promotional code is active - `expiresAt` string, date-time, nullable — Expiration date for the code - `maxRedemptions` integer, nullable — 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, nullable — Minimum purchase amount required - `minimumAmountCurrency` string, nullable — Currency for minimum amount - `limitToCustomers` boolean — Whether code is limited to specific customers - `customerId` string, nullable — 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` Coupon — A discount definition. Promotional codes point at a coupon for their value. - `id` string, uuid — The coupon ID - `name` string, nullable — Name of the coupon - `externalId` string, 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 - `percentOff` number, float, nullable — Percentage taken off, 1–100. Used when `couponType` is `PERCENTAGE`. - `amountOff` number, float, nullable — Fixed amount taken off. Used when `couponType` is `FLAT`. - `currency` string, nullable — Currency for `amountOff`, for example `USD` - `duration` 'once' | 'forever' | 'repeating' — How long the discount keeps applying to a subscription - `durationInMonths` integer, nullable — Number of months the discount repeats for. Only set when `duration` is `repeating`. - `maxRedemptions` integer, nullable — 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` 'CUSTOMER' | 'PAYOUT' — Whether the coupon discounts customers or is used to pay affiliates as a non-cash reward - `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, nullable — Last date the coupon can be redeemed - `integrationType` 'NONE' | 'STRIPE' | 'CHARGEBEE' | 'PADDLE' | 'SHOPIFY' | 'WOOCOMMERCE' | 'ZYLVIE' | 'POLAR', nullable — The billing provider this coupon is synced with - `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` PromotionalCode[] — Promotional codes that point at this coupon - `autoCouponRule` object, nullable — Rule used to generate codes automatically for affiliates, if configured - `affiliate` object, nullable — Affiliate details - `id` string, uuid - `firstName` string - `lastName` string - `email` string, email - `isAffiliateGenerated` boolean — Whether the affiliate created this code themselves from their portal - PromotionalCode[] - `id` string, uuid — The promotional code ID - `code` string — The actual promotional code string - `couponId` string, uuid — The parent coupon ID - `affiliateId` string, uuid, nullable — The affiliate ID this code is assigned to - `externalId` string, nullable — External ID (e.g., Stripe promotion code ID) - `active` boolean — Whether the promotional code is active - `expiresAt` string, date-time, nullable — Expiration date for the code - `maxRedemptions` integer, nullable — 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, nullable — Minimum purchase amount required - `minimumAmountCurrency` string, nullable — Currency for minimum amount - `limitToCustomers` boolean — Whether code is limited to specific customers - `customerId` string, nullable — 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` Coupon — A discount definition. Promotional codes point at a coupon for their value. - `id` string, uuid — The coupon ID - `name` string, nullable — Name of the coupon - `externalId` string, 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 - `percentOff` number, float, nullable — Percentage taken off, 1–100. Used when `couponType` is `PERCENTAGE`. - `amountOff` number, float, nullable — Fixed amount taken off. Used when `couponType` is `FLAT`. - `currency` string, nullable — Currency for `amountOff`, for example `USD` - `duration` 'once' | 'forever' | 'repeating' — How long the discount keeps applying to a subscription - `durationInMonths` integer, nullable — Number of months the discount repeats for. Only set when `duration` is `repeating`. - `maxRedemptions` integer, nullable — 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` 'CUSTOMER' | 'PAYOUT' — Whether the coupon discounts customers or is used to pay affiliates as a non-cash reward - `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, nullable — Last date the coupon can be redeemed - `integrationType` 'NONE' | 'STRIPE' | 'CHARGEBEE' | 'PADDLE' | 'SHOPIFY' | 'WOOCOMMERCE' | 'ZYLVIE' | 'POLAR', nullable — The billing provider this coupon is synced with - `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` PromotionalCode[] — Promotional codes that point at this coupon - `autoCouponRule` object, nullable — Rule used to generate codes automatically for affiliates, if configured - `affiliate` object, nullable — Affiliate details - `id` string, uuid - `firstName` string - `lastName` string - `email` string, email - `isAffiliateGenerated` boolean — Whether the affiliate created this code themselves from their portal ## Other responses - `401` — The `Authorization` header is missing, is not a `Bearer` header, or the token is not valid. - `403` — API access is not enabled for this account. - `404` — The affiliate program this token belongs to no longer exists. - `429` — Too many requests for this token on this endpoint. Please slow down. - `500` — The promotional codes could not be fetched. --- [API](https://skmtc.net/referly/apis/referly-api.md) · [All operations](https://skmtc.net/referly/apis/referly-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/referly/referly-api/revisions/0f506d61b9c3/schema)