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

# Cancelar suscripción

> Cancela una suscripción de inmediato o programa la cancelación para una fecha futura o un ciclo de facturación.

Llamar a este endpoint con un cuerpo vacío (o sin cuerpo) cancela la suscripción de inmediato,
cambiando su `status` a `CANCELED`. Esto no cambió y sigue siendo definitivo: una vez inmediata, no se puede
revertir.

Puedes cancelar desde `CREATED`, `ACTIVE`, `TRIALING`, `PAST_DUE` y `PAUSED`. `COMPLETED` y
`CANCELED` son estados terminales, por lo que cancelar desde cualquiera de ellos devuelve `400 INVALID_STATE`, incluida una segunda
cancelación sobre una suscripción que ya está cancelada. Consulta [Estado de la suscripción](https://docs.y.uno/es/reference/subscriptions/status-subscriptions.md).

## Reembolso en la cancelación inmediata

> [!NOTE]
>
> **Solo organizaciones en la lista de permitidos**
>
> La cotización de reembolsos se habilita por organización, independientemente de la cancelación programada. Si tus llamadas
> devuelven `400` `"Refund quote is not enabled for this organization."`, contacta a tu representante de Yuno
> para que la habilite.

Envía un modo `refund` junto con una cancelación inmediata (sin `schedule`) para que Yuno calcule una
cotización de reembolso para el ciclo de facturación actual. Yuno solo **calcula** la cotización, nunca mueve dinero.
`refund.execution` en la respuesta siempre es `"MERCHANT"`: tú ejecutas el reembolso por tu
propio canal de pago, usando el monto cotizado como dato de entrada.

```json Cancel with a prorated refund theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "refund": "PRORATED"
}
```

| Value | Behavior |
| - | - |
| `NONE` (default) | No se calcula ningún reembolso. Es idéntico a omitir la clave `refund`. |
| `PRORATED` | Reembolsa la parte no usada del ciclo actual, según los días calendario. |
| `FULL` | Reembolsa el monto completo cobrado por el ciclo actual. |
| `CUSTOM` | Reembolsa un monto proporcionado por el comercio, con el tope de lo cobrado por el ciclo. |

`refund` no se puede combinar con `schedule`: enviar ambos, o enviar `refund` junto con
`"schedule": null`, se rechaza con `400` antes de escribir nada. `refund: NONE`, u omitir
`refund` por completo, sigue funcionando con normalidad junto con `schedule`.

### La base del reembolso

Todos los modos de reembolso se calculan sobre la misma base: **el pago capturado más reciente de la
suscripción**, nunca el precio de lista de la propia suscripción ni una estimación. Para un ciclo que
incluyó una promoción, estos montos son el neto pagado después del descuento, y `basis.charged_amount`
lo muestra. Si el ciclo actual no tiene ningún pago capturado (un rechazo, un pago aún pendiente,
o un vacío), `PRORATED`, `FULL` y `CUSTOM` devuelven `400 REFUND_NOT_AVAILABLE`, excepto en una fase genuina
de `$0` (una fase de prueba o promocional sin ningún cobro) o un ciclo cubierto por completo por una
promoción, que devuelve `200` con `amount: 0.00`. No hay nada que reembolsar ahí, pero eso no es
un error.

Una suscripción `PAST_DUE` no tiene ningún pago capturado para el ciclo en curso, así que se aplica la misma regla:
`refund: NONE` (o un `refund` ausente) sigue cancelando con normalidad, pero cualquier otro modo devuelve
`400 REFUND_NOT_AVAILABLE` con `current_status: "PAST_DUE"`.

### PRORATED

Reembolsa los días no usados del ciclo actual, usando aritmética de fechas de calendario, nunca horas ni
minutos:

* `period_start`: la fecha en que se cobró el último pago capturado.
* `period_end`: la fecha en que termina naturalmente el ciclo actual, limitada a `availability.finish_at` cuando
  la suscripción lo tiene y es anterior.
* `unused_days = period_days − used_days`, donde `used_days` cuenta el día en que cancelas como un día completo
  usado: cancelar a cualquier hora del día 10 de un ciclo de 30 días cuenta igualmente 10 días usados.
* `amount = charged_amount × unused_days / period_days`, redondeado `HALF_UP` a las
  unidades menores de la moneda.

Por ejemplo, un ciclo de 30 días cobrado por `$30.00`, cancelado el día 10: 10 días usados, 20 días sin usar,
`amount = 30.00 × 20/30 = 20.00`.

```json Cancel with a prorated refund — response theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "refund": {
    "mode": "PRORATED",
    "amount": { "value": 20.00, "currency": "USD" },
    "unused_days": 20,
    "period_days": 30,
    "basis": {
      "billing_cycle": 4,
      "charged_amount": { "value": 30.00, "currency": "USD" },
      "payment_id": "<example>",
      "charged_at": "<example>"
    },
    "execution": "MERCHANT",
    "quoted_at": "<example>"
  }
}
```

Una suscripción facturada por hora o por minuto no tiene una noción significativa de "día", por lo que `PRORATED`
devuelve allí `400` `"proration is not available for sub-daily cadences"`. `FULL` y `CUSTOM` no
se ven afectados: ambos siguen funcionando en una cadencia inferior a un día.

### FULL

Reembolsa el `basis.charged_amount` completo del ciclo actual: `amount` siempre es igual a
`basis.charged_amount` exactamente, y `unused_days` es igual a `period_days` (todo el ciclo se trata
como no usado).

### CUSTOM

Un reembolso `CUSTOM` toma su monto de uno de dos lugares, en este orden:

1. `refund_amount` en la solicitud de cancelación, si envías uno.
2. De lo contrario, el `refund_rule` configurado en la suscripción.

Si no existe ninguno, la cancelación se rechaza con `400` `BAD_REQUEST`:
`"refund: CUSTOM requires refund_amount or a configured refund_rule."` `CUSTOM` nunca recurre a
un monto calculado. `refund_rule` se define en [Crear](https://docs.y.uno/es/reference/subscriptions/create-subscription.md#setting-a-refund-rule)
o [Actualizar](https://docs.y.uno/es/reference/subscriptions/update-subscription.md#setting-a-refund-rule) y se describe en
[el objeto Subscription](https://docs.y.uno/es/reference/subscriptions/the-subscription-object.md).

```json Cancel G — the request's refund_amount wins over the configured refund_rule theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "refund": "CUSTOM",
  "refund_amount": { "value": 5000, "currency": "COP" }
}
// refund.amount.value: 5000 — the configured refund_rule (a FIXED rule for 10000) is not used
```

```json Cancel H — no refund_amount sent, the configured refund_rule wins theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "refund": "CUSTOM"
}
// refund.amount.value: 10000 — the subscription's stored FIXED refund_rule
```

> [!NOTE]
>
> **Disponibilidad**
>
> Un `refund_rule` configurado está disponible para las organizaciones habilitadas; contacta a Yuno. Para una
> organización que aún no está habilitada, `CUSTOM` se comporta exactamente como hoy: `refund_amount` en
> la solicitud es obligatorio y nunca se puede configurar un `refund_rule` para esa organización
> en primer lugar.

Envía `refund_amount` junto con `"refund": "CUSTOM"` para reembolsar un monto específico en lugar de uno
calculado o basado en una regla:

```json Cancel with a custom refund amount theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "refund": "CUSTOM",
  "refund_amount": { "value": 5.00, "currency": "USD" }
}
```

`amount` en la respuesta es tu `refund_amount` devuelto exactamente igual, sin recalcular ni redondear
de nuevo. `refund_amount.value` debe ser mayor que `0` y no debe superar el monto
cobrado del ciclo actual, y `refund_amount.currency` debe coincidir con la moneda de la propia suscripción.

### Leer el objeto refund

`refund` es `null` cuando `refund` fue `NONE` o se omitió. De lo contrario:

| Field | Description |
| - | - |
| `mode` | `PRORATED`, `FULL` o `CUSTOM`, tal como se solicitó. |
| `amount` | El monto de reembolso calculado (o el devuelto tal cual en `CUSTOM`). |
| `unused_days` / `period_days` | Los datos de días a partir de los cuales se calculó el monto. En `FULL`, `unused_days` es igual a `period_days`: todo el ciclo cuenta como no usado. |
| `basis.billing_cycle` | El ciclo de facturación sobre el que se calculó el reembolso. |
| `basis.charged_amount` | El monto realmente cobrado por ese ciclo: el tope del reembolso. |
| `basis.payment_id` | El id propio del pago capturado. `null` para una cotización de fase de `$0` sin pago al que hacer referencia. |
| `basis.charged_at` | Cuándo se capturó ese pago. `null` para una cotización de fase de `$0` sin pago al que hacer referencia. |
| `execution` | Siempre `"MERCHANT"`: Yuno calcula la cotización, tú ejecutas el reembolso. |
| `quoted_at` | Cuándo se calculó esta cotización. |

### Dónde aparece `refund`

* **La respuesta `200` de cancelación** siempre incluye la clave `refund`: `null` cuando no se calculó ninguna cotización,
  el objeto en caso contrario.
* **`GET /v1/subscriptions/{id}`** y **`GET /v1/subscriptions?merchant_reference=...`** también incluyen el
  `refund` *calculado por última vez*, una vez que existe: cancelar con una cotización de reembolso lo persiste, por lo que
  sigue apareciendo en cada lectura posterior de esa suscripción a través de cualquiera de estos dos.
* **`GET /v1/subscriptions`** (la lista paginada) **no** incluye `refund` en ninguna entrada, sin importar si
  esa suscripción se canceló o no con una cotización: el elemento de la lista es una forma de resumen más pequeña que
  el objeto de suscripción completo, y `refund` no es uno de los campos que incluye.
* **El webhook `subscription.cancel`** incluye `refund` solo cuando realmente se calculó una cotización
  (`PRORATED`/`FULL`/`CUSTOM`): está ausente, no `null`, en una cancelación `NONE` o sin reembolso.

## Programar una cancelación en su lugar

> [!NOTE]
>
> **Solo organizaciones en la lista de permitidos**
>
> La cancelación programada se habilita por organización. Si tus llamadas devuelven `400` `"Scheduled
>   cancellation is not enabled for this organization."`, contacta a tu representante de Yuno para que la
> habilite.

Envía un objeto `schedule` para diferir la cancelación en lugar de aplicarla ahora. La suscripción
permanece en su estado actual, y la facturación continúa con normalidad, hasta que se ejecute la programación.

```json Schedule after 3 more billing cycles theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "schedule": {
    "after_cycles": 3
  }
}
```

```json Schedule for a specific date theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "schedule": {
    "at": "2026-11-01T00:00:00Z"
  }
}
```

`schedule` acepta exactamente uno de:

| Field | Type | Rules |
| - | - | - |
| `after_cycles` | integer | De 1 a 60, y no puede superar los ciclos de facturación restantes de la suscripción (`billing_cycles.total − billing_cycles.current`, cuando el plan tiene un total). |
| `at` | Timestamp | ISO-8601 con desfase UTC, debe estar en el futuro y debe ser anterior a `availability.finish_at` cuando la suscripción lo tiene. |

Enviar ambos o ninguno devuelve `400`.

Una suscripción `PIX_AUTOMATIC` facturada con `frequency.execution: MERCHANT` no puede programar una
cancelación: prográmala como `at` o `after_cycles` en un tipo de método de pago distinto, o cancela
de inmediato.

### Comportamiento mientras se ejecutan los reintentos

> [!NOTE]
>
> **`past_due_behavior` se devuelve en `cancel_scheduled`, pendiente de confirmación de producto**
>
> Actualmente el motor registra el `past_due_behavior` que se resolvió para la programación (el valor explícito
> o el valor predeterminado `EXHAUST_RETRIES`) en el campo `cancel_scheduled.past_due_behavior` de cada
> respuesta. Trata este valor devuelto como provisional hasta que producto lo confirme como el contrato externo
> previsto: puede cambiar.

`past_due_behavior` controla qué hace una cancelación programada si la suscripción está en `PAST_DUE`
cuando la programación se ejecutaría de otro modo:

| Value | Behavior |
| - | - |
| `EXHAUST_RETRIES` (default) | La cancelación programada espera: los reintentos siguen ejecutándose durante el ciclo en curso, y la cancelación solo se ejecuta cuando la suscripción sale de `PAST_DUE` (se recupera o se agotan los reintentos). |
| `SKIP_RETRIES` | La cancelación programada se ejecuta de inmediato, sin esperar a que terminen los reintentos pendientes. |

```json Schedule and skip retries if PAST_DUE when it fires theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "schedule": {
    "after_cycles": 1,
    "past_due_behavior": "SKIP_RETRIES"
  }
}
```

Independientemente de `past_due_behavior`, cancelar una suscripción `PAST_DUE`, ya sea de inmediato o
porque una programación venció, nunca genera un error y siempre detiene los reintentos de ese ciclo. Consulta
[Estado de la suscripción](https://docs.y.uno/es/reference/subscriptions/status-subscriptions.md) y
[Reintentos](https://docs.y.uno/es/docs/payment-features/subscriptions/retries.md).

> [!NOTE]
>
> El manejo de reembolsos solo está disponible en una cancelación **inmediata**; consulta
> [Reembolso en la cancelación inmediata](#refund-on-immediate-cancel). No se incluye con la cancelación
> programada: una solicitud con `schedule` no puede incluir también un modo `refund`.

## Deshacer una cancelación programada

Envía `"schedule": null` para borrar una programación pendiente. La suscripción no se ve afectada de otro modo: sin
cambio de estado ni cobro.

```json Undo a scheduled cancellation theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "schedule": null
}
```

Enviar `"schedule": null` cuando no hay nada programado no hace nada: `200`, `cancel_scheduled` sigue
siendo `null` y no se envía ningún webhook. Cuando se borra una programación, se envía en su lugar
`subscription.cancel_schedule_canceled`.

## Leer el resultado

La respuesta incluye la misma forma de [Subscription](https://docs.y.uno/es/reference/subscriptions/the-subscription-object.md)
que cualquier otro endpoint de suscripciones. Cuatro campos son relevantes aquí:

* `cancel_scheduled`: `null` cuando no hay ninguna cancelación pendiente; de lo contrario, el `mode` de la programación,
  `after_cycles`/`at`, `requested_at` y `past_due_behavior`.
* `retries.stopped`, `retries.attempts_made`, `retries.outcome`, `retries.next_retry_at`: se completan
  siempre que la suscripción está en `PAST_DUE` o tiene un `cancel_scheduled` pendiente; se omiten en los demás casos.
* `unpaid_cycle`: está presente cuando el ciclo de facturación actual está en `PAST_DUE` y no se ha saldado.
* `refund`: `null` (o ausente en lecturas que no son de cancelación) cuando no se calculó ninguna cotización de reembolso; de lo contrario, el
  monto cotizado y su base. Consulta [Reembolso en la cancelación inmediata](#refund-on-immediate-cancel).

> [!NOTE]
>
> **La persistencia de `retries` y `unpaid_cycle` después de la cancelación está pendiente de confirmación de producto**
>
> Ambos campos se calculan a partir del estado en vivo de la suscripción al momento de la solicitud. Si un `GET
>   /v1/subscriptions/{id}` emitido después de que la suscripción llega a `CANCELED` sigue mostrando la
> instantánea de reintentos o el ciclo impago del ciclo que estaba en curso, o los omite una vez terminal, aún no
> está confirmado como un contrato estable: verifica con una respuesta en vivo antes de depender de ello.

Consulta [el objeto Subscription](https://docs.y.uno/es/reference/subscriptions/the-subscription-object.md) para ver la referencia
completa de campos.

## Programar una cancelación en una suscripción pausada

Una suscripción pausada aún se puede programar para cancelación. `schedule.after_cycles` se rechaza
mientras la suscripción está en `PAUSED`, porque una pausa congela el reloj de facturación y no hay ningún
límite de ciclo desde el cual contar:

```json 400 — after_cycles on a paused subscription theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "code": "BAD_REQUEST",
  "messages": [
    "schedule.after_cycles cannot be resolved while the subscription is paused; use schedule.at instead."
  ]
}
```

`schedule.at` no tiene esa restricción: no necesita un reloj de ciclos, por lo que se acepta con normalidad en una
suscripción `PAUSED`. Consulta [Pausar suscripción](https://docs.y.uno/es/reference/subscriptions/pause-subscription.md).

## Webhooks

* `subscription.cancel_scheduled`: se envía cuando se programa una cancelación mediante este endpoint.
* `subscription.cancel_schedule_canceled`: se envía cuando se deshace una cancelación programada pendiente mediante
  `"schedule": null`.

Una cancelación inmediata (cuerpo vacío, o una programación que vence) sigue emitiendo `subscription.cancel`
como antes: la programación emite sus propios eventos solo para las acciones de programar y deshacer.
El payload de `subscription.cancel` también incluye `refund`, siguiendo la misma regla que la respuesta de
cancelación: está presente solo cuando realmente se calculó una cotización (`PRORATED`/`FULL`/`CUSTOM`) y ausente en una
cancelación `NONE` o sin reembolso.

## Errores

| HTTP | `code` | When |
| - | - | - |
| `400` | `BAD_REQUEST` | Una clave de nivel superior no reconocida, o una clave no reconocida dentro de `schedule`. |
| `400` | `BAD_REQUEST` | `schedule` incluye tanto `at` como `after_cycles`, o ninguno. |
| `400` | `BAD_REQUEST` | `after_cycles` no es un entero entre 1 y 60, o supera los ciclos de facturación restantes. |
| `400` | `BAD_REQUEST` | `after_cycles` se envía mientras la suscripción está en `PAUSED`: `"schedule.after_cycles cannot be resolved while the subscription is paused; use schedule.at instead."` |
| `400` | `BAD_REQUEST` | `at` no es una fecha y hora ISO-8601 con desfase UTC, no está en el futuro, o cae en o después de `availability.finish_at`. |
| `400` | `BAD_REQUEST` | `past_due_behavior` no es `EXHAUST_RETRIES` ni `SKIP_RETRIES`. |
| `400` | `BAD_REQUEST` | La cancelación programada no está habilitada para esta organización. |
| `400` | `BAD_REQUEST` | Una suscripción `PIX_AUTOMATIC` facturada con `frequency.execution: MERCHANT` no puede programar una cancelación. |
| `400` | `BAD_REQUEST` | `refund` no es uno de `NONE`, `PRORATED`, `FULL`, `CUSTOM`. |
| `400` | `BAD_REQUEST` | `refund` (cualquier modo distinto de `NONE`) se combina con `schedule`, incluido `"schedule": null`. |
| `400` | `BAD_REQUEST` | La cotización de reembolsos no está habilitada para esta organización (`refund: NONE`/ausente nunca está restringido). |
| `400` | `BAD_REQUEST` | `refund_amount` se envía sin `refund: CUSTOM`. |
| `400` | `BAD_REQUEST` | `refund: CUSTOM` se envía sin `refund_amount` ni un `refund_rule` configurado en la suscripción: `"refund: CUSTOM requires refund_amount or a configured refund_rule."` |
| `400` | `BAD_REQUEST` | `refund_amount.value` falta, no es mayor que `0` o supera el monto cobrado del ciclo actual (el tope). |
| `400` | `BAD_REQUEST` | `refund_amount.currency` falta o no coincide con la moneda de la propia suscripción. |
| `400` | `BAD_REQUEST` | `refund: PRORATED` en una cadencia inferior a un día (`HOUR`/`MINUTE`). |
| `400` | `REFUND_NOT_AVAILABLE` | `refund` no es `NONE`, y el ciclo de facturación actual no tiene ningún pago capturado contra el cual reembolsar (incluye todos los casos `PAST_DUE`). Incluye `current_status`. |
| `400` | `INVALID_STATE` | El estado de la suscripción no admite la cancelación (`COMPLETED` o ya `CANCELED`). |


## OpenAPI

````yaml openapi/es/subscriptions/cancel-subscription.json POST /subscriptions/{subscription_id}/cancel
openapi: 3.1.0
info:
  title: subscription
  version: 1.0.2
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - sec0: []
    sec1: []
paths:
  /subscriptions/{subscription_id}/cancel:
    post:
      summary: Cancelar suscripción
      operationId: cancel-subscription
      parameters:
        - name: subscription_id
          in: path
          description: Identificador único de una suscripción.
          schema:
            type: string
          required: true
      requestBody:
        required: false
        content:
          application/json:
            examples:
              IMMEDIATE (empty body):
                value: {}
              SCHEDULE AFTER 3 CYCLES:
                value:
                  schedule:
                    after_cycles: 3
              SCHEDULE AT A DATE:
                value:
                  schedule:
                    at: '2026-11-01T00:00:00Z'
              SCHEDULE AND SKIP RETRIES IF PAST_DUE:
                value:
                  schedule:
                    after_cycles: 1
                    past_due_behavior: SKIP_RETRIES
              UNDO A PENDING SCHEDULE:
                value:
                  schedule: null
              CANCEL WITH A PRORATED REFUND:
                value:
                  refund: PRORATED
              CANCEL WITH A CUSTOM REFUND AMOUNT:
                value:
                  refund: CUSTOM
                  refund_amount:
                    value: 5
                    currency: USD
              CANCEL WITH CUSTOM REFUND (RULE RESOLVES IT):
                value:
                  refund: CUSTOM
            schema:
              type: object
              properties:
                refund:
                  type: string
                  description: >-
                    NONE (predeterminado), PRORATED, FULL o CUSTOM. Calcula una
                    cotización de reembolso para el ciclo de facturación actual
                    en una cancelación inmediata. No se puede combinar con
                    schedule.
                  example: PRORATED
                refund_amount:
                  type: object
                  description: >-
                    Obligatorio, y solo se permite, cuando refund es CUSTOM. No
                    debe superar el monto cobrado del ciclo actual.
                  properties:
                    value:
                      type: number
                      example: 5
                    currency:
                      type: string
                      description: Debe coincidir con la moneda propia de la suscripción.
                      example: USD
                schedule:
                  type:
                    - object
                    - 'null'
                  properties:
                    after_cycles:
                      type: integer
                      description: >-
                        Cancela después de esta cantidad de ciclos de
                        facturación adicionales. 1-60, limitado a los ciclos
                        restantes. Se requiere exactamente uno de
                        after_cycles/at.
                      example: 3
                    at:
                      type: string
                      description: >-
                        Cancela en esta fecha y hora ISO-8601 (se requiere el
                        desfase UTC). Debe estar en el futuro y antes de
                        availability.finish_at. Se requiere exactamente uno de
                        after_cycles/at.
                      example: '2026-11-01T00:00:00Z'
                    past_due_behavior:
                      type: string
                      description: >-
                        EXHAUST_RETRIES (predeterminado) espera los reintentos
                        del ciclo en curso antes de ejecutarse; SKIP_RETRIES se
                        ejecuta de inmediato incluso si la suscripción está
                        PAST_DUE.
                      example: EXHAUST_RETRIES
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                CANCEL SUBSCRIPTION:
                  value:
                    id: 7304911d-5df9-429e-8488-ad41abea1a4c
                    name: sub_001
                    description: streaming service
                    account_id: 2404911d-5df9-429e-8488-ad41abea1a4b
                    merchant_reference: 001_marzo_23
                    status: CANCELED
                    subscription_plan_id: 1904911d-5df9-429e-8488-ad41abea1a4d
                    amount:
                      currency: USD
                      value: 12100
                    frequency:
                      type: MONTH
                      value: 1
                    billing_cycles:
                      total: 10
                      current: 2
                      next_at: '2023-02-16T20:00:00.786342Z'
                    customer_payer:
                      id: 3t04911d-5df9-429e-8488-ad41abea1a2c
                    payment_method:
                      type: CARD
                      token: 9104911d-5df9-429e-8488-ad41abea1a4b
                      vaulted_token: 6104911d-5df9-429e-8488-ad41abea1a4b
                      card:
                        verify: false
                        card_data:
                          number: '4507990000000010'
                          expiration_month: 10
                          expiration_year: 2025
                          security_code: 123
                          holder_name: JOHN DOE
                    availability:
                      start_at: '2024-01-16T00:00:00.786342Z'
                      finish_at: '2024-05-26T20:00:00.786342Z'
                    metadata:
                      - key: sub_ext_id
                        value: AA001
                    payments:
                      - 5104911d-5df9-229e-8468-bd41abea1a4s
                    created_at: '2023-12-16T20:46:54.786342Z'
                    updated_at: '2023-12-16T21:00:54.786342Z'
                    country: US
                    retries:
                      retry_on_decline: false
                      amount: 6
                      strategy: DEFAULT
                      schedule: null
                      stop_on_hard_decline: null
                      cancel_on_exhausted_retries: null
                    additional_data: null
                    trial_period:
                      billing_cycles: 1
                      amount:
                        value: 0
                        currency: USD
                    initial_payment_validation: false
                    reason: null
                    subscription_agreement_id: null
                    soft_descriptor: ACME SUBSCRIPTION
                    renewal_notification_days: null
                    cancellation_time: '2026-10-23T08:53:58.316841Z'
                    cancellation_source: MERCHANT
                    ending_time: null
                    pending_plan_change: null
                    current_period_start: '2026-10-23T00:00:00Z'
                    current_period_end: '2026-11-23T00:00:00Z'
                    refund: null
                CANCELLATION SCHEDULED:
                  value:
                    id: 7304911d-5df9-429e-8488-ad41abea1a4c
                    name: sub_001
                    description: streaming service
                    account_id: 2404911d-5df9-429e-8488-ad41abea1a4b
                    merchant_reference: 001_marzo_23
                    status: ACTIVE
                    subscription_plan_id: 1904911d-5df9-429e-8488-ad41abea1a4d
                    amount:
                      currency: USD
                      value: 12100
                    frequency:
                      type: MONTH
                      value: 1
                    billing_cycles:
                      total: 10
                      current: 2
                      next_at: '2023-02-16T20:00:00.786342Z'
                    customer_payer:
                      id: 3t04911d-5df9-429e-8488-ad41abea1a2c
                    retries:
                      retry_on_decline: true
                      amount: 4
                      strategy: SMART
                    cancel_scheduled:
                      mode: AFTER_CYCLES
                      after_cycles: 3
                      at: '2024-03-16T20:00:00.786342Z'
                      requested_at: '2023-12-16T21:00:54.786342Z'
                      past_due_behavior: EXHAUST_RETRIES
                    created_at: '2023-12-16T20:46:54.786342Z'
                    updated_at: '2023-12-16T21:00:54.786342Z'
                    country: US
                    payment_method:
                      type: CARD
                      vaulted_token: 6477c344-6c33-47d7-880c-867da866eeaf
                      card:
                        installments: 3
                        network_transaction_id: null
                        usage: USED
                    availability:
                      start_at: '2030-01-01T00:00:00Z'
                      finish_at: null
                    metadata:
                      - key: plan
                        value: gold
                    additional_data: null
                    trial_period:
                      billing_cycles: 1
                      amount:
                        value: 0
                        currency: USD
                    initial_payment_validation: false
                    reason: null
                    subscription_agreement_id: null
                    soft_descriptor: ACME SUBSCRIPTION
                    renewal_notification_days: null
                    cancellation_time: '2026-10-23T08:53:58.316841Z'
                    cancellation_source: MERCHANT
                    ending_time: null
                    pending_plan_change: null
                    current_period_start: '2026-10-23T00:00:00Z'
                    current_period_end: '2026-11-23T00:00:00Z'
                    refund: null
                CANCELED FROM PAST_DUE (RETRIES STOPPED, UNPAID CYCLE):
                  value:
                    id: 7304911d-5df9-429e-8488-ad41abea1a4c
                    name: sub_001
                    description: streaming service
                    account_id: 2404911d-5df9-429e-8488-ad41abea1a4b
                    merchant_reference: 001_marzo_23
                    status: CANCELED
                    subscription_plan_id: 1904911d-5df9-429e-8488-ad41abea1a4d
                    amount:
                      currency: USD
                      value: 12100
                    billing_cycles:
                      total: 10
                      current: 2
                      next_at: '2023-02-16T20:00:00.786342Z'
                    customer_payer:
                      id: 3t04911d-5df9-429e-8488-ad41abea1a2c
                    retries:
                      retry_on_decline: true
                      amount: 4
                      strategy: SMART
                      stopped: true
                      attempts_made: 2
                      outcome: ABANDONED
                    unpaid_cycle:
                      cycle_number: 2
                      amount:
                        currency: USD
                        value: 12100
                      attempts: 2
                      last_failure_code: DECLINED_BY_BANK
                    cancel_scheduled: null
                    created_at: '2023-12-16T20:46:54.786342Z'
                    updated_at: '2023-12-16T21:00:54.786342Z'
                    country: US
                    frequency:
                      type: MONTH
                      value: 1
                    payment_method:
                      type: CARD
                      vaulted_token: 6477c344-6c33-47d7-880c-867da866eeaf
                      card:
                        installments: 3
                        network_transaction_id: null
                        usage: USED
                    availability:
                      start_at: '2030-01-01T00:00:00Z'
                      finish_at: null
                    metadata:
                      - key: plan
                        value: gold
                    additional_data: null
                    trial_period:
                      billing_cycles: 1
                      amount:
                        value: 0
                        currency: USD
                    initial_payment_validation: false
                    reason: null
                    subscription_agreement_id: null
                    soft_descriptor: ACME SUBSCRIPTION
                    renewal_notification_days: null
                    cancellation_time: '2026-10-23T08:53:58.316841Z'
                    cancellation_source: MERCHANT
                    ending_time: null
                    pending_plan_change: null
                    current_period_start: '2026-10-23T00:00:00Z'
                    current_period_end: '2026-11-23T00:00:00Z'
                    refund: null
                CANCELED WITH A PRORATED REFUND QUOTE:
                  value:
                    id: 7304911d-5df9-429e-8488-ad41abea1a4c
                    name: sub_001
                    description: streaming service
                    account_id: 2404911d-5df9-429e-8488-ad41abea1a4b
                    merchant_reference: 001_marzo_23
                    status: CANCELED
                    subscription_plan_id: 1904911d-5df9-429e-8488-ad41abea1a4d
                    amount:
                      currency: USD
                      value: 12100
                    billing_cycles:
                      total: 10
                      current: 4
                      next_at: '2023-02-16T20:00:00.786342Z'
                    customer_payer:
                      id: 3t04911d-5df9-429e-8488-ad41abea1a2c
                    refund:
                      mode: PRORATED
                      amount:
                        value: 20
                        currency: USD
                      unused_days: 20
                      period_days: 30
                      basis:
                        billing_cycle: 4
                        charged_amount:
                          value: 30
                          currency: USD
                        payment_id: 9104911d-5df9-429e-8488-ad41abea1a5e
                        charged_at: '2023-11-16T20:00:00.786342Z'
                      execution: MERCHANT
                      quoted_at: '2023-12-16T21:00:54.786342Z'
                    created_at: '2023-12-16T20:46:54.786342Z'
                    updated_at: '2023-12-16T21:00:54.786342Z'
                    country: US
                    frequency:
                      type: MONTH
                      value: 1
                    payment_method:
                      type: CARD
                      vaulted_token: 6477c344-6c33-47d7-880c-867da866eeaf
                      card:
                        installments: 3
                        network_transaction_id: null
                        usage: USED
                    availability:
                      start_at: '2030-01-01T00:00:00Z'
                      finish_at: null
                    retries:
                      retry_on_decline: false
                      amount: 6
                      strategy: DEFAULT
                      schedule: null
                      stop_on_hard_decline: null
                      cancel_on_exhausted_retries: null
                    metadata:
                      - key: plan
                        value: gold
                    additional_data: null
                    trial_period:
                      billing_cycles: 1
                      amount:
                        value: 0
                        currency: USD
                    initial_payment_validation: false
                    reason: null
                    subscription_agreement_id: null
                    soft_descriptor: ACME SUBSCRIPTION
                    renewal_notification_days: null
                    cancellation_time: '2026-10-23T08:53:58.316841Z'
                    cancellation_source: MERCHANT
                    ending_time: null
                    pending_plan_change: null
                    current_period_start: '2026-10-23T00:00:00Z'
                    current_period_end: '2026-11-23T00:00:00Z'
                CANCELED WITH A CUSTOM REFUND - THE REQUEST AMOUNT WINS:
                  value:
                    id: 7304911d-5df9-429e-8488-ad41abea1a4c
                    name: SUB-108B merchant precedence subject G
                    account_id: 2404911d-5df9-429e-8488-ad41abea1a4b
                    country: CO
                    description: null
                    merchant_reference: pa-sub108bg-1789488892790-438550
                    status: CANCELED
                    amount:
                      currency: COP
                      value: 45000
                    frequency:
                      type: MINUTES
                      value: 1
                    billing_cycles:
                      total: null
                      current: 4
                      paid: 3
                      next_at: '2026-09-15T16:17:57.79Z'
                    customer_payer:
                      id: 3t04911d-5df9-429e-8488-ad41abea1a2c
                    payment_method:
                      type: CARD
                      vaulted_token: 6104911d-5df9-429e-8488-ad41abea1a4b
                      card:
                        installments: null
                        network_transaction_id: '615803391389209'
                        usage: USED
                    availability:
                      start_at: '2026-09-15T16:14:57.79Z'
                      finish_at: null
                    retries:
                      retry_on_decline: false
                      amount: 6
                      strategy: SMART
                      schedule: null
                      stop_on_hard_decline: null
                      cancel_on_exhausted_retries: null
                    metadata: null
                    additional_data: null
                    trial_period:
                      billing_cycles: 1
                      amount:
                        value: 0
                        currency: ''
                    initial_payment_validation: false
                    reason: null
                    subscription_agreement_id: null
                    soft_descriptor: null
                    renewal_notification_days: null
                    cancellation_time: '2026-09-15T16:17:20.597473Z'
                    cancellation_source: MERCHANT
                    ending_time: null
                    created_at: '2026-09-15T16:14:53.58767Z'
                    updated_at: '2026-09-15T16:17:20.597473Z'
                    pending_plan_change: null
                    current_period_start: '2026-09-15T16:16:57.79Z'
                    current_period_end: '2026-09-15T16:17:57.79Z'
                    refund_rule:
                      type: FIXED
                      amount:
                        currency: COP
                        value: 10000
                    refund:
                      mode: CUSTOM
                      amount:
                        currency: COP
                        value: 5000
                      unused_days: 0
                      period_days: 0
                      basis:
                        billing_cycle: 3
                        charged_amount:
                          currency: COP
                          value: 45000
                        payment_id: 857de7e6-47eb-49be-99ee-7e1239c4e154
                        charged_at: '2026-09-15T16:16:57.804759Z'
                      execution: MERCHANT
                      quoted_at: '2026-09-15T16:17:20.59332Z'
                CANCELED WITH A CUSTOM REFUND - THE CONFIGURED RULE WINS:
                  value:
                    id: 7304911d-5df9-429e-8488-ad41abea1a4c
                    name: SUB-108B merchant precedence subject H
                    account_id: 2404911d-5df9-429e-8488-ad41abea1a4b
                    country: CO
                    description: null
                    merchant_reference: pa-sub108bh-1789488893775-983485
                    status: CANCELED
                    amount:
                      currency: COP
                      value: 45000
                    frequency:
                      type: MINUTES
                      value: 1
                    billing_cycles:
                      total: null
                      current: 4
                      paid: 3
                      next_at: '2026-09-15T16:17:58.775Z'
                    customer_payer:
                      id: 3t04911d-5df9-429e-8488-ad41abea1a2c
                    payment_method:
                      type: CARD
                      vaulted_token: 6104911d-5df9-429e-8488-ad41abea1a4b
                      card:
                        installments: null
                        network_transaction_id: '615803391389209'
                        usage: USED
                    availability:
                      start_at: '2026-09-15T16:14:58.775Z'
                      finish_at: null
                    retries:
                      retry_on_decline: false
                      amount: 6
                      strategy: SMART
                      schedule: null
                      stop_on_hard_decline: null
                      cancel_on_exhausted_retries: null
                    metadata: null
                    additional_data: null
                    trial_period:
                      billing_cycles: 1
                      amount:
                        value: 0
                        currency: ''
                    initial_payment_validation: false
                    reason: null
                    subscription_agreement_id: null
                    soft_descriptor: null
                    renewal_notification_days: null
                    cancellation_time: '2026-09-15T16:17:21.838701Z'
                    cancellation_source: MERCHANT
                    ending_time: null
                    created_at: '2026-09-15T16:14:54.30455Z'
                    updated_at: '2026-09-15T16:17:21.838701Z'
                    pending_plan_change: null
                    current_period_start: '2026-09-15T16:16:58.775Z'
                    current_period_end: '2026-09-15T16:17:58.775Z'
                    refund_rule:
                      type: FIXED
                      amount:
                        currency: COP
                        value: 10000
                    refund:
                      mode: CUSTOM
                      amount:
                        currency: COP
                        value: 10000
                      unused_days: 0
                      period_days: 0
                      basis:
                        billing_cycle: 3
                        charged_amount:
                          currency: COP
                          value: 45000
                        payment_id: a35cb164-e68f-45f0-954e-1fe34e4203eb
                        charged_at: '2026-09-15T16:16:58.790108Z'
                      execution: MERCHANT
                      quoted_at: '2026-09-15T16:17:21.837768Z'
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 7304911d-5df9-429e-8488-ad41abea1a4c
                  name:
                    type: string
                    example: sub_001
                  description:
                    type: string
                    example: streaming service
                    nullable: true
                  account_id:
                    type: string
                    example: 2404911d-5df9-429e-8488-ad41abea1a4b
                  merchant_reference:
                    type: string
                    example: 001_marzo_23
                  status:
                    type: string
                    example: CANCELED
                  subscription_plan_id:
                    type: string
                    example: 1904911d-5df9-429e-8488-ad41abea1a4d
                  amount:
                    type: object
                    properties:
                      currency:
                        type: string
                        example: USD
                      value:
                        type: number
                        example: 12100
                        default: 0
                  frequency:
                    type: object
                    properties:
                      type:
                        type: string
                        example: MONTH
                      value:
                        type: integer
                        example: 1
                        default: 0
                      monthly_billing_day:
                        type: integer
                        nullable: true
                        description: >-
                          Día del mes al que se ancla la facturación en una
                          suscripción de frecuencia MONTH. Se establece con
                          RESTART (en Update, un cambio de plan, reanudar o
                          reactivar) o enviando el propio
                          frequency.monthly_billing_day de Update Subscription.
                          Solo está presente una vez establecido; está ausente,
                          no es null, antes de eso y en cualquier otro tipo de
                          frecuencia.
                        example: 15
                  billing_cycles:
                    type: object
                    properties:
                      total:
                        type: integer
                        example: 10
                        default: 0
                        nullable: true
                      current:
                        type: integer
                        example: 2
                        default: 0
                      next_at:
                        type: string
                        example: '2023-02-16T20:00:00.786342Z'
                      scheduling_date:
                        type: string
                        description: >-
                          Momento en que la instrucción de débito se entrega al
                          riel de Pix: `next_at` menos cuatro días. Solo está
                          presente en las suscripciones `PIX_AUTOMATIC` que Yuno
                          ejecuta, y solo cuando el margen de programación de
                          cuatro días está habilitado para la organización; en
                          cualquier otro caso está ausente, no es `null`. Solo
                          lectura. Consulta [Pix
                          Automático](/es/docs/payment-features/subscriptions/pix-automatico#the-scheduling-date).
                        example: '2026-11-27T00:00:00Z'
                      paid:
                        type: integer
                        description: >-
                          Cuántos ciclos se han pagado hasta ahora. Distinto de
                          `current`, que es el ciclo que se está facturando.
                  customer_payer:
                    type: object
                    properties:
                      id:
                        type: string
                        example: 3t04911d-5df9-429e-8488-ad41abea1a2c
                  payment_method:
                    type: object
                    properties:
                      type:
                        type: string
                        example: CARD
                      token:
                        type: string
                        example: 9104911d-5df9-429e-8488-ad41abea1a4b
                      vaulted_token:
                        type: string
                        example: 6104911d-5df9-429e-8488-ad41abea1a4b
                      card:
                        type: object
                        properties:
                          verify:
                            type: boolean
                            example: false
                            default: true
                          card_data:
                            type: object
                            properties:
                              number:
                                type: string
                                example: '4507990000000010'
                              expiration_month:
                                type: integer
                                example: 10
                                default: 0
                              expiration_year:
                                type: integer
                                example: 2025
                                default: 0
                              security_code:
                                type: integer
                                example: 123
                                default: 0
                              holder_name:
                                type: string
                                example: JOHN DOE
                          installments:
                            type: integer
                            nullable: true
                          network_transaction_id:
                            type: string
                            nullable: true
                          usage:
                            type: string
                            example: FIRST
                        nullable: true
                    description: >-
                      Método de pago que cobra la suscripción. Un único objeto,
                      no una lista.
                  availability:
                    type: object
                    properties:
                      start_at:
                        type: string
                        example: '2024-01-16T00:00:00.786342Z'
                      finish_at:
                        type: string
                        example: '2024-05-26T20:00:00.786342Z'
                        nullable: true
                  metadata:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          example: sub_ext_id
                        value:
                          type: string
                          example: AA001
                    nullable: true
                  payments:
                    type: array
                    items:
                      type: string
                      example: 5104911d-5df9-229e-8468-bd41abea1a4s
                    description: >-
                      Lista de IDs de pago creados por la suscripción. Se omite
                      de la respuesta cuando la suscripción no tiene pagos.
                  retries:
                    type: object
                    properties:
                      retry_on_decline:
                        type: boolean
                      amount:
                        type: integer
                      strategy:
                        type: string
                      stopped:
                        type: boolean
                        description: >-
                          Solo está presente cuando la suscripción está en
                          PAST_DUE o tiene cancel_scheduled pendiente.
                      attempts_made:
                        type: integer
                        description: >-
                          Solo está presente cuando la suscripción está en
                          PAST_DUE o tiene cancel_scheduled pendiente.
                      outcome:
                        type: string
                        description: >-
                          RECOVERED, EXHAUSTED o ABANDONED. Solo está presente
                          cuando la suscripción está en PAST_DUE o tiene
                          cancel_scheduled pendiente.
                      next_retry_at:
                        type: string
                        description: >-
                          Solo está presente cuando la suscripción está en
                          PAST_DUE o tiene cancel_scheduled pendiente.
                      schedule:
                        type: array
                        nullable: true
                        description: >-
                          El calendario por intento, que solo se define cuando
                          `strategy` es `CUSTOM_SCHEDULE`; en caso contrario es
                          `null`.
                        items:
                          type: object
                      stop_on_hard_decline:
                        type: boolean
                        nullable: true
                        description: >-
                          Cuando es true, un rechazo definitivo detiene los
                          reintentos del ciclo de facturación actual.
                      cancel_on_exhausted_retries:
                        type: boolean
                        nullable: true
                        description: >-
                          Cuando es true, la suscripción se cancela cuando
                          terminan los reintentos de un ciclo sin un pago
                          exitoso, con `cancellation_source` definido como
                          `RETRIES_EXHAUSTED`.
                      profile:
                        type: string
                        description: >-
                          La escalera de reintentos fija que sigue la
                          suscripción en lugar del calendario configurable.
                          Siempre es `PIX_AUTOMATIC`. Este campo y los tres
                          siguientes solo están presentes en las suscripciones
                          `PIX_AUTOMATIC` que ejecuta Yuno; están ausentes, no
                          son `null`, en cualquier otro método de pago. Consulta
                          [Pix
                          Automático](/es/docs/payment-features/subscriptions/pix-automatico#the-retry-ladder).
                        example: PIX_AUTOMATIC
                      max_attempts:
                        type: integer
                        description: >-
                          Cuántos reintentos ejecuta la escalera de Pix. Siempre
                          es 3, igual que el `amount` informado para estas
                          suscripciones.
                        example: 3
                      min_gap_hours:
                        type: integer
                        description: >-
                          Siempre 24: el intervalo entre las fechas de débito de
                          la escalera (`D`, `D+1`, `D+2`, `D+3`), no entre los
                          intentos de envío.
                        example: 24
                      until:
                        type: string
                        description: >-
                          Cuándo se detiene la escalera:
                          `billing_cycles.next_at` más 7 días. Se mueve con
                          `next_at` en cada renovación.
                  unpaid_cycle:
                    type: object
                    description: >-
                      Solo está presente cuando el ciclo de facturación actual
                      está en PAST_DUE y no se ha liquidado.
                    properties:
                      cycle_number:
                        type: integer
                      amount:
                        type: object
                        properties:
                          currency:
                            type: string
                          value:
                            type: number
                      attempts:
                        type: integer
                      last_failure_code:
                        type: string
                  cancel_scheduled:
                    type:
                      - object
                      - 'null'
                    description: null cuando no hay ninguna cancelación pendiente.
                    properties:
                      mode:
                        type: string
                        example: AFTER_CYCLES
                      after_cycles:
                        type: integer
                        example: 3
                      at:
                        type: string
                      requested_at:
                        type: string
                      past_due_behavior:
                        type: string
                        example: EXHAUST_RETRIES
                  refund:
                    type:
                      - object
                      - 'null'
                    description: >-
                      null cuando refund fue NONE o se omitió. Está presente en
                      la respuesta de cancelación y en cada lectura posterior
                      una vez calculado.
                    properties:
                      mode:
                        type: string
                        example: PRORATED
                      amount:
                        type: object
                        properties:
                          currency:
                            type: string
                            example: USD
                          value:
                            type: number
                            example: 20
                      unused_days:
                        type: integer
                        example: 20
                      period_days:
                        type: integer
                        example: 30
                      basis:
                        type: object
                        properties:
                          billing_cycle:
                            type: integer
                            example: 4
                          charged_amount:
                            type: object
                            properties:
                              currency:
                                type: string
                                example: USD
                              value:
                                type: number
                                example: 30
                          payment_id:
                            type: string
                            description: >-
                              null para una cotización de fase de $0 sin un pago
                              capturado.
                          charged_at:
                            type: string
                            description: >-
                              null para una cotización de fase de $0 sin un pago
                              capturado.
                      execution:
                        type: string
                        example: MERCHANT
                      quoted_at:
                        type: string
                  created_at:
                    type: string
                    example: '2023-12-16T20:46:54.786342Z'
                  updated_at:
                    type: string
                    example: '2023-12-16T21:00:54.786342Z'
                  country:
                    type: string
                    description: El país de la suscripción (ISO 3166-1 alpha-2).
                    example: US
                  soft_descriptor:
                    type: string
                    description: Descriptor suave.
                    example: ACME SUBSCRIPTION
                    nullable: true
                  current_period_start:
                    type: string
                    nullable: true
                    description: >-
                      Inicio del período de facturación en el que está la
                      suscripción actualmente, una cadencia antes de
                      `current_period_end`. Dentro de una prueba o de cualquier
                      otra fase del plan, sigue la cadencia de esa fase. Una
                      suscripción terminal (`CANCELED` o `COMPLETED`) conserva
                      su ventana final en lugar de pasar a null. Es null solo
                      para una suscripción sin cadencia recurrente. Siempre se
                      devuelve junto con current_period_end.
                    example: '2023-01-16T20:00:00.912480Z'
                  current_period_end:
                    type: string
                    nullable: true
                    description: >-
                      Fin del período de facturación en el que está la
                      suscripción actualmente. Es igual a
                      billing_cycles.next_at. Siempre se devuelve junto con
                      current_period_start.
                    example: '2023-02-16T20:00:00.786342Z'
                  billing_date:
                    type: object
                    nullable: true
                    description: >-
                      Solo está presente en suscripciones facturadas en una
                      fecha fija en lugar de una frecuencia; es mutuamente
                      excluyente con `frequency`.
                    properties:
                      type:
                        type: string
                        example: DAY
                      day:
                        type: integer
                        example: 2
                  trial_period:
                    type: object
                    description: Período de prueba.
                    properties:
                      billing_cycles:
                        type: integer
                        example: 1
                        default: 0
                      amount:
                        type: object
                        properties:
                          value:
                            type: number
                            example: 0
                            default: 0
                          currency:
                            type: string
                            example: USD
                  additional_data:
                    type: object
                    nullable: true
                    description: >-
                      El enriquecimiento opcional de la orden enviada en la
                      creación, devuelto tal cual. Consulta [El objeto
                      Suscripción](/es/reference/subscriptions/the-subscription-object)
                      para ver su estructura completa.
                  initial_payment_validation:
                    type: boolean
                    description: >-
                      Indica si la suscripción esperó a que su primer pago fuera
                      exitoso antes de activarse. Es `false` por defecto.
                    example: false
                  reason:
                    type: string
                    nullable: true
                    description: >-
                      Motivo libre del estado actual de la suscripción, cuando
                      se registró uno; `null` en caso contrario.
                    example: merchant request
                  renewal_notification_days:
                    type: integer
                    nullable: true
                    description: >-
                      Cuántos días antes de la próxima fecha de facturación se
                      envía el webhook `subscription.close_to_renewal`. `null`
                      significa que no se envía ninguna notificación de
                      renovación.
                    example: 3
                  subscription_agreement_id:
                    type: string
                    description: ID del acuerdo de suscripción.
                    example: sa_6af2dfcd-44c0-4f16-a331-8bed3ed9c9fa
                    nullable: true
                  cancellation_time:
                    type: string
                    nullable: true
                    description: >-
                      Cuándo se canceló la suscripción. Solo se define una vez
                      que llega a `CANCELED`; `null` en caso contrario.
                    example: '2023-12-16T20:46:54.786342Z'
                  cancellation_source:
                    type: string
                    nullable: true
                    description: >-
                      Qué desencadenó la cancelación: `MERCHANT`, `SYSTEM`,
                      `PLAN_CHANGE` o `RETRIES_EXHAUSTED`. Solo se define una
                      vez que la suscripción llega a `CANCELED`; `null` en caso
                      contrario. Trátalo como un valor abierto: maneja los
                      valores no reconocidos de forma adecuada.
                    example: MERCHANT
                  ending_time:
                    type: string
                    nullable: true
                    description: >-
                      Cuándo se completó o expiró la suscripción. Solo se define
                      una vez que llega a `COMPLETED`; `null` en caso contrario.
                    example: '2024-12-16T20:46:54.786342Z'
                  plan_id:
                    type: string
                    description: >-
                      Solo está presente cuando la suscripción está vinculada a
                      un plan.
                    example: 00000000-0000-4000-8000-000000000001
                  plan_assigned_at:
                    type: string
                    description: >-
                      Solo está presente en suscripciones vinculadas a un plan.
                      El momento en que se asoció el plan: en la creación a
                      partir de un plan, en la migración a un plan o en un
                      cambio de plan.
                    example: '2023-12-16T20:46:54.786342Z'
                  previous_subscription_id:
                    type: string
                    description: >-
                      Solo está presente cuando esta suscripción se creó por un
                      cambio de plan (cambiar una suscripción existente a un
                      plan diferente).
                    nullable: true
                  phases:
                    type: array
                    description: >-
                      Las definiciones de fases del plan vinculado, tal como las
                      declara el plan, incluida la fase terminal `REGULAR`. Solo
                      está presente en suscripciones vinculadas a un plan que
                      tiene fases. Esta es la escalera propia del plan, no la
                      instantánea de este suscriptor: para lo que se fijó para
                      esta suscripción en la creación, usa `billing_phases`.
                    items:
                      type: object
                      properties:
                        order:
                          type: integer
                        name:
                          type: string
                        type:
                          type: string
                          description: '`TRIAL` o `REGULAR`.'
                        duration:
                          type: object
                          nullable: true
                          description: >-
                            Cuánto dura la fase. `null` en la fase terminal
                            `REGULAR`, que se ejecuta hasta que termina la
                            suscripción.
                          properties:
                            type:
                              type: string
                            value:
                              type: integer
                        frequency:
                          type: object
                          nullable: true
                          description: >-
                            Con qué frecuencia factura la fase. `null` en la
                            fase terminal `REGULAR`, que factura con la
                            frecuencia propia del plan.
                          properties:
                            type:
                              type: string
                            value:
                              type: integer
                        amount:
                          type: object
                          nullable: true
                          description: >-
                            El precio de la fase. `null` en la fase terminal
                            `REGULAR`, cuyo precio se resuelve a partir del plan
                            en cada facturación.
                          properties:
                            currency:
                              type: string
                            value:
                              type: number
                        total_payments:
                          type: integer
                          nullable: true
                        country_prices:
                          type: array
                          description: >-
                            Reemplazos del precio de la fase por país, vacío
                            cuando la fase no tiene ninguno.
                          items:
                            type: object
                            properties:
                              country:
                                type: string
                              amount:
                                type: object
                                properties:
                                  currency:
                                    type: string
                                  value:
                                    type: number
                  current_phase:
                    type: string
                    description: Solo está presente en suscripciones vinculadas a un plan.
                    example: REGULAR
                  current_phase_end:
                    type: string
                    nullable: true
                    description: >-
                      Cuándo la fase indicada por `current_phase` pasa a la
                      siguiente: para una suscripción en su prueba, cuándo
                      cambia al precio regular. Es el fin del último período de
                      facturación que cubre la fase, así que en el último
                      período de una prueba es igual a `current_period_end`. Es
                      null para una suscripción sin plan y para una que ya salió
                      de la escalera de fases.
                    example: '2023-03-16T20:00:00.786342Z'
                  billing_phases:
                    type: array
                    description: >-
                      Solo está presente en suscripciones vinculadas a un plan
                      cuyo plan tiene fases. Contiene únicamente las fases TRIAL
                      iniciales, capturadas en la creación; la fase terminal
                      REGULAR nunca se incluye, ya que su precio no se fija y se
                      resuelve a partir del plan en cada facturación.
                      `current_phase: "REGULAR"` es la señal de que la escalera
                      se agotó.
                    items:
                      type: object
                      properties:
                        order:
                          type: integer
                        type:
                          type: string
                          description: >-
                            Siempre TRIAL: la fase terminal REGULAR nunca está
                            en este arreglo.
                        name:
                          type: string
                        amount:
                          type: object
                          properties:
                            currency:
                              type: string
                            value:
                              type: number
                        frequency:
                          type: object
                          properties:
                            type:
                              type: string
                            value:
                              type: integer
                        start_cycle:
                          type: integer
                        end_cycle:
                          type: integer
                  pending_plan_change:
                    type: object
                    nullable: true
                    description: >-
                      El cambio de plan programado para el próximo ciclo de
                      facturación, o null cuando no hay ninguno pendiente.
                      Programa uno con el bloque `plan_change` en Update
                      Subscription.
                    properties:
                      plan_id:
                        type: string
                        description: El identificador del plan de destino.
                        example: 1904911d-5df9-429e-8488-ad41abea1a4d
                      plan_name:
                        type: string
                        description: El nombre del plan de destino.
                        example: Pro
                      direction:
                        type: string
                        enum:
                          - UPGRADE
                          - DOWNGRADE
                        description: >-
                          Indica si el plan de destino es una mejora o una
                          reducción de plan. Solo informativo.
                        example: UPGRADE
                      effective:
                        type: string
                        enum:
                          - NEXT_BILLING_CYCLE
                        description: Cuándo se aplica el cambio.
                        example: NEXT_BILLING_CYCLE
                      phases_behavior:
                        type: string
                        enum:
                          - START_FROM_REGULAR
                          - HONOR_PHASES
                        description: Qué ocurre cuando el plan de destino tiene fases.
                        example: START_FROM_REGULAR
                      applies_at:
                        type: string
                        description: >-
                          El evento de facturación en el que el cambio entrará
                          en vigor: la próxima fecha de facturación de la
                          suscripción.
                        example: '2023-02-16T20:00:00.786342Z'
                      requested_at:
                        type: string
                        description: Cuándo se programó el cambio.
                        example: '2023-01-20T10:12:31.786342Z'
                  refund_rule:
                    type: object
                    description: >-
                      La regla de reembolso almacenada que se usa para resolver
                      un reembolso de cancelación CUSTOM cuando la solicitud de
                      cancelación no envía su propio refund_amount. Solo está
                      presente cuando hay una configurada; se omite, no es null,
                      en caso contrario. Disponible para las organizaciones
                      habilitadas; contacta a Yuno.
                    properties:
                      type:
                        type: string
                        enum:
                          - PERCENT
                          - FIXED
                        description: >-
                          PERCENT resuelve el reembolso como un porcentaje del
                          monto cobrado; FIXED lo resuelve como un monto fijo.
                        example: FIXED
                      percent:
                        type: number
                        description: >-
                          Obligatorio, y solo se permite, cuando type es PERCENT
                          (0-100).
                        example: 50
                      amount:
                        type: object
                        description: Obligatorio, y solo se permite, cuando type es FIXED.
                        properties:
                          value:
                            type: number
                            example: 10000
                          currency:
                            type: string
                            description: >-
                              Debe coincidir con la moneda propia de la
                              suscripción.
                            example: COP
                  pause_until:
                    type: string
                    description: >-
                      Cuándo está programado que la suscripción se reanude
                      automáticamente. Solo está presente en una suscripción
                      actualmente pausada con una duración (pause_cycles o
                      pause_until enviados al pausar); está ausente, no es null,
                      en cualquier otra lectura.
                    example: '2026-10-15T15:54:22.780166Z'
        '400':
          description: '400'
          content:
            application/json:
              examples:
                INVALID_STATE:
                  value:
                    code: INVALID_STATE
                    messages:
                      - >-
                        The subscription state does not support the action
                        requested.
                UNKNOWN KEY:
                  value:
                    code: BAD_REQUEST
                    messages:
                      - 'unknown field: reason'
                SCHEDULE MUST CARRY EXACTLY ONE OF at OR after_cycles:
                  value:
                    code: BAD_REQUEST
                    messages:
                      - schedule must carry exactly one of at or after_cycles
                at NOT IN THE FUTURE:
                  value:
                    code: BAD_REQUEST
                    messages:
                      - schedule.at must be in the future
                ORGANIZATION NOT ENABLED:
                  value:
                    code: BAD_REQUEST
                    messages:
                      - >-
                        Scheduled cancellation is not enabled for this
                        organization.
                REFUND NOT COMBINABLE WITH SCHEDULE:
                  value:
                    code: BAD_REQUEST
                    messages:
                      - refund cannot be combined with schedule (v1)
                REFUND QUOTING NOT ENABLED FOR THIS ORGANIZATION:
                  value:
                    code: BAD_REQUEST
                    messages:
                      - Refund quote is not enabled for this organization.
                REFUND_AMOUNT EXCEEDS THE CHARGED AMOUNT:
                  value:
                    code: BAD_REQUEST
                    messages:
                      - refund_amount must not exceed the charged amount
                REFUND_AMOUNT CURRENCY MISMATCH:
                  value:
                    code: BAD_REQUEST
                    messages:
                      - >-
                        refund_amount.currency must match the subscription's
                        currency (USD)
                PRORATED NOT AVAILABLE ON A SUB-DAILY CADENCE:
                  value:
                    code: BAD_REQUEST
                    messages:
                      - proration is not available for sub-daily cadences
                REFUND NOT AVAILABLE:
                  value:
                    code: REFUND_NOT_AVAILABLE
                    messages:
                      - >-
                        No charged payment exists for the current cycle
                        (subscription is PAST_DUE). Only refund: NONE is valid.
                    current_status: PAST_DUE
                SUBSCRIPTION NOT FOUND:
                  value:
                    code: SUBSCRIPTION_NOT_FOUND
                    messages:
                      - Subscription not found.
                  summary: >-
                    No subscription resolves for the subscription_id on this
                    account. Returned as 400, not 404.
                REFUND CUSTOM REQUIRES A SOURCE:
                  value:
                    code: BAD_REQUEST
                    messages:
                      - >-
                        refund: CUSTOM requires refund_amount or a configured
                        refund_rule.
                  summary: >-
                    Neither refund_amount on the request nor a stored
                    refund_rule resolves the CUSTOM refund.
      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.