> ## Documentation Index
> Fetch the complete documentation index at: https://developers.referly.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Coupons

> Returns coupons based on the affiliate program. Coupons define the discount structure (amount, type, duration) that promotional codes will use.

## 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.


## OpenAPI

````yaml GET /coupons
openapi: 3.0.1
info:
  title: Referly API
  description: API for managing affiliates, referrals, and sales for SaaS businesses
  version: 1.0.0
servers:
  - url: https://www.referly.so/api/v1
security:
  - bearerAuth: []
paths:
  /coupons:
    get:
      summary: Get all coupons or by ID/externalId/name
      description: >-
        Returns coupons based on the affiliate program. Coupons define the
        discount structure (amount, type, duration) that promotional codes will
        use.
      parameters:
        - name: id
          in: query
          description: The ID of the coupon to retrieve
          schema:
            type: string
            format: uuid
        - name: externalId
          in: query
          description: The external ID of the coupon (e.g., Stripe coupon ID)
          schema:
            type: string
        - name: name
          in: query
          description: The name of the coupon to retrieve
          schema:
            type: string
      responses:
        '200':
          description: A list of coupons or a single coupon
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Coupon'
                  - type: array
                    items:
                      $ref: '#/components/schemas/Coupon'
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Coupon:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The coupon ID
        name:
          type: string
          description: Name of the coupon
        externalId:
          type: string
          nullable: true
          description: External ID (e.g., Stripe coupon ID)
        couponType:
          type: string
          enum:
            - PERCENTAGE
            - FLAT
          description: Type of discount - percentage or flat amount
        percentOff:
          type: number
          format: float
          nullable: true
          description: Percentage off (1-100) for percentage coupons
        amountOff:
          type: number
          format: float
          nullable: true
          description: Amount off for flat coupons
        currency:
          type: string
          nullable: true
          description: Currency for flat amount coupons (e.g., USD, EUR)
        duration:
          type: string
          enum:
            - once
            - forever
            - repeating
          description: How long the discount applies
        durationInMonths:
          type: integer
          nullable: true
          description: Number of months for repeating duration
        maxRedemptions:
          type: integer
          nullable: true
          description: Maximum number of times this coupon can be redeemed
        limitToProducts:
          type: boolean
          description: Whether coupon is limited to specific products
        productIds:
          type: array
          items:
            type: string
          description: Array of product IDs this coupon applies to
        valid:
          type: boolean
          description: Whether the coupon is currently valid
        redeemBy:
          type: string
          format: date-time
          nullable: true
          description: Date by which the coupon must be redeemed
        integrationType:
          type: string
          nullable: true
          description: Integration type (e.g., stripe, custom)
        affiliateProgramId:
          type: string
          format: uuid
          description: The affiliate program ID
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the coupon was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the coupon was last updated
        promotionalCodes:
          type: array
          items:
            $ref: '#/components/schemas/PromotionalCode'
          description: Promotional codes associated with this coupon
    Error:
      type: object
      properties:
        error:
          type: integer
          description: Error code
        message:
          type: string
          description: Error message
    PromotionalCode:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The promotional code ID
        code:
          type: string
          description: The actual promotional code string
        couponId:
          type: string
          format: uuid
          description: The parent coupon ID
        affiliateId:
          type: string
          format: uuid
          nullable: true
          description: The affiliate ID this code is assigned to
        externalId:
          type: string
          nullable: true
          description: External ID (e.g., Stripe promotion code ID)
        active:
          type: boolean
          description: Whether the promotional code is active
        expiresAt:
          type: string
          format: date-time
          nullable: true
          description: Expiration date for the code
        maxRedemptions:
          type: integer
          nullable: true
          description: Maximum number of times this code can be used
        timesRedeemed:
          type: integer
          description: Number of times this code has been redeemed
        firstTimeOrder:
          type: boolean
          description: Whether this code is limited to first-time orders
        minimumAmount:
          type: number
          format: float
          nullable: true
          description: Minimum purchase amount required
        minimumAmountCurrency:
          type: string
          nullable: true
          description: Currency for minimum amount
        limitToCustomers:
          type: boolean
          description: Whether code is limited to specific customers
        customerId:
          type: string
          nullable: true
          description: Specific customer ID this code is limited to
        limitToAffiliate:
          type: boolean
          description: Whether only the affiliate can use this code
        isAutoGenerated:
          type: boolean
          description: Whether this code was auto-generated
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the code was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the code was last updated
        coupon:
          $ref: '#/components/schemas/Coupon'
          description: The parent coupon details
        affiliate:
          type: object
          nullable: true
          properties:
            id:
              type: string
              format: uuid
            firstName:
              type: string
            lastName:
              type: string
            email:
              type: string
              format: email
          description: Affiliate details
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````