> ## 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 suscripción

> Describe los atributos del objeto de suscripción, incluidos los ciclos de facturación, la frecuencia y el método de pago.

## Atributos

Este objeto representa una suscripción que se puede asociar a un cliente.

> [!NOTE]
>
> **Campos que calcula Yuno**
>
> `billing_cycles.scheduling_date`, `retries.stopped`, `retries.attempts_made`, `retries.outcome` y `retries.next_retry_at` los calcula Yuno a partir del estado propio de la suscripción. Son de solo lectura: si los envías, se ignoran en [Crear suscripción](https://docs.y.uno/es/reference/subscriptions/create-subscription.md) y en [Actualizar suscripción](https://docs.y.uno/es/reference/subscriptions/update-subscription.md), y los valores que lees siempre son los de Yuno.

**id** `string`

El identificador único de la suscripción (MAX 64 ; MIN 36).

Ejemplo: 7304911d-5df9-429e-8488-ad41abea1a4c

**name** `string`

El nombre de la suscripción (MAX 255; MIN 3).

Ejemplo: sub\_001

**description** `string`

La descripción de la suscripción (MAX 255; MIN 3).

Ejemplo: Servicio de streaming

**account\_id** `string`

El identificador único de la cuenta que tendrá disponible el plan de suscripción para usar (MAX 64 ; MIN 36).

Ejemplo: 2404911d-5df9-429e-8488-ad41abea1a4b

**merchant\_reference** `string`

Identificación del plan de suscripción (MAX 255; MIN 3).

Ejemplo: 001\_marzo\_23

**soft\_descriptor** `string`

Descriptor que aparece en el estado de cuenta bancario del titular de la tarjeta (MAX 255). Cuando se define, se propaga a cada pago de recobro que genera el motor de suscripciones. Los límites de longitud y formato varían según el proveedor; consulta [Descriptor en pagos recurrentes](https://docs.y.uno/es/docs/payment-features/subscriptions/soft-descriptor.md).

Ejemplo: ACME SUBSCRIPTION

**country** `string`

El país de la suscripción.

Ejemplo: CO

**status** `enum`

Estado de la suscripción.

Valores posibles del enum:

* `CREATED` = Estado transitorio mientras el pago inicial aún no se ha procesado. Solo ocurre cuando la suscripción se crea con `initial_payment_validation: true`; pasa a `ACTIVE` cuando el primer pago es exitoso (o a `CANCELED` si falla y se agotan los reintentos).
* `ACTIVE` = La suscripción se creó con un cliente asociado y ya está activa.
* `TRIALING` = La suscripción está dentro de la fase de prueba inicial de un plan (consulta `plan_id`/`current_phase`). Pasa a `ACTIVE` automáticamente cuando termina la prueba; esto se notifica por webhook como cualquier otro cambio de estado.
* `PAST_DUE` = Un cobro recurrente falló y la suscripción espera su recuperación. Sigue facturando y aún se puede cancelar; el siguiente cobro exitoso la devuelve a `ACTIVE`, o a `TRIALING` si la fase de prueba aún está en curso, y cada transición se notifica por webhook. Si el estado no está habilitado para tu cuenta, un cobro fallido deja la suscripción en `ACTIVE` mientras se ejecutan los reintentos. Consulta [Reintentos](https://docs.y.uno/es/docs/payment-features/subscriptions/retries.md).
* `PAUSED` = La suscripción se pausó y se puede reactivar.
* `COMPLETED` = La suscripción se completó porque llegó a la fecha y hora de finalización.
* `CANCELED` = Suscripción cancelada. Consulta `cancellation_source` para saber qué la originó.

**cancellation\_source** `enum`

Qué causó la cancelación de la suscripción. Solo se define cuando la suscripción llega a `CANCELED`; en otro caso es `null`.

Valores posibles:

* `MERCHANT` = Tú cancelaste la suscripción, mediante [Cancelar suscripción](https://docs.y.uno/es/reference/subscriptions/cancel-subscription.md) o el dashboard.
* `SYSTEM` = Yuno canceló la suscripción automáticamente. Esto incluye una suscripción creada con `initial_payment_validation: true` cuyo primer pago no fue exitoso.
* `PLAN_CHANGE` = La suscripción se reemplazó como parte de un [cambio de plan](https://docs.y.uno/es/reference/subscriptions/change-subscription-plan.md). Una nueva suscripción continúa la facturación del cliente con el nuevo plan.
* `RETRIES_EXHAUSTED` = Los reintentos de un ciclo de facturación terminaron sin un pago exitoso mientras la suscripción tenía `retries.cancel_on_exhausted_retries` en `true`. Consulta [Reintentos](https://docs.y.uno/es/docs/payment-features/subscriptions/retries.md#canceling-a-subscription-when-retries-run-out).

> [!NOTE]
>
> Trata este campo como abierto. Pueden incorporarse valores nuevos a medida que Yuno agregue comportamientos de cancelación, por lo que debes manejar un valor desconocido sin errores en lugar de evaluar de forma exhaustiva la lista anterior. `RETRIES_EXHAUSTED` es la incorporación más reciente.

**plan\_id** `string`

El identificador único del [plan](https://docs.y.uno/es/reference/plans/the-plan-object.md) a partir del cual se creó esta suscripción, si existe (MAX 64; MIN 36). Solo está presente cuando la suscripción está vinculada a un plan, y no aparece (no es `null`) en las suscripciones creadas con un `amount`/`frequency` directos en lugar de un `plan_id`.

Ejemplo: 00000000-0000-4000-8000-000000000001

**plan\_assigned\_at** `Timestamp`

Cuando la suscripción está vinculada a un plan, el momento en que se asoció el plan: al crearla a partir de un plan, al migrarla a un plan o en un cambio de plan. Solo está presente en suscripciones vinculadas a un plan.

**previous\_subscription\_id** `string`

Cuando esta suscripción se creó mediante un [cambio de plan](https://docs.y.uno/es/reference/subscriptions/change-subscription-plan.md) (pasar una suscripción existente a un plan distinto), este es el `id` de la suscripción que reemplazó. Solo está presente en ese caso.

Un `plan_change` programado con [Actualizar suscripción](https://docs.y.uno/es/reference/subscriptions/update-subscription.md), ya sea que se ejecute más adelante en el siguiente ciclo de facturación o que se aplique de inmediato (`IMMEDIATE`) en la misma llamada, se aplica a esta misma suscripción y nunca define este campo. Reactivar una suscripción `CANCELED` o `COMPLETED` tampoco lo define: al reactivar, se devuelve la misma suscripción a un estado activo en lugar de crear una sucesora.

**phases** `array of objects`

Las definiciones de fases del plan vinculado, tal como las declara el plan. Solo está presente en suscripciones vinculadas a un plan que tiene fases.

Esta es la escala del plan, no la de este suscriptor. A diferencia de `billing_phases`, incluye la fase terminal `REGULAR`, y se lee del plan en lugar de capturarse al crear la suscripción, por lo que refleja el plan tal como está hoy. En la fila `REGULAR`, `duration`, `frequency` y `amount` son todos `null`: esa fase se ejecuta hasta que termina la suscripción y su precio se resuelve desde el plan en cada facturación.

Usa `billing_phases` para saber lo que realmente se cobrará a esta suscripción, y `phases` para describir el plan en que se basa.

**propiedades**

**order** `int`

**name** `string`

**type** `enum`

`TRIAL` o `REGULAR`.

**duration** `object`

Cuánto dura la fase, como `type` y `value`. Es `null` en la fase `REGULAR`.

**frequency** `object`

Con qué frecuencia factura la fase, como `type` y `value`. Es `null` en la fase `REGULAR`.

**amount** `object`

El precio de la fase, como `currency` y `value`. Es `null` en la fase `REGULAR`.

**total\_payments** `int`

Cuántos cobros cubre la fase. Es `null` en la fase `REGULAR`.

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

Precios de la fase específicos por país, cada uno con un `country` y un `amount`. Está vacío cuando la fase no tiene ninguno.

**current\_phase** `enum`

En qué fase de la escala de prueba del plan vinculado se encuentra actualmente la suscripción. Solo está presente en suscripciones vinculadas a un plan. Tampoco aparece cuando la suscripción se creó mediante un [cambio de plan](https://docs.y.uno/es/reference/subscriptions/change-subscription-plan.md) con `skip_trial: true`: esa suscripción está vinculada a un plan y su plan tiene fases, pero nunca entra en la escala.

Valores posibles: `TRIAL`, `REGULAR`.

**current\_phase\_end** `Timestamp`

Cuándo la fase indicada por `current_phase` pasa a la siguiente: para una suscripción en su prueba, el momento en que cambia al precio regular. Es el final del último período de facturación que cubre la fase, por lo que en el último período de una prueba es igual a `current_period_end`.

Es `null` en suscripciones que no están dentro de una fase: las que no tienen plan y las vinculadas a un plan que ya salieron de la escala y están en el precio regular del plan.

Ejemplo: 2023-03-16T20:00:00.786342Z

**billing\_phases** `array of objects`

Las fases TRIAL iniciales del plan, capturadas para el país de este suscriptor en el momento de la creación. Solo está presente en suscripciones vinculadas a un plan que tiene fases. Tampoco aparece cuando la suscripción se creó mediante un [cambio de plan](https://docs.y.uno/es/reference/subscriptions/change-subscription-plan.md) con `skip_trial: true`: esa suscripción está vinculada a un plan y su plan tiene fases, pero nunca entra en la escala.

> [!WARNING]
>
> **La fase terminal REGULAR nunca se incluye aquí.** Su precio no se fija al crear la suscripción: se resuelve desde el plan en cada facturación, de modo que los cambios de precio del plan llegan a las suscripciones en curso. Cuando `current_phase` es `REGULAR`, la escala está agotada y la suscripción factura el precio regular del plan; no hay una fila correspondiente en este arreglo.

**propiedades**

**order** `int`

**type** `enum`

Siempre `TRIAL`, consulta la nota anterior.

**name** `string`

Refleja el `name` obligatorio de la propia fase.

**amount** `object`

**propiedades**

**currency** `string`

**value** `number`

**frequency** `object`

**propiedades**

**type** `enum`

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

**value** `int`

**start\_cycle** `int`

**end\_cycle** `int`

**amount** `object`

Especifica el objeto de monto de la suscripción, con el valor y la moneda.

**propiedades**

**currency** `enum`

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

Valores posibles del enum: Consulta la [Referencia de países](https://docs.y.uno/es/reference/country-reference.md).

**value** `number`

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

Ejemplo: 12100.00

**frequency** `object`

La frecuencia definida para la suscripción de pago. Si no se define, los valores predeterminados son MONTH para el tipo y 1 para el valor.

**propiedades**

**type** `enum`

El tipo de intervalo que tendrá la suscripción en el tiempo. Si no se define, siempre es MONTH de forma predeterminada.

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

En una suscripción cuyo `payment_method.type` es `PIX_AUTOMATIC`, solo se aceptan `WEEK`, `MONTH` y `YEAR` con `value` igual a `1`; cualquier otra combinación se rechaza con `400 INVALID_PARAMETERS`. Consulta [Pix Automático](https://docs.y.uno/es/docs/payment-features/subscriptions/pix-automatico.md#accepted-billing-cadences).

**value** `int`

El valor entre cada intervalo que tendrá la suscripción en el tiempo. Si no se define, siempre es 1 de forma predeterminada.

Ejemplo: 1

**billing\_cycles** `object`

Especifica el objeto billing\_cycles.

**propiedades**

**total** `number`

Cantidad total de ciclos de facturación.

Ejemplo: 10

**current** `number`

El **siguiente** ciclo de facturación que se cobrará, no el ciclo que está en curso.

Las suscripciones se facturan por adelantado: el cobro de un ciclo se ejecuta al inicio del período que paga, y el contador avanza en cuanto ese cobro se envía. Mientras el suscriptor está dentro del período pagado por el ciclo N, este campo ya muestra `N + 1`. El ciclo en curso es `current - 1`. Hay una excepción: el contador se detiene en el último ciclo. Cuando `current` llega a `billing_cycles.total`, o pasa `availability.finish_at`, la suscripción se marca como `COMPLETED` y `current` queda fijo en `total` durante todo ese último período, por lo que en ese caso el ciclo en curso es `current`, no `current - 1`.

Una suscripción creada con una prueba de dos ciclos muestra `current: 2` durante todo el primer período de prueba, y `current: 3` durante el segundo: la prueba sigue en curso aunque `current` haya superado la cantidad de ciclos de la prueba. `current_period_start` y `current_period_end` indican *cuándo* transcurre el período actual; no indican si la suscripción sigue en su prueba. Para ubicar la prueba, compara el ciclo en curso (`current - 1`) con `trial_period.billing_cycles`; las suscripciones `trial_period` heredadas se mantienen en `ACTIVE` y no tienen `current_phase` mientras están en prueba.

Como el contador avanza cuando se envía un cobro y no cuando es exitoso, un ciclo fallido nunca lo revierte: `current` ya avanzó antes de que se ejecute el primer reintento, y se queda ahí aunque los reintentos terminen cobrando o no.

El primer ciclo es la otra excepción: cuando `initial_payment_validation` es `true`, su contador avanza solo cuando ese primer cobro es exitoso. Mientras el cobro está pendiente o en reintento, `current` se mantiene en `1`; si nunca se cobra, la suscripción se cancela con `current` todavía en `1`. A partir del segundo ciclo se aplica la regla del momento del envío.

Ejemplo: 2

**next\_at** `Timestamp`

La fecha del siguiente pago de la suscripción. Siempre está presente. Cuando se devuelve `current_period_end`, es exactamente el mismo instante.

Ejemplo: 2023-02-16T20:00:00.786342Z

**scheduling\_date** `Timestamp`

Cuándo se entrega la instrucción de débito al riel de Pix: exactamente `next_at` menos cuatro días. Solo está presente en suscripciones `PIX_AUTOMATIC` que ejecuta Yuno, y solo para organizaciones que tienen habilitado el plazo de programación de cuatro días; no aparece (no es `null`) en ningún otro caso. Se devuelve en [Obtener suscripción](https://docs.y.uno/es/reference/subscriptions/retrieve-subscription.md), en los elementos de [Listar suscripciones](https://docs.y.uno/es/reference/subscriptions/list-subscriptions.md) y en los payloads de webhook de suscripciones. Consulta [Pix Automático](https://docs.y.uno/es/docs/payment-features/subscriptions/pix-automatico.md#the-scheduling-date).

Ejemplo: 2026-11-27T00:00:00Z

**current\_period\_start** `Timestamp`

El inicio del período de facturación actualmente en curso: una cadencia de facturación antes de `current_period_end`. Se deriva del calendario, no de los pagos, por lo que una suscripción informa su ventana desde el momento en que se crea, antes de que se haya intentado cualquier cobro.

La cadencia utilizada es la que programó la ventana. Dentro de una fase de un plan (una prueba, un precio introductorio, cualquier fase de un [plan](https://docs.y.uno/es/reference/plans/the-plan-object.md)), es el paso propio de la fase, por lo que una prueba de 14 días informa períodos de 14 días aunque el plan facture mensualmente. En el primer ciclo después de que termina una fase, la ventana todavía mide la cadencia de la fase que la programó.

Nunca queda antes de `availability.start_at`: el primer período de una suscripción comienza cuando comienza la suscripción.

Se devuelve en [Obtener suscripción](https://docs.y.uno/es/reference/subscriptions/retrieve-subscription.md), en [Listar suscripciones](https://docs.y.uno/es/reference/subscriptions/list-subscriptions.md) y en los payloads de webhook de suscripciones.

Las suscripciones terminales informan su último período de facturación en lugar de pasar a `null`: una suscripción `CANCELED` o `COMPLETED` conserva la última ventana que tuvo, igual que `PAUSED` congela su ventana en lugar de avanzarla. Es `null`, junto con `current_period_end`, solo cuando la suscripción no tiene ninguna cadencia recurrente. En las respuestas REST, las claves pueden omitirse por completo en lugar de enviarse como `null`: trata null y ausente como lo mismo.

Ejemplo: 2023-01-16T20:00:00.912480Z

**current\_period\_end** `Timestamp`

El final del período de facturación actualmente en curso, que también es cuando se programa el siguiente cobro. Siempre es igual a `billing_cycles.next_at`.

Este par describe el período en el que la suscripción está **programada**, no uno que necesariamente esté pagado: si el cobro de un ciclo falló y sus reintentos siguen en ejecución, la ventana ya se movió al período que ese cobro debía abrir. Una suscripción `PAUSED` conserva la ventana dentro de la cual se pausó en lugar de avanzarla, y una suscripción `CANCELED` o `COMPLETED` conserva su ventana final en lugar de borrarla; en ambos casos `current_period_end` puede estar muy en el pasado, así que revisa `status` antes de leerlo como una fecha futura.

Es `null` bajo las mismas condiciones que `current_period_start`; los dos siempre se devuelven juntos.

Ejemplo: 2023-02-16T20:00:00.786342Z

**billing\_date** `object`

\[Opcional] Especifica el objeto billing\_date. Es mutuamente excluyente con el objeto frequency.

**propiedades**

**type** `string`

El tipo de billing\_date que tendrá la suscripción en el tiempo. PREPAID, POSTDATE, DAY. Si no se define, se establece de forma predeterminada la fecha de creación del plan.

Ejemplo: DAY

**day** `number`

El día del mes en que se cobra la suscripción si el tipo es DAY. Siempre es 1 de forma predeterminada.

Ejemplo: 2

**customer\_payer** `object`

Especifica el objeto customer\_payer.

**propiedades**

**id**\* `string`

El identificador único del cliente (MAX 255; MIN 3).

Ejemplo: 3t04911d-5df9-429e-8488-ad41abea1a2c

**payment\_method** `object`

Especifica el objeto payment\_method.

**propiedades**

**type** `enum`

Tipo de método de pago.

Valores posibles del enum: `CARD`, `PAYPAL_ENROLLMENT`, `PIX_AUTOMATIC`

`PIX_AUTOMATIC` factura un mandato de Pix Automático de Brasil, se compara sin distinguir mayúsculas de minúsculas y solo acepta las cadencias que el mandato puede expresar; consulta [Pix Automático](https://docs.y.uno/es/docs/payment-features/subscriptions/pix-automatico.md).

**token** `string`

El token del método de pago de un solo uso que proporciona el Yuno SDK (MAX 64; MIN 36).

Ejemplo: 9104911d-5df9-429e-8488-ad41abea1a4b

**vaulted\_token** `string`

El token almacenado del método de pago guardado (MAX: 64; MIN: 36).

Ejemplo: 6104911d-5df9-429e-8488-ad41abea1a4b

**card** `object`

Especifica el objeto card.

**propiedades**

**verify** `boolean`

Con amount = 0 y verify = true, puedes verificar la tarjeta del usuario sin autorizar un monto real.

Valores posibles: `true` o `false`.

**card\_data** `object`

Especifica el objeto card\_data.

**propiedades**

**number** `string`

Número de la tarjeta sin separadores (MAX 19; MIN 8), disponible solo para comercios con certificación PCI.

Ejemplo: 4507990000000010

**expiration\_month** `number`

Mes de vencimiento de la tarjeta, MM (MAX 2; MIN 2), disponible solo para comercios con certificación PCI.

Ejemplo: 10

**expiration\_year** `number`

Año de vencimiento de la tarjeta, YYYY (MAX 4; MIN 4), disponible solo para comercios con certificación PCI.

Ejemplo: 2025

**security\_code** `number`

Código de seguridad de la tarjeta (MAX 4; MIN 3), disponible solo para comercios con certificación PCI.

Ejemplo: 123

**holder\_name** `string`

Nombre completo del titular de la tarjeta tal como aparece en ella (MAX 26; MIN 2), disponible solo para comercios con certificación PCI.

Ejemplo: JOHN DOE

**trial\_period** `object`

Especifica el objeto trial\_period.

**propiedades**

**billing\_cycles** `number`

Cantidad total de ciclos de facturación a los que debe aplicarse el free\_trial.

Ejemplo: 1

**amount** `object`

Monto que se descontará durante el período de prueba.

**propiedades**

**currency** `string`

La moneda utilizada para el período de prueba. (ISO 4217 MAX 3; MIN 3).

Ejemplo: COP

**value** `number`

El valor del monto del período de prueba (múltiplo de 0.0001).

Ejemplo: 10

**availability** `object`

Especifica el objeto availability. Las fechas en que la suscripción estará disponible. Si es null, la fecha de inicio será el día de la creación y no tendrá fecha de finalización.

**propiedades**

**start\_at** `Timestamp`

La fecha de inicio desde la que la suscripción estará disponible para usar.

Ejemplo: 2024-01-16T00:00:00.786342Z

**finish\_at** `Timestamp`

La fecha de finalización hasta la que la suscripción estará disponible para usar.

Ejemplo: 2024-05-26T20:00:00.786342Z

**retries** `object`

Especifica el objeto retries. Define si se deben reintentar en Yuno las transacciones rechazadas y la cantidad, si es necesario.

**propiedades**

**retry\_on\_decline** `bool`

Si se debe reintentar un pago o no después de un primer rechazo. False de forma predeterminada.

Ejemplo: true

**amount** `number`

La cantidad de reintentos que tendrá el plan de suscripción hasta completarse. El máximo es igual a la longitud del calendario de reintentos configurado en tu entorno (6 en producción). Un valor por encima del tope se rechaza con `400` (`Max retries attempts exceeded`). Máx.: 6

Ejemplo: 4

**strategy** `string`

Cómo se decide el momento de cada reintento. Una de las siguientes:

* `DEFAULT`: el calendario de reintentos fijo.
* `SMART`: momento de reintento basado en aprendizaje automático, aplicado a partir del segundo reintento. Disponible para todas las cuentas.
* `CUSTOM_SCHEDULE`: el arreglo `schedule` por intento que tú proporcionas.

Trata este campo como abierto. Pueden incorporarse valores nuevos a medida que Yuno agregue comportamientos de reintento, por lo que debes manejar un valor desconocido sin errores en lugar de evaluar de forma exhaustiva la lista anterior. `SMART` es la incorporación más reciente.

Ejemplo: `SMART`

**stop\_on\_hard\_decline** `bool`

Cuando es true y se detecta un rechazo definitivo, los reintentos se detienen solo para el ciclo de facturación actual. Por sí solo, la suscripción se mantiene ACTIVE y la facturación avanza al siguiente ciclo. Si `cancel_on_exhausted_retries` también es true, la suscripción se cancela.

Ejemplo: true

**cancel\_on\_exhausted\_retries** `bool`

Cuando es true, la suscripción se cancela una vez que los reintentos de un ciclo de facturación terminan sin un pago exitoso, en lugar de avanzar al siguiente ciclo. `cancellation_source` se define como `RETRIES_EXHAUSTED` y se emite un único webhook `SUBSCRIPTION.CANCEL`. El valor predeterminado es false. Solo se define al crear: no se puede cambiar después, y [Actualizar suscripción](https://docs.y.uno/es/reference/subscriptions/update-subscription.md) rechaza con `400` un valor distinto. La cancelación en sí es definitiva; consulta [Reintentos](https://docs.y.uno/es/docs/payment-features/subscriptions/retries.md#canceling-a-subscription-when-retries-run-out).

Ejemplo: true

**stopped** `bool`

Si los reintentos del ciclo actual se han detenido. Solo está presente mientras la suscripción está `PAST_DUE` o tiene una `cancel_scheduled` pendiente; en otro caso se omite.

> [!NOTE]
>
> Si este campo (y `attempts_made`, `outcome`, `next_retry_at` más abajo) sigue informando la instantánea de reintentos del último ciclo una vez que la suscripción llega a `CANCELED`, o se omite en ese momento, está pendiente de confirmación del producto; verifica con una respuesta real antes de depender de ello.

**attempts\_made** `int`

Intentos de reintento realizados hasta ahora en el ciclo actual. Solo está presente mientras la suscripción está `PAST_DUE` o tiene una `cancel_scheduled` pendiente; en otro caso se omite.

**outcome** `enum`

Cómo se resolvieron los reintentos del ciclo actual. Uno de `RECOVERED`, `EXHAUSTED` o `ABANDONED` (reintentos detenidos por una cancelación antes de agotarse por sí solos). Solo está presente mientras la suscripción está `PAST_DUE` o tiene una `cancel_scheduled` pendiente; en otro caso se omite.

**next\_retry\_at** `Timestamp`

Cuándo está programado el siguiente reintento. Solo está presente mientras la suscripción está `PAST_DUE` con reintentos aún en ejecución; en otro caso se omite.

**profile** `enum`

La escala de reintentos fija que sigue la suscripción en lugar del calendario configurable. Siempre `PIX_AUTOMATIC`. Solo está presente en suscripciones `PIX_AUTOMATIC` que ejecuta Yuno; no aparece (no es `null`) en ningún otro método de pago, junto con `max_attempts`, `min_gap_hours` y `until` más abajo. Consulta [Pix Automático](https://docs.y.uno/es/docs/payment-features/subscriptions/pix-automatico.md#the-retry-ladder).

**max\_attempts** `int`

Cuántos reintentos ejecuta la escala de Pix. Siempre `3`, igual que el `amount` informado para estas suscripciones.

**min\_gap\_hours** `int`

Siempre `24`: el intervalo entre las **fechas de débito** de la escala, no entre los intentos de envío. Las fechas de débito de la escala son `D`, `D+1`, `D+2` y `D+3`; cuando un débito se rechaza de forma síncrona, la siguiente instrucción puede enviarse momentos después, por lo que debes comparar las fechas de débito y no los momentos de envío.

**until** `Timestamp`

Cuándo se detiene la escala: `billing_cycles.next_at` más 7 días. Sigue el ciclo, por lo que se mueve junto con `next_at` en cada renovación.

**cancel\_scheduled** `object`

La cancelación programada para esta suscripción, o `null` cuando no hay ninguna pendiente. Programa una con el bloque `schedule` en `POST /v1/subscriptions/{id}/cancel`; deshazla con `"schedule": null`. Consulta [Cancelar suscripción](https://docs.y.uno/es/reference/subscriptions/cancel-subscription.md).

**propiedades**

**mode** `enum`

`AFTER_CYCLES` o `AT_DATE`, según cuál de `after_cycles`/`at` se envió cuando se creó la programación.

**after\_cycles** `int`

La cantidad de ciclos de facturación que se solicitó, cuando `mode` es `AFTER_CYCLES`. Es `null` cuando `mode` es `AT_DATE`.

**at** `Timestamp`

La fecha y hora resueltas en que se ejecutará la cancelación.

**requested\_at** `Timestamp`

Cuándo se programó la cancelación.

**past\_due\_behavior** `enum`

`EXHAUST_RETRIES` (predeterminado) o `SKIP_RETRIES`: lo que hace la programación si la suscripción está `PAST_DUE` cuando de otro modo se ejecutaría. Consulta [Cancelar suscripción](https://docs.y.uno/es/reference/subscriptions/cancel-subscription.md#behavior-while-retries-are-running).

> [!NOTE]
>
> Este eco está pendiente de confirmación del producto como contrato externo estable; consulta la nota en [Cancelar suscripción](https://docs.y.uno/es/reference/subscriptions/cancel-subscription.md#behavior-while-retries-are-running).

**refund\_rule** `object`

La regla vigente que se usa para calcular un reembolso `CUSTOM` al cancelar cuando la solicitud de cancelación no incluye `refund_amount`. Se omite (no es `null`) cuando no hay ninguna regla configurada. Defínela en [Crear suscripción](https://docs.y.uno/es/reference/subscriptions/create-subscription.md#setting-a-refund-rule) o [Actualizar suscripción](https://docs.y.uno/es/reference/subscriptions/update-subscription.md#setting-a-refund-rule); envía `"refund_rule": null` en la actualización para borrarla. Disponible para las organizaciones que la tienen habilitada; contacta a Yuno. Consulta [Cancelar suscripción](https://docs.y.uno/es/reference/subscriptions/cancel-subscription.md#custom) para ver cómo se usa.

**propiedades**

**type** `enum`

`PERCENT` o `FIXED`. Los dos son excluyentes: una regla `PERCENT` lleva solo `percent`, y una regla `FIXED` solo `amount`.

**percent** `decimal`

La parte del monto cobrado que se reembolsa, entre `0` y `100`, cuando `type` es `PERCENT`. Se aplica sobre lo que realmente se cobró en el ciclo, por lo que no necesita una moneda propia.

**amount** `object`

El monto fijo que se reembolsa cuando `type` es `FIXED`, como `value` y `currency`. Su moneda debe ser igual a la moneda propia de la suscripción: una solicitud que dejaría a ambas en desacuerdo se rechaza con `REFUND_RULE_CURRENCY_MISMATCH`, incluida una actualización que cambia la moneda de la suscripción mientras todavía hay almacenada una regla `FIXED` en la moneda anterior.

**pause\_until** `Timestamp`

Cuándo se reanudará por sí sola una suscripción pausada. Solo está presente mientras `status` es `PAUSED` y se indicó una duración al pausar; se omite (no es `null`) en una pausa sin fecha de fin y en cualquier otro estado. Se define con `pause_cycles` o `pause_until` en [Pausar suscripción](https://docs.y.uno/es/reference/subscriptions/pause-subscription.md#pause-for-a-set-time); una duración indicada en ciclos se resuelve a un instante una sola vez, en el momento de la pausa, y se informa aquí en cada lectura posterior.

**unpaid\_cycle** `object`

El ciclo de facturación actual, cuando está `PAST_DUE` y no se ha saldado. Se omite (no es `null`) en cualquier otro estado.

> [!NOTE]
>
> Si este campo sigue informando el ciclo sin saldar una vez que la suscripción llega a `CANCELED`, o se omite en ese momento, está pendiente de confirmación del producto; verifica con una respuesta real antes de depender de ello.

**propiedades**

**cycle\_number** `int`

El ciclo de facturación que está sin pagar, igual a `billing_cycles.current` en el momento en que se calculó.

**amount** `object`

El monto adeudado del ciclo sin pagar. Tiene la misma estructura que el `amount` a nivel de suscripción.

**attempts** `int`

Total de intentos de cobro realizados hasta ahora para este ciclo, incluido el intento original.

**last\_failure\_code** `string`

El código de rechazo o fallo del intento más reciente. Es `null` si no está disponible.

**refund** `object`

La cotización de reembolso de la última cancelación inmediata, o `null`/se omite cuando nunca se calculó ninguna. Se solicita con el modo `refund` en
`POST /v1/subscriptions/{id}/cancel`; consulta
[Cancelar suscripción](https://docs.y.uno/es/reference/subscriptions/cancel-subscription.md#refund-on-immediate-cancel).
Una vez calculada, persiste y sigue apareciendo en cada lectura posterior de la suscripción.

**propiedades**

**mode** `enum`

`PRORATED`, `FULL` o `CUSTOM`: refleja lo que se solicitó.

**amount** `object`

El monto de reembolso calculado (o reflejado, en `CUSTOM`). Tiene la misma estructura que el
`amount` a nivel de suscripción.

**unused\_days** `int`

Días del ciclo de facturación que se consideran sin usar. En `FULL`, es igual a `period_days`: todo el
ciclo cuenta como sin usar.

**period\_days** `int`

La duración total del ciclo de facturación en días.

**basis** `object`

Contra qué se calculó el reembolso.

**propiedades**

**billing\_cycle** `int`

El ciclo de facturación contra el que se calculó el reembolso.

**charged\_amount** `object`

El monto realmente cobrado por ese ciclo: el tope del reembolso.

**payment\_id** `string`

El id propio del pago capturado. Es `null` para una cotización de fase de `$0` sin un pago al
que hacer referencia.

**charged\_at** `Timestamp`

Cuándo se capturó ese pago. Es `null` para una cotización de fase de `$0` sin un pago al
que hacer referencia.

**execution** `string`

Siempre `"MERCHANT"`: Yuno calcula la cotización, tú ejecutas el reembolso.

**quoted\_at** `Timestamp`

Cuándo se calculó esta cotización.

**initial\_payment\_validation** `bool`

Indicador para identificar si la suscripción debe esperar el primer pago para continuar. False de forma predeterminada.

Ejemplo: false

**pending\_plan\_change** `object`

El cambio de plan programado para el siguiente ciclo de facturación, o `null` cuando no hay ninguno pendiente. Programa uno con el bloque `plan_change` en `PATCH /v1/subscriptions/{id}`; deshazlo con `"plan_change": null`.

Un cambio programado se aplica a esta misma suscripción: no se crea ninguna suscripción nueva, y no se define ni `previous_subscription_id` ni `cancellation_source: PLAN_CHANGE`.

**propiedades**

**plan\_id** `string`

El identificador del plan de destino.

**plan\_name** `string`

El nombre del plan de destino.

**direction** `string`

`UPGRADE` o `DOWNGRADE`. Una frecuencia de facturación más larga es un upgrade; con la misma frecuencia, un precio resuelto más alto es un upgrade. Solo informativo.

**effective** `string`

Cuándo se aplica el cambio. Siempre `NEXT_BILLING_CYCLE`: aquí solo aparecen los cambios programados. Un cambio de plan `IMMEDIATE` (consulta [Actualizar suscripción](https://docs.y.uno/es/reference/subscriptions/update-subscription.md)) se aplica en el lugar y nunca queda pendiente.

**phases\_behavior** `string`

Qué sucede cuando el plan de destino tiene fases. `START_FROM_REGULAR` (predeterminado) entra directamente en la fase regular; `HONOR_PHASES` entra por el calendario de fases del plan de destino, lo que establece `status` en `TRIALING`, `current_phase` en `TRIAL` y vuelve a poblar `billing_phases`.

**applies\_at** `Timestamp`

El evento de facturación en el que el cambio tendrá efecto: la siguiente fecha de facturación de la suscripción.

**requested\_at** `Timestamp`

Cuándo se programó el cambio.

**metadata** `array of objects`

Especifica el arreglo metadata.

**propiedades**

**key** `string`

Este valor sirve como nombre o identificador de los metadatos. Usa un término descriptivo. (MAX 48; MIN 1).

Ejemplo: sub\_ext\_id

**value** `string`

La información que deseas almacenar en los metadatos. (MAX 512; MIN 1).

Ejemplo: AA001

**subscription\_agreement\_id** `string`

Vincula esta suscripción con el pago inicial creado con el mismo ID de acuerdo. Se usa para seguimiento, conciliación y gestión de contracargos (MAX 255).

El valor debe coincidir exactamente con el `subscription_agreement_id` enviado en `payment_method.detail.card.stored_credentials.subscription_agreement_id` en el pago de origen (`payment_method.detail.wallet.stored_credentials.subscription_agreement_id` cuando el pago de origen es un CIT de wallet).

Ejemplo: sa\_6af2dfcd-44c0-4f16-a331-8bed3ed9c9fa

**payments** `Array of strings`

Especifica el arreglo payments.

> [!NOTE]
>
> Actualmente este arreglo siempre está vacío en los payloads de webhook. Suscríbete a los webhooks `payment.*` para dar seguimiento a los cobros. Para el historial completo de cobros de la suscripción (montos, proveedor, contexto de fase), usa [Listar pagos de la suscripción](https://docs.y.uno/es/reference/subscriptions/list-subscription-payments.md) en lugar de este campo.

Ejemplo: \["5104911d-5df9-229e-8468-bd41abea1a4s"]

**renewal\_notification\_days** `int`

Cantidad de días antes de la siguiente fecha de facturación en que se envía el webhook `subscription.close_to_renewal`. `null` significa que no se envía ninguna notificación de renovación para esta suscripción.

Ejemplo: 3

**reason** `string`

Motivo libre del estado actual de la suscripción, cuando se registró uno. Es `null` en suscripciones cuyo estado cambió sin motivo, de máximo 255 caracteres.

Se define con el campo `reason` propio de la suscripción en [Crear suscripción](https://docs.y.uno/es/reference/subscriptions/create-subscription.md), [Actualizar suscripción](https://docs.y.uno/es/reference/subscriptions/update-subscription.md), [Pausar suscripción](https://docs.y.uno/es/reference/subscriptions/pause-subscription.md) y [Reanudar suscripción](https://docs.y.uno/es/reference/subscriptions/resume-subscription.md); cada una escribe su propio `reason`, por lo que uno posterior sobrescribe a uno anterior. Reactivar una suscripción `CANCELED` o `COMPLETED` lo devuelve a `null`.

Ejemplo: "merchant request"

**cancellation\_time** `Timestamp`

Cuándo se canceló la suscripción ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)). Solo se define cuando la suscripción llega a `CANCELED`; en otro caso es `null`. Consulta `cancellation_source` para saber qué la originó.

Ejemplo: 2023-12-16T20:46:54.786342Z

**ending\_time** `Timestamp`

Cuándo se completó o venció la suscripción ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)). Solo se define cuando la suscripción llega a `COMPLETED`; en otro caso es `null`.

Ejemplo: 2024-12-16T20:46:54.786342Z

**created\_at** `Timestamp`

Fecha y hora de creación de la suscripción ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) MAX 27; MIN 27).

Ejemplo: 2023-12-16T20:46:54.786342Z

**updated\_at** `Timestamp`

Fecha y hora de la última actualización de la suscripción ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) MAX 27; MIN 27).

Ejemplo: 2023-12-16T21:00:54.786342Z

**additional\_data** `object`

Especifica el objeto additional\_data. Este objeto no es obligatorio. Sin embargo, si envías esta información, la experiencia de pago de tu usuario mejorará.

**propiedades**

**order** `object`

Especifica el objeto order.

**propiedades**

**items** `array of object`

Especifica el objeto del ítem.

**propiedades**

**id** `string`

El identificador único del ítem (MAX 255; MIN 3).

Ejemplo: 3214

**name** `string`

El nombre del ítem (MAX 255; MIN 3).

Ejemplo: iPhone 12 Pro Max

**quantity** `int`

La cantidad del ítem (MAX 999; MIN 1).

Ejemplo: 1

**unit\_amount** `float`

El monto unitario del ítem (múltiplo de 0.0001).

Ejemplo: 550

**category** `string`

La categoría del ítem (MAX 255; MIN 3).

Valores posibles: Consulta la [Lista de categorías de ítems](https://docs.y.uno/es/reference/items-category-list.md).

**brand** `string`

La marca del ítem (MAX 255; MIN 3).

Ejemplo: Apple

**sku\_code** `string`

La unidad de mantenimiento de stock (SKU) del ítem (MAX 255; MIN 3).

Ejemplo: A2342

**manufacture\_part\_number** `string`

El número de parte del fabricante del ítem (MAX 255; MIN 3).

Ejemplo: 345621234


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