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

> Returns the promotions of one account, newest first, one page at a time, with an optional status filter.

> [!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).

The list belongs to the account in the `X-Account-Code` header. To see the promotions of several accounts, call once per account.

The list holds every promotion of the account: the `CODE` promotions you create with the API and the `AUTOMATIC` ones. Check `redemption.mode` to tell them apart.

## Pages

Results come newest first, by `created_at`. A page holds up to `limit` promotions: 20 by default, 1 to 100 allowed. When more promotions 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`.

Use `status` to keep one status: `SCHEDULED`, `ACTIVE`, `EXPIRED` or `DISABLED`. It accepts any case of the ASCII letters. Surrounding spaces are ignored, and a value of only spaces is read as no filter. Any other value, including one with a non-ASCII look-alike letter, answers `400 INVALID_REQUEST` with `status: UNKNOWN`. Any other query parameter is ignored.


## OpenAPI

````yaml openapi/promotions/list-promotions.json GET /promotions
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:
    get:
      summary: List Promotions
      description: >-
        Returns the promotions of the account of the `X-Account-Code` header,
        newest first, one page at a time. The list holds the account's `CODE`
        and `AUTOMATIC` promotions. Promotions must be enabled for your
        organization by Yuno before you can use this endpoint. See
        [Promotions](/docs/payment-features/promotions#enable-promotions-for-your-organization).
      operationId: list-promotions
      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.").
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - SCHEDULED
              - ACTIVE
              - EXPIRED
              - DISABLED
          description: >-
            Filter by status. It accepts any case of the ASCII letters.
            Surrounding spaces are ignored. Any other value, including one with
            a non-ASCII look-alike letter, returns `400 INVALID_REQUEST` with
            the message `status: UNKNOWN`.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: >-
            Page size, 1 to 100. The default is 20. A value outside the range
            returns `400 INVALID_REQUEST` with the message `limit: RANGE`, and
            one that is not a whole number of up to 3 digits `limit: FORMAT`.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            Opaque. The `next_cursor` of the previous page. A cursor that is not
            valid returns `400 INVALID_REQUEST` with the message `cursor:
            FORMAT`.
      responses:
        '200':
          description: 200. One page of promotions.
          content:
            application/json:
              examples:
                Last page:
                  summary: Last page
                  value:
                    data:
                      - id: 00000000-0000-4000-8000-0000000000b1
                        account_id: 00000000-0000-4000-8000-0000000000a1
                        name: Summer 10
                        description: null
                        schedule:
                          starts_at: '2026-11-01T00:00:00Z'
                          ends_at: '2026-12-01T00:00:00Z'
                        redemption:
                          mode: CODE
                          code: SUMMER10
                        discount:
                          type: PERCENTAGE
                          value: 10
                          amounts: null
                        conditions:
                          bins: null
                          payment_methods: null
                          card_types: null
                          countries:
                            values:
                              - US
                          amounts:
                            values:
                              - currency: USD
                                min: 50
                                max: 5000
                        limits:
                          total: 100
                          used: 3
                        status: ACTIVE
                        created_at: '2026-10-16T15:04:05Z'
                        disabled_at: null
                    next_cursor: null
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      description: >-
                        A promotion. Every member is present, with `null` for an
                        absent value.
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: The id of the promotion (UUID). Assigned by Yuno.
                        account_id:
                          type: string
                          format: uuid
                          description: The account the promotion belongs to.
                        name:
                          type: string
                        description:
                          type:
                            - string
                            - 'null'
                        schedule:
                          type: object
                          properties:
                            starts_at:
                              type: string
                              format: date-time
                            ends_at:
                              type:
                                - string
                                - 'null'
                              format: date-time
                              description: '`null` means no end date.'
                        redemption:
                          type: object
                          properties:
                            mode:
                              type: string
                              enum:
                                - AUTOMATIC
                                - CODE
                              description: >-
                                Promotions you create with this API are `CODE`.
                                The account can also hold `AUTOMATIC`
                                promotions, and the list returns them too.
                            code:
                              type:
                                - string
                                - 'null'
                              description: >-
                                The code, in upper case. `null` for an
                                `AUTOMATIC` promotion.
                        discount:
                          type: object
                          properties:
                            type:
                              type: string
                              enum:
                                - PERCENTAGE
                                - FIXED
                            value:
                              type:
                                - number
                                - 'null'
                              description: '`PERCENTAGE` only. `null` for a fixed discount.'
                            amounts:
                              type:
                                - array
                                - 'null'
                              items:
                                type: object
                                properties:
                                  currency:
                                    type: string
                                    description: ISO 4217 currency code.
                                  value:
                                    type: number
                                    description: >-
                                      An amount in major units, with exactly the
                                      decimals of the currency.
                              description: '`FIXED` only. `null` for a percentage discount.'
                        conditions:
                          type: object
                          description: >-
                            One key for each dimension, `null` when the
                            promotion has no condition on it. A code promotion
                            created with this API holds `countries` and
                            `amounts` only.
                          properties:
                            bins:
                              type:
                                - object
                                - 'null'
                            payment_methods:
                              type:
                                - object
                                - 'null'
                              description: Payment method types.
                              properties:
                                values:
                                  type: array
                                  items:
                                    type: string
                            card_types:
                              type:
                                - object
                                - 'null'
                              description: Card types.
                              properties:
                                values:
                                  type: array
                                  items:
                                    type: string
                            countries:
                              type:
                                - object
                                - 'null'
                              description: Payment countries (ISO 3166-1).
                              properties:
                                values:
                                  type: array
                                  items:
                                    type: string
                            amounts:
                              type:
                                - object
                                - 'null'
                              properties:
                                values:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      currency:
                                        type: string
                                      min:
                                        type:
                                          - number
                                          - 'null'
                                      max:
                                        type:
                                          - number
                                          - 'null'
                        limits:
                          type:
                            - object
                            - 'null'
                          description: >-
                            The cap of the code and the uses counted so far.
                            `null` when the promotion has no cap.
                          properties:
                            total:
                              type: integer
                              description: The most uses the code accepts.
                            used:
                              type: integer
                              description: >-
                                The uses counted so far. It grows by one for
                                each new payment `X-Idempotency-Key` and never
                                decreases.
                        status:
                          type: string
                          enum:
                            - SCHEDULED
                            - ACTIVE
                            - EXPIRED
                            - DISABLED
                          description: >-
                            Computed from `schedule` and from the disable at the
                            moment you read the promotion.
                        created_at:
                          type: string
                          format: date-time
                        disabled_at:
                          type:
                            - string
                            - 'null'
                          format: date-time
                          description: '`null` while the promotion is not disabled.'
                    description: >-
                      One page of promotions, newest first. Empty for an empty
                      page.
                  next_cursor:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Pass it as `cursor` to read the next page. `null` on the
                      last page.
        '400':
          description: >-
            400. There is no `X-Account-Code` header, or a query parameter is
            not valid.
          content:
            application/json:
              examples:
                No X-Account-Code:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - x-account-code header is required.
                  summary: No X-Account-Code header
                Unknown status:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'status: UNKNOWN'
                  summary: Unknown status filter
                limit out of range:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'limit: RANGE'
                  summary: limit outside 1 to 100
                Invalid cursor:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'cursor: FORMAT'
                  summary: Invalid cursor
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_PARAMETERS
                  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. Promotions is not enabled for your organization. The body has a
            `code` and no `messages`.
          content:
            application/json:
              examples:
                Promotions not enabled:
                  value:
                    code: PROMOTION_NOT_FOUND
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: PROMOTION_NOT_FOUND
                  messages:
                    type: array
                    items:
                      type: string
        '500':
          description: 500. The promotions service failed. Retry later.
          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
      deprecated: false
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.