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

# List Coupons

> List coupons with name search and page-number pagination



## OpenAPI

````yaml get /v1/coupons
openapi: 3.1.1
info:
  title: HitPay API
  description: >-
    Accept PayNow, FPX, GrabPay, cards, and 40+ payment methods with a single
    API. Production base URL: https://api.hit-pay.com, Sandbox:
    https://api.sandbox.hit-pay.com
  version: '1.0'
servers:
  - url: https://api.hit-pay.com
    description: Production
  - url: https://api.sandbox.hit-pay.com
    description: Sandbox
security: []
paths:
  /v1/coupons:
    get:
      summary: List Coupons
      description: >-
        List the business's coupons, newest first. Uses page-number pagination.
        List items don't include `applies_to_ids`; get a single coupon for
        those.
      operationId: get-all-coupons
      parameters:
        - name: X-BUSINESS-API-KEY
          in: header
          required: true
          style: simple
          explode: false
          schema:
            type: string
            example: b286daabf9921b5a01a4621f026c111e046f8911feba212996c92159b98427d
        - name: keywords
          in: query
          description: Filter by coupon name (partial match).
          schema:
            type: string
        - name: per_page
          in: query
          description: >-
            Coupons per page, from 1 to 100. Values outside that range are
            clamped.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: page
          in: query
          description: Page number.
          schema:
            type: integer
            minimum: 1
            default: 1
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CouponListItem'
                  links:
                    type: object
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      from:
                        type:
                          - integer
                          - 'null'
                      last_page:
                        type: integer
                      path:
                        type: string
                      per_page:
                        type: integer
                      to:
                        type:
                          - integer
                          - 'null'
                      total:
                        type: integer
              examples:
                Result:
                  value:
                    data:
                      - id: a304f0fd-4ebb-4a8f-bc90-c7341f90080c
                        business_id: 98567029-f559-49f9-916b-042a4255b32a
                        name: Year End Sale
                        code: YEAREND10
                        fixed_amount: 500
                        percentage: 0
                        coupons_left: 100
                        is_promo_banner: false
                        banner_text: null
                        created_at: '2026-10-19T13:23:03.000000Z'
                        updated_at: '2026-10-19T13:23:03.000000Z'
                        starts_at: '2026-10-31T16:00:00.000000Z'
                        ends_at: '2026-12-30T16:00:00.000000Z'
                        coupon_type: 2
                        minimum_cart_amount: 2000
                        deleted_at: null
                    links:
                      first: https://api.sandbox.hit-pay.com/v1/coupons?page=1
                      last: https://api.sandbox.hit-pay.com/v1/coupons?page=1
                      prev: null
                      next: null
                    meta:
                      current_page: 1
                      from: 1
                      last_page: 1
                      path: https://api.sandbox.hit-pay.com/v1/coupons
                      per_page: 10
                      to: 1
                      total: 1
      deprecated: false
components:
  schemas:
    CouponListItem:
      type: object
      description: A coupon as returned by the list endpoint (no `applies_to_ids`).
      properties:
        id:
          type: string
          format: uuid
        business_id:
          type: string
          format: uuid
        name:
          type: string
        code:
          type: string
        fixed_amount:
          type: integer
          description: Fixed discount in minor units (cents).
        percentage:
          type: number
          description: Percentage discount as a fraction (`0.15` = 15%).
        coupons_left:
          type:
            - integer
            - 'null'
          description: Remaining uses; `null` = unlimited.
        is_promo_banner:
          type: boolean
        banner_text:
          type:
            - string
            - 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        starts_at:
          type:
            - string
            - 'null'
          format: date-time
          description: UTC.
        ends_at:
          type:
            - string
            - 'null'
          format: date-time
          description: UTC.
        coupon_type:
          type: integer
          enum:
            - 1
            - 2
            - 3
        minimum_cart_amount:
          type: integer
          description: Minimum cart amount in minor units (cents).
        deleted_at:
          type:
            - string
            - 'null'
          format: date-time

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.