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

# Retrieve Promotion

> Returns one promotion of an account, with its status and, for a code promotion with a cap, the uses counted so far.

> [!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 promotion must belong to the account in the `X-Account-Code` header. A promotion of another account, and an id that no promotion holds, answer `404 PROMOTION_NOT_FOUND`. An id that is not a UUID v4 answers `400 INVALID_PARAMETERS`.

`status` is computed when you read the promotion: `SCHEDULED` before `starts_at`, `ACTIVE` inside the window, `EXPIRED` after `ends_at`, and `DISABLED` once you disable it. For a code promotion with a cap, `limits.used` is the number of uses counted so far. A promotion with no cap shows `limits: null`.


## OpenAPI

````yaml openapi/promotions/retrieve-promotion.json GET /promotions/{promotion_id}
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}:
    get:
      summary: Retrieve Promotion
      description: >-
        Returns one promotion of the account of the `X-Account-Code` header.
        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: retrieve-promotion
      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 id of the promotion (UUID v4). A value that is not a UUID v4
            returns `400 INVALID_PARAMETERS`. A promotion of another account
            returns `404`.
      responses:
        '200':
          description: 200. The promotion.
          content:
            application/json:
              examples:
                A code promotion:
                  value:
                    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
              schema:
                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.'
        '400':
          description: >-
            400. There is no `X-Account-Code` header, or the promotion id is not
            a UUID v4.
          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
                Invalid promotion id:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        The path parameter in url 'promotion_id' must be a valid
                        uuid v4.
                  summary: The promotion id is not a UUID v4
              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. The promotion does not exist on the account, or Promotions is
            not enabled for your organization (the body then has a `code` and no
            `messages`).
          content:
            application/json:
              examples:
                Promotion not found:
                  value:
                    code: PROMOTION_NOT_FOUND
                    messages:
                      - The promotion does not exist on the account.
                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.