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

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# List Promotion Codes

> Returns the codes of one promotion, oldest first, one page at a time, with the number of payments that took each code.

> [!WARNING]
>
> **Promotions is enabled per organization**
>
> This endpoint works only after Yuno enables Promotions for your organization. Until then it answers `404 PROMOTION_NOT_FOUND`. Ask your Technical Account Manager or Key Account Manager. See [Promotions](https://docs.y.uno/docs/payment-features/promotions#enable-promotions-for-your-organization).

This endpoint lists the batch codes of a code promotion of the account in the `X-Account-Code` header. The codes are secret: keep them safe, and share each one only with the customers who may use it.

## Pages

Results come oldest first, by `created_at`. A page holds up to `limit` codes: 100 by default, 1 to 500 allowed. When more codes exist, `next_cursor` is a string: pass it as `cursor` to read the next page. On the last page `next_cursor` is `null`. The cursor is opaque. A cursor that is not valid answers `400 INVALID_REQUEST` with the message `cursor: FORMAT`. A `limit` outside 1 to 500 answers `400 INVALID_REQUEST` with `limit: RANGE`; a `limit` with a character that is not a digit, or with more than three digits, answers `limit: FORMAT`.

## What each code shows

Each code holds its `code`, its `uses_per_code` (the most payments it accepts), and `used`, the number of payments that took it. `batch_id` names the batch that made the code, and `created_at` is when Yuno created it: all the codes of one batch share it. A disabled promotion lists its codes too.

A promotion that is not on the account answers `404 PROMOTION_NOT_FOUND`. A promotion id that is not a UUID v4 answers `400 INVALID_PARAMETERS`. [Promotion Error Codes](https://docs.y.uno/reference/promotions/promotion-error-codes) lists every answer.


## OpenAPI

````yaml openapi/promotions/list-promotion-codes.json GET /promotions/{promotion_id}/codes
openapi: 3.1.0
info:
  title: promotions
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
  - url: https://api.eu.y.uno/v1
    description: Production (EMEA)
security:
  - sec0: []
    sec1: []
paths:
  /promotions/{promotion_id}/codes:
    get:
      summary: List Promotion Codes
      description: >-
        Lists the batch codes of a promotion of the account in the
        `X-Account-Code` header, oldest first, one page at a time. `limit` takes
        1 to 500 and defaults to 100. Pass `next_cursor` of a page as `cursor`
        to read the next one; it is `null` on the last page. `used` is the
        number of payments that took the code. A disabled promotion lists its
        codes too. The codes are secret; Yuno does not write them to its logs.
      operationId: listPromotionCodes
      parameters:
        - in: header
          name: X-Account-Code
          required: true
          schema:
            type: string
          description: >-
            The `account_id` found in your [Yuno
            Dashboard](https://dashboard.y.uno/developers) (UUID). Required. A
            promotion belongs to one account, and this header names it. Omitting
            it returns `400 INVALID_PARAMETERS` ("x-account-code header is
            required.").
        - in: path
          name: promotion_id
          required: true
          schema:
            type: string
            format: uuid
          description: >-
            The promotion id (UUID v4). The promotion must belong to the account
            of `X-Account-Code`. A promotion with no codes, such as an
            `AUTOMATIC` promotion, answers `200` with an empty `codes` list. An
            id that is not a UUID v4 answers `400 INVALID_PARAMETERS`.
        - in: query
          name: limit
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
          description: >-
            How many codes to return, from 1 to 500. Default 100. A value
            outside that range answers `400 INVALID_REQUEST` with `limit:
            RANGE`; a value with a character that is not a digit, or with more
            than three digits, answers `limit: FORMAT`.
        - in: query
          name: cursor
          required: false
          schema:
            type: string
          description: >-
            The `next_cursor` of the previous page. A cursor that is not valid
            answers `400 INVALID_REQUEST` with `cursor: FORMAT`.
      responses:
        '200':
          description: >-
            200. One page of the codes, oldest first. `next_cursor` is `null` on
            the last page.
          content:
            application/json:
              schema:
                type: object
                properties:
                  codes:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: A secret.
                        uses_per_code:
                          type: integer
                          description: How many payments the code accepts.
                        used:
                          type: integer
                          description: How many payments took the code.
                        batch_id:
                          type: string
                          format: uuid
                        created_at:
                          type: string
                          format: date-time
                          description: >-
                            When the code was created. All the codes of one
                            batch share it.
                  next_cursor:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Pass it as `cursor` to read the next page. `null` on the
                      last page.
              examples:
                A page of codes:
                  summary: Two codes, the last page
                  value:
                    codes:
                      - code: SUMMERA7KQ9
                        uses_per_code: 1
                        used: 1
                        batch_id: 3f6a9c1e-2b7d-8e4a-9f15-6c0d2b8e7a41
                        created_at: '2026-10-20T14:00:00.000001Z'
                      - code: SUMMERM2TX4
                        uses_per_code: 1
                        used: 0
                        batch_id: 3f6a9c1e-2b7d-8e4a-9f15-6c0d2b8e7a41
                        created_at: '2026-10-20T14:00:00.000001Z'
                    next_cursor: null
        '400':
          description: >-
            400. No `X-Account-Code` header (`INVALID_PARAMETERS`), or `limit`
            or `cursor` is not valid (`INVALID_REQUEST`).
          content:
            application/json:
              examples:
                No X-Account-Code:
                  summary: No X-Account-Code header
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - x-account-code header is required.
                limit out of range:
                  summary: limit is 0 or more than 500
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'limit: RANGE'
                cursor not issued:
                  summary: A cursor that is not valid
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'cursor: FORMAT'
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
        '401':
          description: 401. The credentials are missing or invalid.
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    code: INVALID_CREDENTIALS
                    messages:
                      - Invalid Credentials
                Not authenticated:
                  value:
                    code: NOT_AUTHENTICATED
                    messages:
                      - Not authenticated
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_CREDENTIALS
                  messages:
                    type: array
                    items:
                      type: string
        '404':
          description: >-
            404. No promotion of the account holds this id, or Promotions is not
            enabled for your organization.
          content:
            application/json:
              examples:
                Promotion not on the account:
                  summary: The promotion is not on the account
                  value:
                    code: PROMOTION_NOT_FOUND
                    messages:
                      - The promotion does not exist on the account.
                Promotions not enabled:
                  summary: Promotions is not enabled
                  value:
                    code: PROMOTION_NOT_FOUND
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
        '500':
          description: 500. The promotions service failed. Retry the request.
          content:
            application/json:
              examples:
                Internal error:
                  value:
                    code: INTERNAL_ERROR
                    messages:
                      - Internal error
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INTERNAL_ERROR
                  messages:
                    type: array
                    items:
                      type: string
        '503':
          description: 503. The promotions service is not configured or not available.
          content:
            application/json:
              examples:
                Service unavailable:
                  value:
                    code: PROMOTION_ENGINE_UNAVAILABLE
                    messages:
                      - The promotions service is unavailable.
                Store unavailable:
                  value:
                    code: STORE_UNAVAILABLE
                    messages:
                      - The store is unavailable.
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: PROMOTION_ENGINE_UNAVAILABLE
                  messages:
                    type: array
                    items:
                      type: string
        '504':
          description: 504. The promotions service did not answer in time.
          content:
            application/json:
              examples:
                Gateway timeout:
                  value:
                    code: PROMOTION_ENGINE_TIMEOUT
                    messages:
                      - The promotions service did not answer in time.
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: PROMOTION_ENGINE_TIMEOUT
                  messages:
                    type: array
                    items:
                      type: string
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: public-api-key
      x-default: <Your public-api-key>
    sec1:
      type: apiKey
      in: header
      name: private-secret-key
      x-default: <Your private-secret-key>

````

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