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

# Attach Promotion to Plan

> Attaches an existing promotion to a subscription plan for a number of charges, so the plan's subscriptions can receive it

Attaches an existing promotion to a plan. Subscriptions on the plan can then receive the promotion when they are [created](https://docs.y.uno/reference/subscriptions/create-subscription.md) or [updated](https://docs.y.uno/reference/subscriptions/update-subscription.md). The attachment sets how many charges the discount covers (`cycles`) and what a pause does to it (`on_pause`). See [Promotions on subscription plans](https://docs.y.uno/docs/payment-features/subscriptions/promotions.md).

The response, and each item in the plan's `promotions` list, shows the attachment's `promotion_id`, `name`, `type`, `status`, `cycles`, `on_pause` and `attached_at`.

`type` is the promotion's redemption mode: `AUTOMATIC` (applied by itself when a subscription is created on the plan) or `CODE` (applied only when the merchant sends its code).

> [!NOTE]
>
> **Attachments are not edited**
>
> To change `cycles` or `on_pause`, remove the attachment with [Remove Promotion from Plan](https://docs.y.uno/reference/plans/remove-plan-promotion.md) and attach the promotion again. Removing an attachment does not change the subscriptions that already have the promotion.

## Errors

| HTTP | `code` | When |
| :- | :- | :- |
| `404` | `PROMOTION_NOT_FOUND` | The `promotion_id` is unknown, or belongs to another account. |
| `409` | `PROMOTION_ALREADY_ATTACHED` | The plan already has this promotion. |
| `422` | `PROMOTION_NOT_APPLICABLE` | The promotion cannot be attached. The `reason` says why, for example `EXPIRED`, or `PROMOTIONS_NOT_ENABLED` when promotions are not turned on for your organization. |
| `503` | `PROMOTION_ENGINE_UNAVAILABLE` | The promotions engine did not respond. |
| `504` | `PROMOTION_ENGINE_TIMEOUT` | The promotions engine did not respond in time. |

See [Subscription promotion error codes](https://docs.y.uno/reference/subscriptions/subscription-promotion-error-codes.md) for every reason.


## OpenAPI

````yaml openapi/plans/attach-plan-promotion.json POST /subscriptions/plans/{plan_id}/promotions
openapi: 3.1.0
info:
  title: plans
  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:
  /subscriptions/plans/{plan_id}/promotions:
    post:
      summary: Attach Promotion to Plan
      description: >-
        Attaches an existing promotion to the plan for `cycles` charges.
        Subscriptions on the plan can then receive it when they are created or
        updated. Attachments are not edited: to change `cycles` or `on_pause`,
        remove the attachment and attach the promotion again.
      operationId: attach-plan-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 —
            omitting it returns `400 BAD_REQUEST` ("Invalid x-account-code
            header.").
        - name: plan_id
          in: path
          description: The unique identifier of the plan.
          schema:
            type: string
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - promotion_id
                - cycles
              properties:
                promotion_id:
                  type: string
                  description: The ID of an existing promotion (UUID).
                cycles:
                  type: integer
                  minimum: 1
                  description: The number of charges the discount covers. At least 1.
                on_pause:
                  type: string
                  enum:
                    - KEEP
                    - END
                  default: KEEP
                  description: >-
                    What a pause does to the promotion once it is applied to a
                    subscription. `KEEP` (default) keeps its remaining cycles
                    for when the subscription resumes. `END` ends the promotion
                    with `end_reason` `PAUSE`.
            examples:
              Request:
                value:
                  promotion_id: 8f2d6c1e-3b7a-4c55-9a1e-2f4d8b7c6a10
                  cycles: 3
      responses:
        '201':
          description: 201. The promotion is attached to the plan.
          content:
            application/json:
              examples:
                Result:
                  value:
                    promotion_id: 8f2d6c1e-3b7a-4c55-9a1e-2f4d8b7c6a10
                    name: Welcome 20% x3
                    type: AUTOMATIC
                    status: ENABLED
                    cycles: 3
                    attached_at: '2026-11-02T14:00:00Z'
                    on_pause: KEEP
              schema:
                type: object
                properties:
                  promotion_id:
                    type: string
                  name:
                    type: string
                  type:
                    type: string
                    description: >-
                      The redemption mode of the promotion. `AUTOMATIC`
                      promotions apply by themselves when a subscription is
                      created on the plan. `CODE` promotions apply when the
                      merchant sends the code.
                    enum:
                      - AUTOMATIC
                      - CODE
                  status:
                    type: string
                    description: '`ENABLED` when the attachment is created.'
                  cycles:
                    type: integer
                  attached_at:
                    type: string
                    format: date-time
                  on_pause:
                    type: string
                    enum:
                      - KEEP
                      - END
                    description: >-
                      What a pause does to the promotion once it is applied to a
                      subscription.
        '404':
          description: 404. The promotion does not exist, or belongs to another account.
          content:
            application/json:
              examples:
                Result:
                  value:
                    code: PROMOTION_NOT_FOUND
                    messages:
                      - Promotion not found.
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
        '409':
          description: 409. The plan already has this promotion.
          content:
            application/json:
              examples:
                Result:
                  value:
                    code: PROMOTION_ALREADY_ATTACHED
                    messages:
                      - The promotion is already attached to this plan.
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
        '422':
          description: >-
            422. The promotion cannot be attached. `reason` says why, for
            example `EXPIRED`, or `PROMOTIONS_NOT_ENABLED` when promotions are
            not turned on for the organization.
          content:
            application/json:
              examples:
                Result:
                  value:
                    code: PROMOTION_NOT_APPLICABLE
                    messages:
                      - The promotion cannot be applied.
                    reason: EXPIRED
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
                  reason:
                    type: string
                    description: Why the promotion cannot be attached or applied.
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.