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

# Crear promoción

> Crea una promoción con código: un código que envías tú o que Yuno construye a partir de tu prefijo, un descuento, un rango de fechas, las condiciones que debe cumplir un pago y, opcionalmente, el máximo de usos.

> [!WARNING]
>
> **Promotions se habilita por organización**
>
> Este endpoint funciona solo después de que Yuno habilite Promotions para tu organización. Hasta entonces responde `404 PROMOTION_NOT_FOUND`. Pide la habilitación a tu Technical Account Manager o Key Account Manager. Consulta [Promotions](https://docs.y.uno/es/docs/payment-features/promotions#enable-promotions-for-your-organization).

> [!NOTE]
>
> **Las promociones no se pueden editar**
>
> No existe un endpoint para actualizar ni para eliminar. Para cambiar un descuento, una fecha, una condición o el código, [deshabilita la promoción](https://docs.y.uno/reference/promotions/disable-promotion) y crea una nueva.

Este endpoint crea promociones con código. Un cliente canjea una cuando tu servidor envía su código en [Crear pago](https://docs.y.uno/es/reference/payments/create-payment.md). Consulta [Códigos promocionales](https://docs.y.uno/es/docs/payment-features/promotion-codes) para ver el flujo completo.

## Qué necesita la solicitud

* **La cuenta se toma del encabezado `X-Account-Code`.** La promoción pertenece a esa cuenta. Un cuerpo que incluya `account_id` se rechaza con `400 INVALID_PARAMETERS`, y también un cuerpo que repita `redemption` o alguno de sus miembros (los nombres se comparan sin distinguir mayúsculas de minúsculas).
* **`X-Idempotency-Key` es obligatorio.** Es cualquier texto de 1 a 64 caracteres. La misma clave en la misma cuenta devuelve la primera promoción con `201`, y Yuno no compara el cuerpo. Una solicitud sin una clave válida se rechaza con `400` antes de leer el cuerpo.
* **`redemption.mode` es `CODE`** y envías exactamente uno de `redemption.code` y `redemption.prefix`. Si no envías ninguno, la respuesta es `400 INVALID_REQUEST` con `redemption: CODE_OR_PREFIX_REQUIRED`, y si envías ambos, la respuesta es `redemption: CODE_AND_PREFIX_EXCLUSIVE`. Cada respuesta agrega el mensaje `Send exactly one of redemption.code or redemption.prefix.`. Un `null`, un texto vacío y un texto con solo espacios cuentan como no enviados. Un `redemption.code` que no es válido, enviado junto con un prefijo, cuenta como ambos.
* **Un código que envías tiene de 3 a 32 caracteres:** letras, dígitos, `_` y `-`, en mayúsculas o minúsculas. Yuno recorta los espacios alrededor y lo guarda en mayúsculas. Un código con un carácter fuera de ese conjunto responde `redemption.code: CODE_CHARACTERS`, y uno de longitud incorrecta responde `redemption.code: CODE_LENGTH`.
* **Un prefijo construye el código.** El prefijo tiene de 1 a 8 letras o dígitos (`A-Z`, `a-z`, `0-9`). Yuno lo convierte a mayúsculas y construye el código con el prefijo y un sufijo aleatorio de 5 caracteres de `A-Z` y `2-9`, sin `0`, `O`, `1`, `I` y `L`. Por ejemplo, el prefijo `SUMMER` puede dar `SUMMERK7P2X`. El `201` muestra el código en `redemption.code`. Un carácter fuera de `A-Z`, `a-z` y `0-9` responde `redemption.prefix: FORMAT`, y más de 8 caracteres responde `redemption.prefix: LENGTH`. Yuno nunca construye un código que ya tenga otra promoción de tu cuenta, sin importar su estado. Una creación con prefijo nunca responde `409 CODE_ALREADY_EXISTS`. La misma `X-Idempotency-Key` devuelve la misma promoción con el mismo código. Si Yuno no puede construir un código, la creación falla con `500 INTERNAL_ERROR` y Yuno no guarda nada: reintenta la solicitud.
* **Un código es único por cuenta.** Otra promoción de la cuenta que no esté deshabilitada, con un calendario que se superponga al de la nueva, no puede tener el mismo código, y ningún código de lote de la cuenta puede tenerlo tampoco: la solicitud responde `409 CODE_ALREADY_EXISTS`. Un código vuelve a estar libre cuando la promoción anterior se deshabilita, o cuando su calendario termina en el momento de inicio de la nueva o antes.
* **Las condiciones son `countries` y `amounts`.** Un código se aplica a todo el pago, sin importar el método de pago. Una condición `bins`, `payment_methods` o `card_types` responde `400 INVALID_REQUEST` con `conditions.bins: FORBIDDEN`, `conditions.payment_methods: FORBIDDEN` o `conditions.card_types: FORBIDDEN`.
* **`limits.total` es opcional.** Es el máximo de usos que acepta el código, un número entero de 1 a 2147483647. Una promoción sin `limits` no tiene tope, y su respuesta muestra `limits: null`. Yuno cuenta un uso cuando un pago toma el código. Consulta [Usos y límites](https://docs.y.uno/es/docs/payment-features/promotion-codes#uses-and-limits).
* **El cuerpo pesa como máximo 256 KiB.** Un cuerpo más grande responde `413 REQUEST_ENTITY_TOO_LARGE`.

## Qué contiene la respuesta

`201` devuelve la promoción, tal como la describe [El objeto Promotion](https://docs.y.uno/reference/promotions/the-promotion-object), con `status` calculado a partir de `schedule` y con `limits.used` en `0`. Todos los miembros están presentes, con `null` para un valor ausente. `redemption.code` contiene el código, ya sea el que enviaste o el que Yuno construyó a partir de tu prefijo.

Existen dos tipos de `400`. `INVALID_PARAMETERS` proviene de las comprobaciones que Yuno hace antes de leer la promoción: los encabezados, `account_id`, `redemption.mode`. `INVALID_REQUEST` proviene de las reglas de la promoción en sí, con un mensaje `path: RULE` por cada ruta que falla, en el orden de las comprobaciones. [Códigos de error de Promotion](https://docs.y.uno/es/reference/promotions/promotion-error-codes) los enumera.


## OpenAPI

````yaml openapi/promotions/create-promotion.json POST /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:
    post:
      summary: Create Promotion
      description: >-
        Creates a code promotion on the account of the `X-Account-Code` header.
        A customer redeems it when your server sends its code on a payment. Send
        exactly one of `redemption.code` (a code of your own, 3 to 32
        characters) and `redemption.prefix` (1 to 8 letters or digits). With a
        prefix, Yuno builds the code from the prefix and a random suffix of 5
        characters, and returns the code in the answer. 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: create-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: header
          name: X-Idempotency-Key
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 64
          description: >-
            Required. Any text of 1 to 64 characters. The same key on the same
            account returns the first promotion with `201`, and Yuno does not
            compare the body.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - schedule
                - redemption
                - discount
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: The promotion name (1 to 255 characters).
                description:
                  type: string
                  minLength: 1
                  maxLength: 1000
                  description: Optional. Up to 1000 characters.
                schedule:
                  type: object
                  required:
                    - starts_at
                  description: The window in which the promotion runs. UTC.
                  properties:
                    starts_at:
                      type: string
                      format: date-time
                      description: >-
                        When the promotion starts (ISO 8601). Any instant: a
                        start in the past makes the promotion active at once.
                    ends_at:
                      type:
                        - string
                        - 'null'
                      format: date-time
                      description: >-
                        When the promotion ends (ISO 8601). Must be after
                        `starts_at`. Omit it or send `null` for no end date.
                redemption:
                  type: object
                  required:
                    - mode
                  properties:
                    mode:
                      type: string
                      enum:
                        - CODE
                      description: >-
                        Always `CODE`. Any other mode returns `400
                        INVALID_PARAMETERS`.
                    code:
                      type:
                        - string
                        - 'null'
                      minLength: 3
                      maxLength: 32
                      description: >-
                        A code of your own: 3 to 32 characters, `A-Z`, `0-9`,
                        `_` and `-`, in any case. Yuno trims the spaces around
                        it, stores it in upper case and matches the code of a
                        payment without regard to case. Unique per account among
                        the promotions that are not disabled and whose schedule
                        overlaps this one, and no batch code of the account
                        holds it: otherwise `409 CODE_ALREADY_EXISTS`. Send
                        exactly one of `code` and `prefix`: neither answers
                        `redemption: CODE_OR_PREFIX_REQUIRED` and both answer
                        `redemption: CODE_AND_PREFIX_EXCLUSIVE`. A `null`, an
                        empty text or a text with only spaces counts as not
                        sent.
                    prefix:
                      type:
                        - string
                        - 'null'
                      maxLength: 8
                      description: >-
                        The start of a code that Yuno builds: 1 to 8 letters or
                        digits (`A-Z`, `a-z`, `0-9`). Yuno converts it to upper
                        case and builds the code as the prefix and a random
                        suffix of 5 characters from `A-Z` and `2-9`, without
                        `0`, `O`, `1`, `I` and `L`, for example `SUMMERK7P2X`.
                        The `201` shows the code in `redemption.code`. A
                        character outside `A-Z`, `a-z` and `0-9` answers
                        `redemption.prefix: FORMAT`, and more than 8 characters
                        `redemption.prefix: LENGTH`. Send exactly one of `code`
                        and `prefix`. A `null`, an empty text or a text with
                        only spaces counts as not sent.
                      example: SUMMER
                discount:
                  type: object
                  required:
                    - type
                  description: >-
                    What the customer saves. For `FIXED`, when the promotion
                    also has an `amounts` condition, `discount.amounts` and
                    `conditions.amounts.values` must list the same currencies,
                    or the request returns `400`.
                  properties:
                    type:
                      type: string
                      enum:
                        - PERCENTAGE
                        - FIXED
                    value:
                      type: number
                      minimum: 0.01
                      maximum: 100
                      description: >-
                        `PERCENTAGE` only, with up to two decimals (for example
                        `10.5`).
                    amounts:
                      type: array
                      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: one `{ currency, value }` for each
                        currency, at most 50, each above zero. A fixed promotion
                        applies only to payments in the currencies it lists, and
                        the discount is capped at the payment amount.
                conditions:
                  type: object
                  description: >-
                    The conditions a payment must meet. **AND** across keys,
                    **OR** inside each key's `values` list. A code applies to
                    the whole payment, whatever the payment method, so only
                    `countries` and `amounts` are accepted. A `bins`,
                    `payment_methods` or `card_types` condition returns `400
                    INVALID_REQUEST` with the messages `conditions.bins:
                    FORBIDDEN`, `conditions.payment_methods: FORBIDDEN` or
                    `conditions.card_types: FORBIDDEN`.
                  properties:
                    countries:
                      type: object
                      required:
                        - values
                      properties:
                        values:
                          type: array
                          items:
                            type: string
                          description: >-
                            Payment countries ([ISO
                            3166-1](/reference/country-reference)). An empty
                            list is rejected.
                    amounts:
                      type: object
                      required:
                        - values
                      properties:
                        values:
                          type: array
                          description: >-
                            Amount bounds per currency. A payment in a currency
                            with no entry gets the reason `CURRENCY_MISMATCH`.
                          items:
                            type: object
                            required:
                              - currency
                            properties:
                              currency:
                                type: string
                              min:
                                type: number
                                description: Inclusive. Omit it for no lower bound.
                              max:
                                type: number
                                description: Inclusive. Omit it for no upper bound.
                limits:
                  type: object
                  description: Optional. Without it the code has no cap.
                  properties:
                    total:
                      type: integer
                      minimum: 1
                      maximum: 2147483647
                      description: >-
                        The most uses the code accepts. Yuno counts a use when a
                        payment takes the code, by the payment
                        `X-Idempotency-Key`. A declined payment keeps its use.
            examples:
              Percentage code with a cap:
                value:
                  name: Summer 10
                  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
                  conditions:
                    countries:
                      values:
                        - US
                    amounts:
                      values:
                        - currency: USD
                          min: 50
                          max: 5000
                  limits:
                    total: 100
              A prefix, Yuno builds the code:
                value:
                  name: Summer 20
                  schedule:
                    starts_at: '2026-11-01T00:00:00Z'
                    ends_at: '2026-12-01T00:00:00Z'
                  redemption:
                    mode: CODE
                    prefix: SUMMER
                  discount:
                    type: PERCENTAGE
                    value: 20
              Fixed code with no cap:
                value:
                  name: Ten dollars off
                  schedule:
                    starts_at: '2026-11-01T00:00:00Z'
                  redemption:
                    mode: CODE
                    code: TEN-OFF
                  discount:
                    type: FIXED
                    amounts:
                      - currency: USD
                        value: 10
      responses:
        '201':
          description: >-
            201. The promotion. The same answer returns when the account repeats
            the `X-Idempotency-Key`.
          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: 0
                    status: SCHEDULED
                    created_at: '2026-10-16T15:04:05Z'
                    disabled_at: null
                A code promotion built from a prefix:
                  value:
                    id: 00000000-0000-4000-8000-0000000000b2
                    account_id: 00000000-0000-4000-8000-0000000000a1
                    name: Summer 20
                    description: null
                    schedule:
                      starts_at: '2026-11-01T00:00:00Z'
                      ends_at: '2026-12-01T00:00:00Z'
                    redemption:
                      mode: CODE
                      code: SUMMERK7P2X
                    discount:
                      type: PERCENTAGE
                      value: 20
                      amounts: null
                    conditions:
                      bins: null
                      payment_methods: null
                      card_types: null
                      countries: null
                      amounts: null
                    limits: null
                    status: SCHEDULED
                    created_at: '2026-10-16T15:04:05Z'
                    disabled_at: null
                  summary: The request had a prefix
              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: the code you sent, or the
                          code Yuno built from your prefix (the prefix and a
                          random suffix of 5 characters, for example
                          `SUMMERK7P2X`). `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. Two kinds of body: `INVALID_PARAMETERS` for what public-api
            checks before it asks the promotions service, and `INVALID_REQUEST`
            for the promotions service's own checks, with one `path: RULE`
            message for each failed path.
          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
                No X-Idempotency-Key:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        The header 'X-Idempotency-Key' is required and must not
                        exceed 64 characters.
                  summary: No X-Idempotency-Key header
                account_id in the body:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        The field 'account_id' is not accepted in the body: the
                        promotion belongs to the account of the x-account-code
                        header.
                  summary: account_id in the body
                Mode is not CODE:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        The field 'redemption.mode' must be CODE: merchants
                        create promotions that customers redeem with a code.
                  summary: redemption.mode is not CODE
                Payment method condition:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'conditions.payment_methods: FORBIDDEN'
                  summary: A payment method condition on a code
                Code too short:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'redemption.code: CODE_LENGTH'
                  summary: Code with fewer than 3 characters
                Code too long:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'redemption.code: CODE_LENGTH'
                  summary: Code with more than 32 characters
                Neither a code nor a prefix:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'redemption: CODE_OR_PREFIX_REQUIRED'
                      - >-
                        Send exactly one of redemption.code or
                        redemption.prefix.
                  summary: >-
                    No redemption.code and no redemption.prefix (null, empty or
                    spaces count as not sent)
                A code and a prefix:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'redemption: CODE_AND_PREFIX_EXCLUSIVE'
                      - >-
                        Send exactly one of redemption.code or
                        redemption.prefix.
                  summary: Both redemption.code and redemption.prefix
                Prefix with a bad character:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'redemption.prefix: FORMAT'
                  summary: Prefix with a character outside A-Z, a-z and 0-9
                Prefix too long:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'redemption.prefix: LENGTH'
                  summary: Prefix with more than 8 characters
                Code with a bad character:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'redemption.code: CODE_CHARACTERS'
                  summary: Code with a character outside A-Z, 0-9, _ and -
                limits.total out of range:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'limits.total: RANGE'
                  summary: limits.total below 1 or above 2147483647
                ends_at not after starts_at:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'schedule.ends_at: NOT_AFTER_START'
                  summary: schedule.ends_at not after schedule.starts_at
              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
        '409':
          description: >-
            409. Another promotion of the account that is not disabled holds
            this code in an overlapping schedule, or a batch code of the account
            holds it.
          content:
            application/json:
              examples:
                Code already exists:
                  value:
                    code: CODE_ALREADY_EXISTS
                    messages:
                      - >-
                        Another promotion of the account holds this code in an
                        overlapping schedule.
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: CODE_ALREADY_EXISTS
                  messages:
                    type: array
                    items:
                      type: string
        '413':
          description: 413. The body is larger than 256 KiB.
          content:
            application/json:
              examples:
                Request too large:
                  value:
                    code: REQUEST_ENTITY_TOO_LARGE
                    messages:
                      - The request body must not exceed 256 KiB.
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: REQUEST_ENTITY_TOO_LARGE
                  messages:
                    type: array
                    items:
                      type: string
        '500':
          description: >-
            500. The promotions service failed, or the request had a
            `redemption.prefix` and Yuno could not build a code. Yuno stores
            nothing. 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
      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.