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

# Disable Promotion

> Disables a promotion. The change is final: a disabled promotion is never enabled again.

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

> [!NOTE]
>
> **Disabling is the only change a promotion accepts**
>
> Send `{ "status": "DISABLED" }`, with `DISABLED` in capitals. A body with any other field answers `400 INVALID_REQUEST`, and a `status` that is missing or is not `DISABLED` answers `400 INVALID_PARAMETERS`. To change a discount, a date, a condition or the code, disable the promotion and [create a new one](https://docs.y.uno/reference/promotions/create-promotion).

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

Disabling is idempotent. A second call answers the promotion with the same `disabled_at` as the first.

## What disabling does

* **A code stops applying to new payments.** A payment that carries the code afterwards is refused with `422 PROMOTION_NOT_APPLICABLE` and the reason `DISABLED`. No payment is created.
* **A retry of an earlier payment is still priced.** A payment that repeats the `X-Idempotency-Key` and the code of an earlier use is priced from that use, even after you disable the promotion.
* **The code becomes free.** A disabled promotion no longer holds its code, so you can create a new promotion with the same code.
* **The uses stay.** `limits.used` keeps the count, and a use is never given back.


## OpenAPI

````yaml openapi/promotions/disable-promotion.json PATCH /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}:
    patch:
      summary: Disable Promotion
      description: >-
        Disables a promotion of the account of the `X-Account-Code` header.
        Disabling is final and idempotent: a second call returns the promotion
        with the same `disabled_at`. 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: disable-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`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - status
              properties:
                status:
                  type: string
                  enum:
                    - DISABLED
                  description: >-
                    Always `DISABLED`, in capitals. It is the only change a
                    promotion accepts. A body with any other field returns `400
                    INVALID_REQUEST`.
            examples:
              Disable:
                value:
                  status: DISABLED
      responses:
        '200':
          description: 200. The promotion, with `status` `DISABLED` and its `disabled_at`.
          content:
            application/json:
              examples:
                A disabled 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: DISABLED
                    created_at: '2026-10-16T15:04:05Z'
                    disabled_at: '2026-10-20T09:30:00Z'
              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, the promotion id is not a
            UUID v4, or `status` is missing or is not `DISABLED`
            (`INVALID_PARAMETERS`), or the body has a field other than `status`
            (`INVALID_REQUEST`).
          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
                Unknown field:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - The field 'name' is not allowed
                  summary: A field other than status
              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.