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

# Create Promotion Codes

> Makes a batch of codes on a code promotion: each code is the prefix and a random suffix, with its own limit of uses.

> [!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 makes a batch of codes on a code promotion of your account. The guide [Create a batch of codes](https://docs.y.uno/docs/payment-features/promotion-codes#create-a-batch-of-codes) explains the whole flow, and [List Promotion Codes](https://docs.y.uno/reference/promotions/list-promotion-codes) reads the codes back.

## What the request needs

* **The account comes from the `X-Account-Code` header.** The promotion must belong to that account. Without the header the answer is `400 INVALID_PARAMETERS`.
* **`X-Idempotency-Key` is required.** It is any text of 1 to 64 characters. The same key on the same promotion returns the first batch with `201`, and Yuno does not compare the body.
* **The promotion id is a UUID v4 in the path.** An id that is not one answers `400 INVALID_PARAMETERS`. An id that is not on the account answers `404 PROMOTION_NOT_FOUND`.
* **`quantity` is required,** a whole number from 1 to 1000. **`prefix` is required,** 1 to 8 letters or digits. **`uses_per_code` is optional,** a whole number from 1 to 1000000, and each code accepts one payment without it.
* **A full code is refused.** A body with a `code` answers `400 INVALID_REQUEST` with `code: NOT_ALLOWED`. Yuno makes every code of the batch.
* **The body is at most 256 KiB.** A larger body answers `413 REQUEST_ENTITY_TOO_LARGE`.

## What the answer holds

`201` returns the batch: `batch_id`, `promotion_id`, `quantity` and `codes`. Each entry of `codes` holds the `code` and its `uses_per_code`. The suffix of each code is 5 characters for up to 28 codes, 6 characters for 29 to 887 codes, and 7 characters for 888 to 1000 codes.

The codes come back only in this answer and in [List Promotion Codes](https://docs.y.uno/reference/promotions/list-promotion-codes). Keep them secret. Yuno does not write them to its logs.

## Errors

Two kinds of `400` exist, as for [Create Promotion](https://docs.y.uno/reference/promotions/create-promotion). `INVALID_PARAMETERS` comes from the headers, the path and the check of the body as an object. `INVALID_REQUEST` comes from the rules of the batch: `quantity`, `uses_per_code`, `prefix` and `code`, with one `path: RULE` message for each failed path. A promotion that can't hold a batch answers `422 PROMOTION_NOT_APPLICABLE` with a `reason`. [Promotion Error Codes](https://docs.y.uno/reference/promotions/promotion-error-codes) lists every answer.


## OpenAPI

````yaml openapi/promotions/create-promotion-codes.json POST /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:
    post:
      summary: Create Promotion Codes
      description: >-
        Makes a batch of codes on a code promotion of the account in the
        `X-Account-Code` header. Each code is the prefix and a random suffix,
        with its own limit of uses (`uses_per_code`). `quantity` (1 to 1000) and
        `prefix` are required. A promotion holds at most 10,000 batch codes. The
        same `X-Idempotency-Key` on the same promotion returns the first batch.
        The codes come back only in this answer and in List Promotion Codes.
        Keep them secret; Yuno does not write them to its logs.
      operationId: createPromotionCodes
      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
            promotion returns the first batch with `201`. Yuno does not compare
            the body.
        - 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` and must be a code promotion (`redemption.mode`
            is `CODE`). An id that is not a UUID v4 answers `400
            INVALID_PARAMETERS`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - quantity
                - prefix
              properties:
                quantity:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  description: >-
                    The number of codes in the batch, from 1 to 1000. A missing
                    value answers `quantity: REQUIRED`, and a value outside that
                    range answers `quantity: RANGE`. Both are `400
                    INVALID_REQUEST`.
                uses_per_code:
                  type: integer
                  minimum: 1
                  maximum: 1000000
                  default: 1
                  description: >-
                    How many payments each code accepts, from 1 to 1000000.
                    Optional: without it each code accepts one payment. A value
                    outside that range answers `uses_per_code: RANGE`.
                prefix:
                  type: string
                  minLength: 1
                  maxLength: 8
                  description: >-
                    Required. 1 to 8 letters or digits (`A-Z`, `0-9`), in any
                    case. Yuno converts it to upper case and builds each code
                    from it: the prefix, then a random suffix. A missing or
                    blank prefix answers `prefix: REQUIRED`. A body with a
                    `code` is refused with `code: NOT_ALLOWED`.
            examples:
              Batch of three codes:
                summary: A batch of three codes with a prefix
                value:
                  quantity: 3
                  uses_per_code: 1
                  prefix: SUMMER
      responses:
        '201':
          description: >-
            201. The batch, with its codes. The same key on the same promotion
            returns the same batch with `201`.
          content:
            application/json:
              schema:
                type: object
                description: A batch of codes.
                properties:
                  batch_id:
                    type: string
                    format: uuid
                    description: >-
                      The id of the batch. It is derived from the account, the
                      promotion and the key.
                  promotion_id:
                    type: string
                    format: uuid
                  quantity:
                    type: integer
                    description: The number of codes in the answer.
                  codes:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: >-
                            A secret. The prefix and a random suffix of 5, 6 or
                            7 characters, by the quantity of the request.
                        uses_per_code:
                          type: integer
                          description: How many payments the code accepts.
              examples:
                Batch created:
                  summary: A batch of three codes
                  value:
                    batch_id: 3f6a9c1e-2b7d-8e4a-9f15-6c0d2b8e7a41
                    promotion_id: 660e8400-e29b-41d4-a716-446655440001
                    quantity: 3
                    codes:
                      - code: SUMMERA7KQ9
                        uses_per_code: 1
                      - code: SUMMERM2TX4
                        uses_per_code: 1
                      - code: SUMMERP8W6R
                        uses_per_code: 1
        '400':
          description: >-
            400. The headers, the path or the body is not valid
            (`INVALID_PARAMETERS`), or a rule of the batch failed
            (`INVALID_REQUEST`, with one `path: RULE` message for each failed
            path).
          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.
                No X-Idempotency-Key:
                  summary: No X-Idempotency-Key header
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        The header 'X-Idempotency-Key' is required and must not
                        exceed 64 characters.
                account_id in the body:
                  summary: 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.
                Quantity out of range:
                  summary: quantity is 0 or more than 1000
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'quantity: RANGE'
                No prefix:
                  summary: No prefix
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'prefix: REQUIRED'
                Prefix with a bad character:
                  summary: A prefix character outside A-Z and 0-9
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'prefix: FORMAT'
                Prefix too long:
                  summary: A prefix of more than 8 characters
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'prefix: LENGTH'
                uses_per_code out of range:
                  summary: uses_per_code is 0 or more than 1000000
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'uses_per_code: RANGE'
                A code in the body:
                  summary: A full code in the body
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - 'code: NOT_ALLOWED'
              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. The gate answer has a `code` and no
            `messages`.
          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:
                  value:
                    code: PROMOTION_NOT_FOUND
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: PROMOTION_NOT_FOUND
                  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
        '422':
          description: >-
            422. The promotion can't hold the batch: `PROMOTION_NOT_APPLICABLE`,
            with the `reason`. Yuno stores nothing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: PROMOTION_NOT_APPLICABLE
                  reason:
                    type: string
                    enum:
                      - NOT_CODE_PROMOTION
                      - DISABLED
                      - EXPIRED
                      - BATCH_LIMIT_REACHED
                  messages:
                    type: array
                    items:
                      type: string
              examples:
                Not a code promotion:
                  summary: An AUTOMATIC promotion has no code
                  value:
                    code: PROMOTION_NOT_APPLICABLE
                    reason: NOT_CODE_PROMOTION
                    messages:
                      - Only a promotion with a code can hold batch codes.
                Disabled:
                  summary: The promotion is disabled
                  value:
                    code: PROMOTION_NOT_APPLICABLE
                    reason: DISABLED
                    messages:
                      - The promotion is disabled.
                Expired:
                  summary: The promotion ended
                  value:
                    code: PROMOTION_NOT_APPLICABLE
                    reason: EXPIRED
                    messages:
                      - The promotion expired.
                Batch limit reached:
                  summary: The batch would pass 10,000 codes
                  value:
                    code: PROMOTION_NOT_APPLICABLE
                    reason: BATCH_LIMIT_REACHED
                    messages:
                      - The promotion cannot hold more than 10000 batch codes.
        '500':
          description: >-
            500. The promotions service failed, or Yuno could not draw enough
            codes that are free for the batch. Yuno stores nothing: retry the
            request.
          content:
            application/json:
              examples:
                Internal error:
                  summary: Internal error
                  value:
                    code: INTERNAL_ERROR
                    messages:
                      - Internal error
              schema:
                type: object
                properties:
                  code:
                    type: string
                  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.