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

# El objeto de plan

> Documenta los atributos del objeto de plan, incluidos los precios por país, las fases y los metadatos.

## Atributos

Un plan es una entrada reutilizable de un catálogo de precios. Suscribe a un cliente a un plan en lugar de definir `amount`/`frequency` directamente en la suscripción, y todos los campos que definen "cuánto y con qué frecuencia" se resuelven a partir del plan.

**id** `string`

El identificador único del plan (MAX 64; MIN 36).

Ejemplo: 00000000-0000-4000-8000-000000000001

**account\_id** `string`

El identificador único de la cuenta a la que pertenece el plan (MAX 64; MIN 36).

Ejemplo: 00000000-0000-4000-8000-000000000002

**account\_ids** `Array of strings`

Las cuentas adicionales con las que se comparte el plan, sin incluir al propietario indicado en `account_id`. Vacío para un plan que pertenece a una sola cuenta. Solo se devuelve, el campo no se acepta al crear un plan.

Ejemplo: \["00000000-0000-4000-8000-000000000003"]

**name** `string`

El nombre del plan (MAX 255; MIN 3).

Ejemplo: Streaming Pro

**description** `string`

La descripción del plan. Actualmente no se aplica ningún límite de longitud.

Ejemplo: Access to Pro features, billed monthly

**merchant\_reference** `string`

Tu propio identificador para el plan. Actualmente no se aplica ningún límite de longitud.

Ejemplo: streaming-pro-monthly

**status** `enum`

Estado del plan.

Valores posibles:

* `ACTIVE` = Se puede suscribir al plan.
* `CANCELED` = El plan ya no acepta nuevas suscripciones. Cancelar un plan también cancela todas las suscripciones vinculadas a él en ese momento.

**base\_amount** `object`

El precio predeterminado que se cobra en cualquier país sin una entrada explícita en `country_prices`.

**properties**

**currency** `enum`

La moneda utilizada para realizar el pago (MAX 3; MIN 3; [ISO 4217](https://docs.y.uno/es/reference/country-reference.md)).

**value** `number`

El monto del pago (múltiplo de 0.0001).

Ejemplo: 20.00

**frequency** `object`

La frecuencia de facturación del plan. Toda suscripción creada a partir de este plan la hereda: no envíes `frequency` al suscribir con un `plan_id`.

**properties**

**type** `enum`

Valores posibles del enum: `DAY`, `WEEK`, `MONTH`, `QUARTER`, `HALF_YEAR` o `YEAR`.

**value** `int`

Ejemplo: 1

**country\_prices** `array of objects`

Precios explícitos por país. Un país que no aparece aquí usa `base_amount`.

**properties**

**country** `string`

MAX 2; MIN 2; [ISO 3166-1](https://docs.y.uno/es/reference/country-reference.md).

**amount** `object`

**properties**

**currency** `enum`

**value** `number`

**allowed\_payment\_methods** `array of strings`

Tipos de método de pago aceptados para las suscripciones de este plan.

Ejemplo: `["CARD", "PIX"]`

**metadata** `array of objects`

Pares clave-valor asociados al propio plan. Es independiente de cualquier `metadata` definido directamente en una suscripción: consulta el [objeto de suscripción](https://docs.y.uno/es/reference/subscriptions/the-subscription-object.md) para eso.

**properties**

**key** `string`

Ejemplo: campaign

**value** `string`

Ejemplo: app\_store

**phases** `array of objects`

Una escalera inicial opcional de fases (por ejemplo, un periodo de prueba) antes de que se aplique el precio regular del plan. Omítela para un plan fijo sin periodo de prueba.

**properties**

**order**\* `int`

Posición en la escalera, a partir de 1. El `order` más alto es la fase terminal, de precio regular, y no tiene `duration`. Obligatorio.

**name**\* `string`

Obligatorio y no vacío: toda fase debe tener un nombre.

**type**\* `enum`

Obligatorio. Valores posibles: `TRIAL` (cualquier fase inicial, con cualquier precio, incluido 0), `REGULAR` (la fase terminal).

**duration** `object`

Obligatorio en toda fase no terminal; se omite en la fase terminal.

**properties**

**type** `enum`

`DAY`, `WEEK`, `MONTH` o `YEAR`.

**value** `int`

**frequency** `object`

Opcional. Si se omite, la fase se factura como un único cobro de suma global que cubre toda la `duration`. Si se define, la fase se factura en cada intervalo de `frequency`. No aplica a la fase terminal.

**propiedades**

**type** `enum`

`DAY`, `WEEK`, `MONTH`, `QUARTER`, `HALF_YEAR` o `YEAR`.

**value** `int`

**amount** `object`

El precio fijo de la fase. Se permite 0 (un periodo de prueba gratuito).

> [!WARNING]
>
> En una fase **no terminal**, este campo o `country_prices` es obligatorio: uno de los dos. En la fase terminal REGULAR, omítelo por completo: enviar un `amount` allí se rechaza con `400 BAD_REQUEST` ("The terminal phase price comes from the plan base\_amount/country\_prices - remove the phase amount"). El precio de la fase terminal siempre proviene del `base_amount`/`country_prices` del propio plan, nunca de un campo a nivel de fase.

**country\_prices** `array of objects`

Precios por país para esta fase, con la misma forma que los `country_prices` a nivel de plan. En una fase no terminal, este campo o `amount` es obligatorio. No aplica a la fase terminal.

**total\_payments** `int`

Calculado por el servidor. Si se omite `frequency`, siempre es `1` (un único cobro de suma global por toda la fase). Si se define `frequency`, es `duration / frequency` (ambos en la misma unidad); por ejemplo, una duración de 3 meses facturada mensualmente (`frequency: {type: MONTH, value: 1}`) produce `3`. `null` en la fase terminal.

**subscribers\_count** `int`

El número de suscripciones activas (en cualquier estado no terminal) que hay actualmente en este plan. Este es el conjunto que afectaría una cancelación.

Ejemplo: 12

> [!NOTE]
>
> Solo lo devuelve [Listar planes](https://docs.y.uno/es/reference/plans/list-plans.md); no está presente en las respuestas de [Crear plan](https://docs.y.uno/es/reference/plans/create-plan.md) ni de [Consultar plan](https://docs.y.uno/es/reference/plans/retrieve-plan.md).

**countries** `array of strings`

Códigos ISO α2 ordenados: la unión distinta de todos los países que este plan fija explícitamente, a nivel de plan o dentro de cualquier fase. Un arreglo vacío significa que el plan se aplica globalmente mediante `base_amount`, no que no tenga cobertura.

> [!NOTE]
>
> Solo lo devuelve [Listar planes](https://docs.y.uno/es/reference/plans/list-plans.md); no está presente en las respuestas de [Crear plan](https://docs.y.uno/es/reference/plans/create-plan.md) ni de [Consultar plan](https://docs.y.uno/es/reference/plans/retrieve-plan.md).

**created\_at** `Timestamp`

**updated\_at** `Timestamp`

## Relacionado

* [Crear plan](https://docs.y.uno/es/reference/plans/create-plan.md)
* [Consultar plan](https://docs.y.uno/es/reference/plans/retrieve-plan.md)
* [Listar planes](https://docs.y.uno/es/reference/plans/list-plans.md)
* [Cancelar plan](https://docs.y.uno/es/reference/plans/cancel-plan.md)
* [El objeto de suscripción](https://docs.y.uno/es/reference/subscriptions/the-subscription-object.md): consulta `plan_id` para ver cómo una suscripción se vincula de vuelta a su plan


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.