---
title: "Get coupons"
method: GET
path: "/coupons"
---

# Get coupons

`GET /coupons`

Returns coupons for your program. A coupon defines the discount itself — how much comes off, in what currency, and for how long. The codes customers actually type at checkout are [promotional codes](/api-reference/promotional-codes/get), which each point at a coupon.

Filter with `id`, `externalId` or `name` for a single coupon. With no parameters, every coupon in the program is returned, newest first.

Each coupon comes back with its `promotionalCodes` (including the affiliate each is assigned to) and its `autoCouponRule` if one is configured.

## Query parameters

- `id` string, uuid
- `externalId` string
- `name` string

## Response `200`

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

- union
  - 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
      - `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 — recursive
      - `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
    - `autoCouponRule` object, nullable — Rule used to generate codes automatically for affiliates, if configured
  - Coupon[]
    - `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
      - `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 — recursive
      - `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
    - `autoCouponRule` object, nullable — Rule used to generate codes automatically for affiliates, if configured

## 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 coupons 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)