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

# Consultar plan

> Obtiene los detalles completos de un plan, incluidas sus fases, los precios por país y las promociones asociadas.

> [!NOTE]
>
> **Promociones asociadas**
>
> La respuesta incluye una lista `promotions` con las promociones asociadas al plan, cada una con el número de `cycles` que cubre, su comportamiento `on_pause`, su `type` (`AUTOMATIC` o `CODE`) y su `status`. El `status` es `ENABLED` o `DISABLED`, leído del motor de promociones. Si el motor no responde, el estado es `UNKNOWN`. Asocia y elimina promociones con [Attach Promotion to Plan](https://docs.y.uno/es/reference/plans/attach-plan-promotion.md) y [Remove Promotion from Plan](https://docs.y.uno/es/reference/plans/remove-plan-promotion.md). Consulta [Promociones en planes de suscripción](https://docs.y.uno/es/docs/payment-features/subscriptions/promotions.md).


## OpenAPI

````yaml openapi/es/plans/retrieve-plan.json GET /subscriptions/plans/{plan_id}
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)
security:
  - sec0: []
    sec1: []
paths:
  /subscriptions/plans/{plan_id}:
    get:
      summary: Obtener plan
      operationId: retrieve-plan
      parameters:
        - in: header
          name: X-Account-Code
          required: true
          schema:
            type: string
          description: >-
            El `account_id` que se encuentra en tu [Yuno
            Dashboard](https://dashboard.y.uno/developers) (UUID). Obligatorio:
            si lo omites, se devuelve `400 BAD_REQUEST` ("Invalid x-account-code
            header.").
        - name: plan_id
          in: path
          description: El identificador único del plan.
          schema:
            type: string
          required: true
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value:
                    id: 00000000-0000-4000-8000-000000000001
                    account_id: 00000000-0000-4000-8000-000000000002
                    name: Streaming Pro
                    description: Access to Pro features, billed monthly
                    merchant_reference: streaming-pro-monthly
                    status: ACTIVE
                    base_amount:
                      currency: USD
                      value: 20
                    frequency:
                      type: MONTH
                      value: 1
                    country_prices:
                      - country: US
                        amount:
                          currency: USD
                          value: 20
                      - country: BR
                        amount:
                          currency: BRL
                          value: 99.9
                    allowed_payment_methods:
                      - CARD
                      - PIX
                    metadata:
                      - key: campaign
                        value: app_store
                    phases:
                      - order: 1
                        name: Intro
                        type: TRIAL
                        duration:
                          type: MONTH
                          value: 3
                        frequency:
                          type: MONTH
                          value: 1
                        amount:
                          currency: USD
                          value: 9.99
                        total_payments: 3
                        country_prices: []
                      - order: 2
                        name: Regular
                        type: REGULAR
                        duration: null
                        frequency: null
                        amount: null
                        total_payments: null
                        country_prices: []
                    promotions:
                      - promotion_id: 8f2d6c1e-3b7a-4c55-9a1e-2f4d8b7c6a10
                        name: Welcome 20% x3
                        type: AUTOMATIC
                        status: ENABLED
                        cycles: 3
                        on_pause: KEEP
                        attached_at: '2026-11-02T14:00:00Z'
                    created_at: '2024-01-15T10:30:00.000000Z'
                    updated_at: '2024-01-15T10:30:00.000000Z'
                    account_ids:
                      - a5b50509-2f47-444e-8056-feb736ad89ae
                    retries: null
                    retry_split: null
                    meters: []
              schema:
                type: object
                properties:
                  id:
                    type: string
                  account_id:
                    type: string
                  name:
                    type: string
                  description:
                    type: string
                    nullable: true
                  merchant_reference:
                    type: string
                  status:
                    type: string
                  base_amount:
                    type: object
                    properties:
                      currency:
                        type: string
                      value:
                        type: number
                  frequency:
                    type: object
                    properties:
                      type:
                        type: string
                      value:
                        type: integer
                  country_prices:
                    type: array
                    items:
                      type: object
                      properties:
                        country:
                          type: string
                        amount:
                          type: object
                          properties:
                            currency:
                              type: string
                            value:
                              type: number
                  allowed_payment_methods:
                    type: array
                    items:
                      type: string
                  metadata:
                    type: array
                    items:
                      type: object
                  phases:
                    type: array
                    items:
                      type: object
                  created_at:
                    type: string
                  updated_at:
                    type: string
                  account_ids:
                    type: array
                    items:
                      type: string
                    description: >-
                      Todas las cuentas en las que está disponible el plan.
                      Siempre se devuelve; contiene `account_id` cuando el plan
                      está limitado a una sola cuenta.
                  retries:
                    type: object
                    nullable: true
                    description: >-
                      La configuración de reintentos que heredan las
                      suscripciones creadas a partir de este plan. `null` cuando
                      el plan no define ninguna.
                  retry_split:
                    type: object
                    nullable: true
                    description: >-
                      La configuración de la división A/B de Smart Retries
                      asociada a este plan. `null` cuando no hay ninguna
                      definida.
                  meters:
                    type: array
                    items:
                      type: object
                    description: >-
                      Los precios medidos asociados a este plan. Vacío cuando el
                      plan no tiene precios basados en el uso; consulta [Attach
                      Meter to Plan](/es/reference/meters/attach-meter-to-plan).
                  promotions:
                    type: array
                    items:
                      type: object
                      properties:
                        promotion_id:
                          type: string
                          description: El ID de la promoción asociada (UUID).
                        name:
                          type: string
                          description: El nombre de la promoción.
                        type:
                          type: string
                          enum:
                            - AUTOMATIC
                            - CODE
                          description: >-
                            El modo de canje de la promoción. Las promociones
                            `AUTOMATIC` se aplican solas cuando se crea una
                            suscripción en el plan. Las promociones `CODE` se
                            aplican cuando el comercio envía el código.
                        status:
                          type: string
                          enum:
                            - ENABLED
                            - DISABLED
                            - UNKNOWN
                          description: >-
                            Se lee del motor de promociones. `UNKNOWN` cuando el
                            motor no responde.
                        cycles:
                          type: integer
                          description: >-
                            El número de cobros que cubre la promoción en este
                            plan.
                        on_pause:
                          type: string
                          enum:
                            - KEEP
                            - END
                          description: >-
                            Qué hace una pausa con una copia de esta promoción:
                            `KEEP` (predeterminado) o `END`.
                        attached_at:
                          type: string
                          format: date-time
                          description: Cuándo se asoció la promoción al plan.
                    description: >-
                      Las promociones asociadas a este plan. Vacío cuando no hay
                      ninguna asociada. Consulta [Promociones en planes de
                      suscripción](/es/docs/payment-features/subscriptions/promotions).
        '404':
          description: '404'
          content:
            application/json:
              examples:
                Result:
                  value:
                    code: PLAN_NOT_FOUND
                    messages:
                      - Plan not found.
                  summary: Result
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: PLAN_NOT_FOUND
                  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.