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

# Create a Promotional Code

> Creates a new promotional code linked to a coupon. Supports both manual codes and auto-generated codes based on structure.

## Creating Promotional Codes

Create promotional codes that customers can use at checkout. Each promotional code must be linked to an existing coupon.

### Manual vs Auto-Generated Codes

#### Manual Codes

Specify the exact code string you want to create:

```json theme={null}
{
  "couponId": "coupon_123",
  "code": "SAVE20",
  "affiliateId": "affiliate_456"
}
```

#### Auto-Generated Codes

Let the system generate codes based on a structure:

```json theme={null}
{
  "couponId": "coupon_123",
  "affiliateId": "affiliate_456",
  "isAutoGenerated": true,
  "codeStructure": {
    "firstName": true,
    "randomChars": true
  },
  "prefix": "SAVE",
  "randomCharsLength": 4,
  "randomCharsCase": "uppercase"
}
```

This would generate a code like: `SAVEJOHN8X4Z`

### Code Structure Options

When using auto-generated codes, you can combine:

* **firstName**: Include affiliate's first name
* **lastName**: Include affiliate's last name
* **email**: Include part of affiliate's email (before @)
* **discountAmount**: Include the discount value
* **couponName**: Include the coupon name
* **randomChars**: Add random characters

### Additional Settings

* **active**: Whether the code is currently active
* **expiresAt**: Expiration date for the code
* **maxRedemptions**: Maximum number of times the code can be used
* **firstTimeOrder**: Limit to first-time customers only
* **minimumAmount**: Minimum purchase amount required
* **limitToAffiliate**: Only the affiliate can use this code
* **limitToCustomers**: Restrict to specific customers

<Note>
  The coupon must exist before creating promotional codes. The promotional code
  inherits its discount properties from the parent coupon.
</Note>


## OpenAPI

````yaml POST /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:
    post:
      summary: Create a new promotional code
      description: >-
        Creates a new promotional code linked to a coupon. Supports both manual
        codes and auto-generated codes based on structure.
      requestBody:
        description: Promotional code details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPromotionalCode'
        required: true
      responses:
        '200':
          description: Promotional code created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromotionalCode'
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    NewPromotionalCode:
      type: object
      required:
        - couponId
      properties:
        couponId:
          type: string
          format: uuid
          description: The coupon ID this promotional code belongs to
        code:
          type: string
          description: The promotional code string (required if not auto-generated)
        affiliateId:
          type: string
          format: uuid
          description: The affiliate ID to assign this code to
        affiliateEmail:
          type: string
          format: email
          description: The affiliate email (alternative to affiliateId)
        externalId:
          type: string
          description: External ID (e.g., Stripe promotion code ID)
        active:
          type: boolean
          description: 'Whether the code is active (default: true)'
        expiresAt:
          type: string
          format: date-time
          description: Expiration date
        maxRedemptions:
          type: integer
          description: Maximum redemptions
        firstTimeOrder:
          type: boolean
          description: 'Limit to first-time orders (default: false)'
        minimumAmount:
          type: number
          format: float
          description: Minimum purchase amount
        minimumAmountCurrency:
          type: string
          description: Currency for minimum amount
        limitToCustomers:
          type: boolean
          description: 'Limit to specific customers (default: false)'
        customerId:
          type: string
          description: Specific customer ID
        limitToAffiliate:
          type: boolean
          description: 'Only affiliate can use (default: false)'
        isAutoGenerated:
          type: boolean
          description: 'Whether to auto-generate the code (default: false)'
        codeStructure:
          type: object
          description: >-
            Structure for auto-generated codes (required if isAutoGenerated is
            true)
          properties:
            firstName:
              type: boolean
              description: Include affiliate's first name
            lastName:
              type: boolean
              description: Include affiliate's last name
            email:
              type: boolean
              description: Include part of affiliate's email
            discountAmount:
              type: boolean
              description: Include discount value
            couponName:
              type: boolean
              description: Include coupon name
            randomChars:
              type: boolean
              description: Add random characters
        prefix:
          type: string
          description: Prefix for auto-generated codes
        randomCharsLength:
          type: integer
          description: 'Length of random characters (default: 4)'
        randomCharsCase:
          type: string
          enum:
            - uppercase
            - lowercase
            - mixed
          description: 'Case for random characters (default: mixed)'
    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

````