> ## 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 Promotional Codes

> Returns promotional codes based on the affiliate program. Promotional codes are the actual discount codes customers use at checkout.

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

If no parameters are provided, all promotional codes for your program are returned.


## OpenAPI

````yaml GET /promotional-codes
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:
  /promotional-codes:
    get:
      summary: Get all promotional codes or by ID/code/couponId/affiliateId
      description: >-
        Returns promotional codes based on the affiliate program. Promotional
        codes are the actual discount codes customers use at checkout.
      parameters:
        - name: id
          in: query
          description: The ID of the promotional code to retrieve
          schema:
            type: string
            format: uuid
        - name: code
          in: query
          description: The promotional code string to retrieve
          schema:
            type: string
        - name: externalId
          in: query
          description: The external ID (e.g., Stripe promotion code ID)
          schema:
            type: string
        - name: couponId
          in: query
          description: Get all promotional codes for a specific coupon
          schema:
            type: string
            format: uuid
        - name: affiliateId
          in: query
          description: Get all promotional codes for a specific affiliate
          schema:
            type: string
            format: uuid
        - name: affiliateEmail
          in: query
          description: Get all promotional codes for an affiliate by email
          schema:
            type: string
            format: email
      responses:
        '200':
          description: A list of promotional codes or a single promotional code
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PromotionalCode'
                  - type: array
                    items:
                      $ref: '#/components/schemas/PromotionalCode'
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    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
    Error:
      type: object
      properties:
        error:
          type: integer
          description: Error code
        message:
          type: string
          description: Error message
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````