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

# List Coupons

> The "List Coupons" API allows you to retrieve a list of all coupons available in your location. Use this endpoint to view all promotional offers and special discounts for your customers.



## OpenAPI

````yaml /api-reference/payments/openapi.json get /payments/coupon/list
openapi: 3.0.0
info:
  title: Payments API
  description: Documentation for payments API
  version: '1.0'
  contact: {}
servers:
  - url: https://services.leadconnectorhq.com
security: []
tags:
  - name: Payments
    description: Documentation for payments API
  - name: Integrations
    description: Documentation for payments API
  - name: Orders
    description: Documentation for payments API
  - name: Order fulfillments
    description: Documentation for payments API
  - name: Order Notes
    description: Documentation for payments API
  - name: Transactions
    description: Documentation for payments API
  - name: Subscriptions
    description: Documentation for payments API
  - name: Coupons
    description: Documentation for payments API
  - name: Custom Provider
    description: Documentation for payments API
paths:
  /payments/coupon/list:
    get:
      tags:
        - Coupons
      summary: List Coupons
      description: >-
        The "List Coupons" API allows you to retrieve a list of all coupons
        available in your location. Use this endpoint to view all promotional
        offers and special discounts for your customers.
      operationId: list-coupons
      parameters:
        - name: Version
          in: header
          description: API Version
          required: true
          schema:
            type: string
            enum:
              - '2021-07-28'
        - name: altId
          required: true
          in: query
          description: Location Id
          schema:
            example: BQdAwxa0ky1iK2sstLGJ
            type: string
        - name: altType
          required: true
          in: query
          description: Alt Type
          schema:
            example: location
            enum:
              - location
            type: string
        - name: limit
          required: false
          in: query
          description: Maximum number of coupons to return
          schema:
            default: 100
            example: 10
            type: number
        - name: offset
          required: false
          in: query
          description: Number of coupons to skip for pagination
          schema:
            default: 0
            example: 0
            type: number
        - name: status
          required: false
          in: query
          description: Filter coupons by status
          schema:
            example: active
            enum:
              - scheduled
              - active
              - expired
            type: string
        - name: search
          required: false
          in: query
          description: Search term to filter coupons by name or code
          schema:
            example: DEAL50
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCouponsResponseDto'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableDTO'
      security:
        - Location-Access:
            - payments/coupons.readonly
components:
  schemas:
    ListCouponsResponseDto:
      type: object
      properties:
        data:
          description: Array of coupon objects
          type: array
          items:
            $ref: '#/components/schemas/CouponDto'
        totalCount:
          type: number
          description: Total number of coupons matching the query criteria
          example: 20
        traceId:
          type: string
          description: Unique identifier for tracing this API request
          example: c667b18d-8f5e-44cf-a914
      required:
        - data
        - totalCount
        - traceId
    UnprocessableDTO:
      type: object
      properties:
        statusCode:
          type: number
          example: 422
        message:
          type: array
          items:
            type: string
          example:
            - Unprocessable Entity
        error:
          type: string
          example: Unprocessable Entity
      required:
        - statusCode
        - message
        - error
    CouponDto:
      type: object
      properties:
        _id:
          type: string
          description: Unique MongoDB identifier for the coupon
          example: 67f6c132d9485f9dacd5f123
        usageCount:
          type: number
          description: Number of times the coupon has been used
          example: 12
        limitPerCustomer:
          type: number
          description: >-
            Maximum number of times a customer can use this coupon (0 for
            unlimited)
          example: 5
        altId:
          type: string
          description: Location Id
          example: 79t07PzK8Tvf73d12312
        altType:
          type: string
          description: Type of entity
          example: location
        name:
          type: string
          description: Display name of the coupon
          example: NEWT6
        code:
          type: string
          description: Redemption code for the coupon
          example: NEWT6
        discountType:
          type: string
          description: Type of discount (percentage or amount)
          example: percentage
          enum:
            - percentage
            - amount
        discountValue:
          type: number
          description: Value of the discount (percentage or fixed amount)
          example: 25
        status:
          type: string
          description: Current status of the coupon
          example: scheduled
          enum:
            - scheduled
            - active
            - expired
        startDate:
          type: string
          description: Date when the coupon becomes active
          example: '2025-04-30T18:30:00.000Z'
        endDate:
          type: string
          description: End date when the coupon expires
          example: '2025-05-30T18:30:00.000Z'
        applyToFuturePayments:
          type: boolean
          description: Indicates if the coupon applies to future recurring payments
          example: true
        applyToFuturePaymentsConfig:
          $ref: '#/components/schemas/ApplyToFuturePaymentsConfigDto'
        userId:
          type: string
          description: User ID associated with the coupon (if applicable)
          example: q0m15dTLGeiGOXG123123
        createdAt:
          type: string
          description: Creation timestamp
          example: '2025-04-09T18:49:22.026Z'
        updatedAt:
          type: string
          description: Last update timestamp
          example: '2025-04-09T18:49:22.026Z'
      required:
        - _id
        - usageCount
        - limitPerCustomer
        - altId
        - altType
        - name
        - code
        - discountType
        - discountValue
        - status
        - startDate
        - applyToFuturePayments
        - applyToFuturePaymentsConfig
        - createdAt
        - updatedAt
    ApplyToFuturePaymentsConfigDto:
      type: object
      properties:
        type:
          type: string
          description: Type of future payments configuration
          example: fixed
          enum:
            - forever
            - fixed
        duration:
          type: number
          description: Duration value for fixed type configurations
          example: 3
        durationType:
          type: string
          description: Duration type for fixed configurations (e.g. months)
          example: months
      required:
        - type

````