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

# List promotion codes

> Lists promotion codes. Filter by program, partner or type, and page with cursors.



## OpenAPI

````yaml /api-reference/openapi.json get /v2/promotion-codes
openapi: 3.1.0
info:
  title: Tolt Public API
  version: 2.0.0
servers:
  - url: https://platform.tolt.dev
    description: Development
security:
  - bearerAuth: []
paths:
  /v2/promotion-codes:
    get:
      tags:
        - PromotionCodes
      summary: List promotion codes
      description: >-
        Lists promotion codes. Filter by program, partner or type, and page with
        cursors.
      operationId: listPromotionCodes
      parameters:
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            description: How many rows to return in one page.
          required: false
          description: How many rows to return in one page.
          name: limit
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
            description: >-
              Ranking direction: desc puts the most recently created or updated
              rows first.
          required: false
          description: >-
            Ranking direction: desc puts the most recently created or updated
            rows first.
          name: order
          in: query
        - schema:
            type: string
            enum:
              - created_at
              - updated_at
            default: created_at
            description: >-
              Timestamp to order and page by: created_at follows creation order,
              updated_at follows each item's most recent change.
          required: false
          description: >-
            Timestamp to order and page by: created_at follows creation order,
            updated_at follows each item's most recent change.
          name: sort
          in: query
        - schema:
            type: string
            description: >-
              Continue after a position: the next_cursor of a previous page, or
              an item id when sorting by created_at. Cannot be combined with
              ending_before.
          required: false
          description: >-
            Continue after a position: the next_cursor of a previous page, or an
            item id when sorting by created_at. Cannot be combined with
            ending_before.
          name: starting_after
          in: query
        - schema:
            type: string
            description: >-
              Page backward from a position: the prev_cursor of a previous page,
              or an item id when sorting by created_at. Cannot be combined with
              starting_after.
          required: false
          description: >-
            Page backward from a position: the prev_cursor of a previous page,
            or an item id when sorting by created_at. Cannot be combined with
            starting_after.
          name: ending_before
          in: query
        - schema:
            type: string
            format: date-time
            description: >-
              Start of a window on when items were created: items created at
              this time or later are included, for example 2026-01-01T00:00:00Z.
              Leave it out for no lower bound.
          required: false
          description: >-
            Start of a window on when items were created: items created at this
            time or later are included, for example 2026-01-01T00:00:00Z. Leave
            it out for no lower bound.
          name: created_after
          in: query
        - schema:
            type: string
            format: date-time
            description: >-
              End of a window on when items were created: only items created
              before this time are included. Leave it out for no upper bound.
          required: false
          description: >-
            End of a window on when items were created: only items created
            before this time are included. Leave it out for no upper bound.
          name: created_before
          in: query
        - schema:
            type: string
            format: date-time
            description: >-
              Only items last changed at or after this moment; with
              sort=updated_at, use it to fetch what changed since a previous
              sync.
          required: false
          description: >-
            Only items last changed at or after this moment; with
            sort=updated_at, use it to fetch what changed since a previous sync.
          name: updated_after
          in: query
        - schema:
            type: string
            format: date-time
            description: >-
              Only items last changed before this moment; pair it with
              updated_after to fetch what changed in a period.
          required: false
          description: >-
            Only items last changed before this moment; pair it with
            updated_after to fetch what changed in a period.
          name: updated_before
          in: query
        - schema:
            type: string
            description: >-
              Limit to one program, by its id (prg_...) as returned when listing
              programs.
          required: false
          description: >-
            Limit to one program, by its id (prg_...) as returned when listing
            programs.
          name: program_id
          in: query
        - schema:
            type: string
            description: >-
              Limit to one partner, by its id (part_...) as returned when
              listing partners.
          required: false
          description: >-
            Limit to one partner, by its id (part_...) as returned when listing
            partners.
          name: partner_id
          in: query
        - schema:
            type: string
            enum:
              - fixed
              - percentage
            description: >-
              Only codes giving this kind of discount: a fixed amount off or a
              percentage off.
          required: false
          description: >-
            Only codes giving this kind of discount: a fixed amount off or a
            percentage off.
          name: type
          in: query
        - schema:
            type: string
            maxLength: 255
            description: Text matched anywhere in the code, ignoring case.
          required: false
          description: Text matched anywhere in the code, ignoring case.
          name: search
          in: query
      responses:
        '200':
          description: A page of promotion codes
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Request successful
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PromotionCode'
                  has_more:
                    type: boolean
                    example: false
                  next_cursor:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Opaque cursor marking the last item on this page. Pass it
                      as starting_after to continue. Null when the page is
                      empty.
                  prev_cursor:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Opaque cursor marking the first item on this page. Pass it
                      as ending_before to page backward. Null when the page is
                      empty.
                required:
                  - success
                  - message
                  - data
                  - has_more
                  - next_cursor
                  - prev_cursor
              example:
                success: true
                message: Successfully fetched promotion codes
                data:
                  - id: promo_WGkMvM5bJNCh3ZwvU7GSUcvP
                    code: SAMNEWS20
                    type: percentage
                    value: '20'
                    duration: forever
                    duration_in_months: null
                    active: true
                    entity_type: partner
                    external_id: null
                    partner_id: part_NLYzgNKuSuASvrvoxNtau6SY
                    program_id: prg_T6z8aRW3XCmvFWP972RKxpAd
                    group_id: null
                    created_at: '2026-10-19T10:15:19.228Z'
                    updated_at: '2026-10-19T10:15:19.228Z'
                  - id: promo_gTCAUsWfdmN2GuCVRaHWNRan
                    code: SAM20
                    type: percentage
                    value: '20'
                    duration: forever
                    duration_in_months: null
                    active: true
                    entity_type: partner
                    external_id: null
                    partner_id: part_NLYzgNKuSuASvrvoxNtau6SY
                    program_id: prg_T6z8aRW3XCmvFWP972RKxpAd
                    group_id: null
                    created_at: '2026-10-01T12:00:00Z'
                    updated_at: '2026-10-01T12:00:00Z'
                has_more: false
                next_cursor: >-
                  cur_WyJjcmVhdGVkX2F0IiwiMjAyNi0xMC0wMSAxMjowMDowMCswMCIsInByb21vX2dUQ0FVc1dmZG1OMkd1Q1ZSYUhXTlJhbiJd
                prev_cursor: >-
                  cur_WyJjcmVhdGVkX2F0IiwiMjAyNi0xMC0xOSAxMDoxNToxOS4yMjgrMDAiLCJwcm9tb19XR2tNdk01YkpOQ2gzWnd2VTdHU1VjdlAiXQ
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                message: 'starting_after: malformed cursor'
                code: invalid_cursor
                doc_url: https://docs.tolt.com/errors#invalid_cursor
                errors:
                  - field: starting_after
                    message: malformed cursor
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                message: Unauthorized
                code: unauthorized
                doc_url: https://docs.tolt.com/errors#unauthorized
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    PromotionCode:
      type: object
      properties:
        id:
          type: string
          example: promo_gTCAUsWfdmN2GuCVRaHWNRan
        code:
          type:
            - string
            - 'null'
          example: SAM20
        type:
          type:
            - string
            - 'null'
          example: percentage
        value:
          type:
            - string
            - 'null'
          example: '20'
        duration:
          type: string
          example: forever
        duration_in_months:
          type:
            - string
            - 'null'
          example: null
        active:
          type:
            - boolean
            - 'null'
          example: true
        entity_type:
          type:
            - string
            - 'null'
          example: partner
        external_id:
          type:
            - string
            - 'null'
          example: null
        partner_id:
          type:
            - string
            - 'null'
          example: part_NLYzgNKuSuASvrvoxNtau6SY
        program_id:
          type:
            - string
            - 'null'
          example: prg_T6z8aRW3XCmvFWP972RKxpAd
        group_id:
          type:
            - string
            - 'null'
          example: null
        created_at:
          type: string
          format: date-time
          example: '2026-10-01T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-10-01T12:00:00Z'
      required:
        - id
        - code
        - type
        - value
        - duration
        - duration_in_months
        - active
        - entity_type
        - external_id
        - partner_id
        - program_id
        - group_id
        - created_at
        - updated_at
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          description: Human-readable explanation. May change; branch on code instead.
        code:
          type: string
          enum:
            - bad_request
            - validation_error
            - invalid_reference
            - invalid_cursor
            - unauthorized
            - forbidden
            - not_found
            - conflict
            - already_exists
            - commission_paid
            - commission_frozen
            - transaction_refunded
            - commission_exists
            - rate_limited
            - payload_too_large
            - internal_error
          description: Stable machine-readable error code.
          example: not_found
        doc_url:
          type: string
          example: https://docs.tolt.com/errors#not_found
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
            required:
              - field
              - message
          description: >-
            One entry per offending field. Present on validation_error and
            invalid_reference.
      required:
        - success
        - message
        - code
        - doc_url
  headers:
    X-RateLimit-Limit:
      description: Requests allowed in the current window.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Unix time, in seconds, when the window resets.
      schema:
        type: integer
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  responses:
    PayloadTooLarge:
      description: Request body exceeds 1 MB
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            message: Request body exceeds 1 MB
            code: payload_too_large
            doc_url: https://docs.tolt.com/errors#payload_too_large
    RateLimited:
      description: The API key exceeded its rate limit
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            message: Too many requests. Retry after the window resets.
            code: rate_limited
            doc_url: https://docs.tolt.com/errors#rate_limited
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Tolt API key sent as a bearer token.

````

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