> ## Documentation Index > Fetch the complete documentation index at: https://www.referly.so/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## 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: >- REST API for managing affiliates, referrals, sales, affiliate links, coupons and promotional codes in your Referly affiliate program. Every request must send `Authorization: Bearer `. The token is scoped to a single affiliate program, so no program ID is ever required in the request — every read and write is automatically limited to that program. Requests are rate limited per token, per endpoint and per method. version: 1.0.0 servers: - url: https://www.referly.so/api/v1 security: - bearerAuth: [] paths: /promotional-codes: get: summary: Get promotional codes description: >- 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. parameters: - name: id in: query description: The promotional code's UUID. Returns a single code. schema: type: string format: uuid - name: code in: query description: The code string itself, for example `JANE20`. Returns a single code. schema: type: string - name: externalId in: query description: >- The code's ID in the connected billing provider, for example a Stripe promotion code ID. Returns a single code. schema: type: string - name: couponId in: query description: Return every code belonging to this coupon. schema: type: string format: uuid - name: affiliateId in: query description: Return every code assigned to this affiliate UUID. schema: type: string format: uuid - name: affiliateEmail in: query description: Return every code assigned to the affiliate with this email address. schema: type: string format: email responses: '200': description: >- A single promotional code when filtering by `id`, `code` or `externalId` (`null` if no match), otherwise an array. content: application/json: schema: oneOf: - $ref: '#/components/schemas/PromotionalCode' - type: array items: $ref: '#/components/schemas/PromotionalCode' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/ProgramNotFound' '429': $ref: '#/components/responses/RateLimited' '500': description: The promotional codes could not be fetched. 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: >- How many times this code can be redeemed. `null` means unlimited. Redemptions are also capped by the parent coupon's own limit. 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 assigned affiliate may redeem this code isAutoGenerated: type: boolean description: >- Whether this code was generated from a `codeStructure` rather than supplied by hand 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: description: The coupon this code takes its discount from allOf: - $ref: '#/components/schemas/Coupon' 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 isAffiliateGenerated: type: boolean description: Whether the affiliate created this code themselves from their portal description: >- A code customers enter at checkout. Its discount comes from the coupon it belongs to. Error: type: object properties: error: type: string description: Human readable description of what went wrong Coupon: type: object description: >- A discount definition. Promotional codes point at a coupon for their value. properties: id: type: string format: uuid description: The coupon ID name: type: string nullable: true description: Name of the coupon externalId: type: string nullable: true description: >- The coupon's ID in the connected billing provider, for example a Stripe coupon ID couponType: type: string enum: - PERCENTAGE - FLAT description: Whether the discount is a percentage or a fixed amount percentOff: type: number format: float nullable: true description: Percentage taken off, 1–100. Used when `couponType` is `PERCENTAGE`. amountOff: type: number format: float nullable: true description: Fixed amount taken off. Used when `couponType` is `FLAT`. currency: type: string nullable: true description: Currency for `amountOff`, for example `USD` duration: type: string enum: - once - forever - repeating description: How long the discount keeps applying to a subscription durationInMonths: type: integer nullable: true description: >- Number of months the discount repeats for. Only set when `duration` is `repeating`. maxRedemptions: type: integer nullable: true description: >- Total redemptions allowed across every promotional code on this coupon. `null` means unlimited. timesRedeemed: type: integer description: How many times this coupon has been redeemed so far couponCategory: type: string enum: - CUSTOMER - PAYOUT description: >- Whether the coupon discounts customers or is used to pay affiliates as a non-cash reward limitToProducts: type: boolean description: Whether the coupon only applies to `productIds` productIds: type: array items: type: string description: Products the coupon is restricted to collectionIds: type: array items: type: string description: Collections the coupon is restricted to valid: type: boolean description: Whether the coupon can currently be redeemed redeemBy: type: string format: date-time nullable: true description: Last date the coupon can be redeemed integrationType: type: string enum: - NONE - STRIPE - CHARGEBEE - PADDLE - SHOPIFY - WOOCOMMERCE - ZYLVIE - POLAR nullable: true description: The billing provider this coupon is synced with affiliateProgramId: type: string format: uuid description: The affiliate program this coupon belongs to createdAt: type: string format: date-time description: When the coupon was created updatedAt: type: string format: date-time description: When the coupon was last updated promotionalCodes: type: array items: $ref: '#/components/schemas/PromotionalCode' description: Promotional codes that point at this coupon autoCouponRule: type: object nullable: true description: >- Rule used to generate codes automatically for affiliates, if configured responses: Unauthorized: description: >- The `Authorization` header is missing, is not a `Bearer` header, or the token is not valid. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: API access is not enabled for this account. content: application/json: schema: $ref: '#/components/schemas/Error' ProgramNotFound: description: The affiliate program this token belongs to no longer exists. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Too many requests for this token on this endpoint. Please slow down. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer ````