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

# Cambiar el plan de una suscripción

> Mueve una suscripción a un plan, con efecto en su próxima renovación.

> [!NOTE]
>
> **El cambio entra en vigor en la próxima renovación**
>
> No se realiza ningún cobro cuando llamas a este endpoint, y no se prorratea ni se reembolsa nada. La
> suscripción sigue facturando según su calendario actual; el precio del nuevo plan se aplica a partir
> de la fecha de la próxima renovación.

## Dos comportamientos, un endpoint

El comportamiento que obtienes depende de si la suscripción ya está en un plan.

| Suscripción | Qué sucede | `id` en la respuesta |
| - | - | - |
| Sin plan | Se asocia al plan en el mismo registro | Sin cambios |
| Ya está en un plan | Se cancela y se reemplaza por una nueva suscripción en el plan de destino | **Nuevo**: el `id` anterior está en `previous_subscription_id` |

En el caso de reemplazo, la suscripción original queda `CANCELED` con un
`cancellation_source` de `PLAN_CHANGE`, y la suscripción de reemplazo hereda los ciclos de facturación
restantes de la original y su fecha de próxima renovación: `availability.start_at` y
`billing_cycles.next_at` en la de reemplazo son iguales al `next_at` de la original, y su
`billing_cycles.current` se reinicia en `1`. Si esa fecha de renovación ya pasó (por
ejemplo, en una suscripción pausada durante mucho tiempo), la de reemplazo comienza en
aproximadamente un minuto y factura de inmediato.

> [!NOTE]
>
> **Promociones cuando cambia el plan**
>
> Para una suscripción que ya está en un plan, la promoción original termina con `end_reason` `CANCELED` y no se traslada al reemplazo. El reemplazo recibe la promoción `AUTOMATIC` del nuevo plan, si el plan tiene una. Una suscripción que no está en un plan se asocia en el lugar, como en la tabla anterior: no se reemplaza ni se cancela nada, y no se agrega ninguna promoción automática. Para conservar la promoción actual de una suscripción que ya está en un plan, usa en su lugar un cambio de plan con `promotion_behavior` establecido en `KEEP`. Consulta [Update Subscription](https://docs.y.uno/es/reference/subscriptions/update-subscription.md) y [Promociones en planes de suscripción](https://docs.y.uno/es/docs/payment-features/subscriptions/promotions.md#plan-changes).

> [!WARNING]
>
> **Guarda el `id` devuelto después de un cambio de plan a plan**
>
> La suscripción de reemplazo es una suscripción distinta. Si conservas el `id` anterior, las llamadas posteriores
> actuarán sobre una suscripción cancelada.

## Webhooks

Un cambio de plan a plan emite tres eventos:

* `subscription.create` para la suscripción de reemplazo.
* `subscription.cancel` para la original, con `cancellation_source: PLAN_CHANGE`. No
  lo cuentes como cancelación de clientes (churn).
* `subscription.plan_changed` para la suscripción de reemplazo, con `previous_subscription_id` definido.

El caso de asociación no emite ninguno de ellos. Su único webhook es un cambio de estado, y solo cuando
la secuencia de fases del plan promueve la suscripción a `TRIALING` en esta llamada.

## Omitir el periodo de prueba del plan de destino

Si el plan de destino define fases de prueba o de introducción, la suscripción adopta toda esa secuencia por
defecto, lo que significa que un suscriptor puede cambiar de plan durante una prueba y recibir una prueba nueva.

Establece `skip_trial` en `true` para evitarlo. La suscripción de reemplazo factura el precio regular del plan de destino
desde su primer cobro y su estado se mantiene `ACTIVE` en lugar de pasar a `TRIALING`.

```json Change plan without granting a new trial theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "plan_id": "1904911d-5df9-429e-8488-ad41abea1a4d",
  "skip_trial": true
}
```

`skip_trial` tiene como valor predeterminado `false` y se aplica solo a los cambios de plan a plan. Enviar
`skip_trial: true` en una suscripción que no está en un plan devuelve `400`; `false` y una
omisión del indicador son equivalentes y se aceptan en todos los casos. En un plan sin fases no
hace ninguna diferencia.

> [!NOTE]
>
> **`phases` sigue describiendo el plan**
>
> Con `skip_trial: true`, la respuesta sigue listando las `phases` del plan de destino: ese arreglo
> describe el *plan*, no lo que se facturará a esta suscripción. Las señales a nivel de suscripción
> son `status`, que se mantiene `ACTIVE` en lugar de pasar a `TRIALING`, y la **ausencia**
> de `current_phase` y `billing_phases`: ambas claves se omiten de la respuesta en lugar de
> devolverse como `null`, así que verifica la ausencia, no `null`. Un cambio predeterminado devuelve ambas
> con valores.

## Conservar el mismo `id`

El objeto `plan_change` de [Actualizar suscripción](https://docs.y.uno/es/reference/subscriptions/update-subscription.md)
cambia el plan de una suscripción **en el mismo registro**: el `id` nunca cambia, no se cancela nada
y no se dispara el webhook `subscription.cancel`. Ninguno de los dos mecanismos cobra en el momento, y tampoco
se prorratea ni se reembolsa nada en ningún caso. Se diferencian en lo que ocurre con el registro de la suscripción:

| | Registro | Próximo cobro |
| - | - | - |
| Este endpoint, de plan a plan | Nuevo `id`; la original queda `CANCELED` | La próxima renovación de la original, al precio del nuevo plan |
| `plan_change` con `effective: NEXT_BILLING_CYCLE` | Sin cambios hasta la renovación, mismo `id` | La próxima renovación, al precio del nuevo plan |
| `plan_change` con `effective: IMMEDIATE` | Movido al nuevo plan en esta llamada, mismo `id` | `billing_cycle_behavior: KEEP` (predeterminado) mantiene la fecha del próximo cobro; `RESTART` la vuelve a anclar a ahora más la frecuencia del nuevo plan |

Si cambias de plan en suscripciones que ya están en un plan y quieres conservar su `id`,
usa `plan_change` con `effective: IMMEDIATE` en lugar de este endpoint.

`plan_change` no es un sustituto general: requiere una suscripción que ya esté en un
plan y que esté `ACTIVE` o `TRIALING`. Asociar un plan a una suscripción que no tiene ninguno, o
cambiar de plan desde `CREATED` o `PAUSED`, solo es posible mediante este endpoint.

Los dos se diferencian en su comportamiento predeterminado respecto a la prueba, por motivos de retrocompatibilidad:

| | Valor predeterminado |
| - | - |
| Este endpoint | Adopta las fases del plan de destino (`skip_trial: false`) |
| `plan_change` en Actualizar suscripción | Las omite (`phases_behavior: "START_FROM_REGULAR"`) |

Establece `skip_trial` o `phases_behavior` de forma explícita siempre que el comportamiento de la prueba sea importante para ti.

## Llamadas repetidas

Mientras la suscripción esté en un estado aceptado, volver a enviar su plan **actual** es una operación
idempotente sin efecto que devuelve `200` con la suscripción sin cambios, incluso si
solo cambias `skip_trial`, e incluso si ese plan se canceló después.

Un cambio de plan a plan no se puede repetir sobre el mismo `subscription_id`. Una vez que tiene éxito, la
original queda `CANCELED`, por lo que volver a enviar a ese `id` devuelve `400` `INVALID_STATE`
(`The subscription status CANCELED does not support plan changes.`) en lugar de repetir el
primer resultado. Trata ese error como confirmación de que el cambio ya se realizó, y dirige cualquier
llamada posterior al `id` de la suscripción de reemplazo.

Si una llamada excede el tiempo de espera, concilia con `GET /v1/subscriptions/{subscription_id}` en lugar de
reintentar a ciegas: la original lleva `cancellation_source: PLAN_CHANGE` una vez que el cambio
se realizó, y la de reemplazo es la suscripción cuyo `previous_subscription_id` es ese
`id`. Un reintento en curso enviado mientras la original aún se puede cambiar es seguro: se
deduplica siempre que `skip_trial` no cambie. Un valor distinto de `skip_trial` es una
operación distinta.

## Requisitos

La suscripción no debe estar `CANCELED` ni `COMPLETED`: esas devuelven `400` `INVALID_STATE`
(`The subscription status <STATUS> does not support plan changes.`). Este endpoint acepta
suscripciones `CREATED` y `PAUSED`, que el objeto `plan_change` de Actualizar suscripción
no acepta.

En ambos casos se requiere que el plan esté `ACTIVE` y pertenezca a la cuenta de la suscripción, y
ninguno está disponible para suscripciones facturadas con `frequency.execution: MERCHANT`.

**Asociar una suscripción que no tiene plan** requiere además que la cadencia del plan
coincida con la de la suscripción y que el precio resuelto esté en la moneda de la suscripción. La
suscripción no debe estar en un periodo de prueba, no debe tener ya fases de facturación, no debe usar
un `billing_date` y no debe tener un monto `VARIABLE`.

La suscripción adopta la secuencia de fases del plan de destino desde su próximo ciclo sin facturar, y esa
secuencia debe caber dentro de los ciclos de facturación restantes de la suscripción. Si la secuencia comienza con una
fase `TRIAL` que cubre el ciclo en curso, una suscripción `ACTIVE` pasa a `TRIALING` en esta
misma llamada; las suscripciones `CREATED` y `PAUSED` no se promueven de esta forma. `skip_trial` no puede
evitarlo: es un indicador exclusivo de cambios de plan a plan.

**Cambiar de un plan a otro** requiere además que la suscripción tenga al menos
un ciclo de facturación restante y que su ventana de disponibilidad no termine antes de la próxima renovación.
El plan de destino debe aceptar el tipo de método de pago de la suscripción, si restringe
`allowed_payment_methods`, y la suscripción debe tener un método de pago almacenado en el vault. La
cadencia y el precio del plan de destino se aplican tal como están definidos en ese plan.

Si la suscripción tenía un cambio programado pendiente, esta llamada lo descarta sin
un webhook `subscription.plan_change_canceled`; la suscripción de reemplazo comienza con
`pending_plan_change: null`.

## Errores

| HTTP | `code` | Cuándo |
| - | - | - |
| `404` | `PLAN_NOT_FOUND` | El plan de destino no existe o no está vinculado a esta cuenta. |
| `400` | `INVALID_STATE` | El estado de la suscripción no admite cambios de plan; el plan de destino no está activo; o la ventana de disponibilidad termina antes de la próxima renovación. |
| `400` | `BAD_REQUEST` | `skip_trial: true` en una suscripción que no está en un plan; no hay ciclos de facturación restantes; la suscripción se factura con `frequency.execution: MERCHANT`. |
| `400` | `INCORRECT_PAYMENT_METHOD_TYPE` | El plan de destino restringe `allowed_payment_methods` y el tipo de método de pago de la suscripción no está en la lista. |
| `400` | `PAYMENT_METHOD_NOT_FOUND` | La suscripción no tiene un método de pago almacenado en el vault. |

Volver a enviar el plan actual de la suscripción aquí es una operación `200` sin efecto. La misma intención expresada
mediante el objeto `plan_change` de [Actualizar suscripción](https://docs.y.uno/es/reference/subscriptions/update-subscription.md)
se rechaza con `422` `SAME_PLAN`.


## OpenAPI

````yaml openapi/es/subscriptions/change-subscription-plan.json POST /subscriptions/{subscription_id}/plan
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}/plan:
    post:
      summary: Change Subscription Plan
      description: >-
        Mueve una suscripción a un plan de suscripción.


        Si la suscripción aún no está en un plan, se asocia en el mismo lugar y
        conserva su `id`. Si ya está en un plan, se cancela y se reemplaza por
        una suscripción **nueva** en el plan de destino; la respuesta es el
        reemplazo, y su `previous_subscription_id` apunta a la suscripción que
        reemplazó.


        En ambos casos el cambio entra en vigor en la **próxima renovación** de
        la suscripción: no se hace ningún cargo ahora y nada se prorratea ni se
        reembolsa.
      operationId: change-subscription-plan
      parameters:
        - name: subscription_id
          in: path
          description: Identificador único de una suscripción.
          schema:
            type: string
            format: uuid
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - plan_id
              properties:
                plan_id:
                  type: string
                  format: uuid
                  description: >-
                    El identificador único del plan al que se moverá la
                    suscripción.
                  examples:
                    - 1904911d-5df9-429e-8488-ad41abea1a4d
                skip_trial:
                  type: boolean
                  default: false
                  description: >-
                    Solo para cambios de plan a plan. Cuando es `true`, la
                    suscripción de reemplazo no adopta las fases de prueba o
                    introductorias del plan de destino: factura el precio
                    regular de ese plan desde su primer cobro y su estado sigue
                    siendo `ACTIVE` en lugar de pasar a `TRIALING`. Úsalo para
                    evitar que los suscriptores obtengan una prueba nueva al
                    cambiar de plan. Enviar `true` en una suscripción que no
                    está en un plan devuelve `400`; `false` y omitir el
                    indicador son equivalentes y siempre se aceptan.
                  examples:
                    - true
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Default (adopts the target plan's trial):
                  value:
                    id: 8f11a2b0-6c1d-4a77-9f3e-2b5c8d0e91aa
                    name: sub_001
                    account_id: 2404911d-5df9-429e-8488-ad41abea1a4b
                    country: US
                    description: streaming service
                    merchant_reference: 001_marzo_23
                    status: TRIALING
                    amount:
                      currency: USD
                      value: 12100
                    frequency:
                      type: MONTH
                      value: 1
                    billing_cycles:
                      total: 8
                      current: 1
                      next_at: '2024-01-16T20:46:54.786342Z'
                    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: null
                        usage: FIRST
                    availability:
                      start_at: '2024-01-16T20:46:54.786342Z'
                      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: sub_ext_id
                        value: AA001
                    additional_data: null
                    trial_period: null
                    initial_payment_validation: false
                    reason: null
                    subscription_agreement_id: null
                    soft_descriptor: null
                    renewal_notification_days: null
                    cancellation_time: null
                    cancellation_source: null
                    ending_time: null
                    created_at: '2023-12-16T20:46:54.786342Z'
                    updated_at: '2023-12-16T20:46:54.786342Z'
                    plan_id: 1904911d-5df9-429e-8488-ad41abea1a4d
                    plan_assigned_at: '2023-12-16T20:46:54.786342Z'
                    previous_subscription_id: 7304911d-5df9-429e-8488-ad41abea1a4c
                    phases:
                      - order: 1
                        name: Intro
                        type: TRIAL
                        duration:
                          type: MONTH
                          value: 2
                        frequency:
                          type: MONTH
                          value: 1
                        amount:
                          value: 5000
                          currency: USD
                        total_payments: 2
                        country_prices: []
                      - order: 2
                        name: Regular
                        type: REGULAR
                        duration: null
                        frequency: null
                        amount: null
                        total_payments: null
                        country_prices: []
                    current_phase: TRIAL
                    billing_phases:
                      - order: 1
                        type: TRIAL
                        name: Intro
                        amount:
                          value: 5000
                          currency: USD
                        frequency:
                          type: MONTH
                          value: 1
                        start_cycle: 1
                        end_cycle: 2
                    pending_plan_change: null
                'skip_trial: true':
                  value:
                    id: 9c2d4e6f-1a3b-4c5d-8e7f-0a1b2c3d4e5f
                    name: sub_001
                    account_id: 2404911d-5df9-429e-8488-ad41abea1a4b
                    country: US
                    description: streaming service
                    merchant_reference: 001_marzo_23
                    status: ACTIVE
                    amount:
                      currency: USD
                      value: 12100
                    frequency:
                      type: MONTH
                      value: 1
                    billing_cycles:
                      total: 8
                      current: 1
                      next_at: '2024-01-16T20:46:54.786342Z'
                    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: null
                        usage: FIRST
                    availability:
                      start_at: '2024-01-16T20:46:54.786342Z'
                      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: sub_ext_id
                        value: AA001
                    additional_data: null
                    trial_period: null
                    initial_payment_validation: false
                    reason: null
                    subscription_agreement_id: null
                    soft_descriptor: null
                    renewal_notification_days: null
                    cancellation_time: null
                    cancellation_source: null
                    ending_time: null
                    created_at: '2023-12-16T20:46:54.786342Z'
                    updated_at: '2023-12-16T20:46:54.786342Z'
                    plan_id: 1904911d-5df9-429e-8488-ad41abea1a4d
                    plan_assigned_at: '2023-12-16T20:46:54.786342Z'
                    previous_subscription_id: 7304911d-5df9-429e-8488-ad41abea1a4c
                    phases:
                      - order: 1
                        name: Intro
                        type: TRIAL
                        duration:
                          type: MONTH
                          value: 2
                        frequency:
                          type: MONTH
                          value: 1
                        amount:
                          value: 5000
                          currency: USD
                        total_payments: 2
                        country_prices: []
                      - order: 2
                        name: Regular
                        type: REGULAR
                        duration: null
                        frequency: null
                        amount: null
                        total_payments: null
                        country_prices: []
                    pending_plan_change: null
              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
                  country:
                    type: string
                    description: El país de la suscripción (ISO 3166-1 alpha-2).
                    example: US
                  merchant_reference:
                    type: string
                    example: 001_marzo_23
                  soft_descriptor:
                    type: string
                    example: ACME SUBSCRIPTION
                    nullable: true
                  status:
                    type: string
                    example: ACTIVE
                  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.
                  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
                  customer_payer:
                    type: object
                    properties:
                      id:
                        type: string
                        example: 3t04911d-5df9-429e-8488-ad41abea1a2c
                  payment_method:
                    type: object
                    properties:
                      type:
                        type: string
                        example: CARD
                      vaulted_token:
                        type: string
                        example: 6104911d-5df9-429e-8488-ad41abea1a4b
                      card:
                        type: object
                        properties:
                          installments:
                            type: integer
                            nullable: true
                          network_transaction_id:
                            type: string
                            nullable: true
                          usage:
                            type: string
                            example: FIRST
                        nullable: true
                  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
                  retries:
                    type: object
                    nullable: true
                    description: >-
                      La política de reintentos que se aplica cuando se rechaza
                      un cobro recurrente. Consulta
                      [Reintentos](/es/docs/payment-features/subscriptions/retries).
                    properties:
                      retry_on_decline:
                        type: boolean
                        description: Indica si los cobros rechazados se reintentan o no.
                        example: true
                      amount:
                        type: integer
                        description: >-
                          Cuántos reintentos tiene un ciclo de facturación.
                          Limitado por la longitud del calendario de reintentos
                          de tu entorno (6 en producción).
                        example: 4
                      strategy:
                        type: string
                        description: >-
                          Cómo se decide el momento de cada reintento:
                          `DEFAULT`, `SMART` o `CUSTOM_SCHEDULE`. Trátalo como
                          un valor abierto: maneja los valores no reconocidos de
                          forma adecuada.
                        example: DEFAULT
                      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.
                      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.
                  trial_period:
                    type: object
                    properties:
                      billing_cycles:
                        type: integer
                        example: 1
                        default: 0
                      amount:
                        type: object
                        properties:
                          value:
                            type: number
                            example: 0
                            default: 0
                          currency:
                            type: string
                            example: ''
                    nullable: true
                  metadata:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          example: sub_ext_id
                        value:
                          type: string
                          example: AA001
                    nullable: true
                  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
                  payments:
                    type: array
                    items:
                      type: string
                      example: 5104911d-5df9-229e-8468-bd41abea1a4s
                  subscription_agreement_id:
                    type: string
                    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'
                  created_at:
                    type: string
                    example: '2023-12-16T20:46:54.786342Z'
                  updated_at:
                    type: string
                    example: '2023-12-16T21:00:54.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'
                  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
                  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
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value:
                    code: INVALID_STATE
                    messages:
                      - >-
                        The subscription status <STATUS> does not support plan
                        changes.
                PIX AUTOMATICO CADENCE NOT SUPPORTED:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        Pix Automático only supports weekly, monthly, quarterly,
                        half-yearly or yearly frequencies with value 1.
                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.
        '404':
          description: '404'
          content:
            application/json:
              examples:
                Result:
                  value:
                    code: PLAN_NOT_FOUND
                    messages:
                      - >-
                        The target plan does not exist or is not linked to this
                        account.
      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.