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

> Creates a new coupon definition that can be used to generate promotional codes. Coupons define the discount structure.

## Creating Coupons

Create a new coupon definition that can be used to generate promotional codes for your affiliates.

### Coupon Types

* **PERCENTAGE**: Discount based on a percentage (e.g., 20% off)
* **FLAT**: Fixed amount discount (e.g., \$10 off)

### Duration Options

* **once**: Applies to a single payment
* **forever**: Applies to all future payments
* **repeating**: Applies for a specific number of months

<Note>
  After creating a coupon, you'll need to create promotional codes linked to
  this coupon. Promotional codes are the actual discount codes that customers
  will enter at checkout.
</Note>


## OpenAPI

````yaml POST /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:
    post:
      summary: Create a new coupon
      description: >-
        Creates a new coupon definition that can be used to generate promotional
        codes. Coupons define the discount structure.
      requestBody:
        description: Coupon details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCoupon'
        required: true
      responses:
        '200':
          description: Coupon created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Coupon'
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    NewCoupon:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the coupon
        externalId:
          type: string
          description: External ID (e.g., Stripe coupon ID)
        couponType:
          type: string
          enum:
            - PERCENTAGE
            - FLAT
          description: 'Type of discount - percentage or flat amount (default: PERCENTAGE)'
        percentOff:
          type: number
          format: float
          description: Percentage off (1-100) - required for percentage coupons
        amountOff:
          type: number
          format: float
          description: Amount off - required for flat coupons
        currency:
          type: string
          description: Currency (e.g., USD, EUR) - required for flat coupons
        duration:
          type: string
          enum:
            - once
            - forever
            - repeating
          description: 'How long the discount applies (default: forever)'
        durationInMonths:
          type: integer
          description: Number of months - required for repeating duration
        maxRedemptions:
          type: integer
          description: Maximum number of times this coupon can be redeemed
        limitToProducts:
          type: boolean
          description: 'Whether coupon is limited to specific products (default: false)'
        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 (default: true)'
        redeemBy:
          type: string
          format: date-time
          description: Date by which the coupon must be redeemed
        integrationType:
          type: string
          description: Integration type (e.g., stripe, custom)
    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

````