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

# Listar suscripciones

> Devuelve una lista paginada de las suscripciones de una cuenta.

> [!WARNING]
>
> **Los elementos de la lista son un resumen, no la suscripción completa**
>
> Cada elemento incluye los campos necesarios para mostrar una cuadrícula, incluidos `current_period_start`/`current_period_end`. Todo lo demás (`availability`, `retries`, `metadata`, `trial_period`, `payments`, `pending_plan_change`, `billing_phases` y el resto de [El objeto de suscripción](https://docs.y.uno/es/reference/subscriptions/the-subscription-object.md)) solo lo devuelve [Consultar suscripción](https://docs.y.uno/es/reference/subscriptions/retrieve-subscription.md). Llámalo por cada elemento cuando necesites alguno de ellos.

> [!NOTE]
>
> **`merchant_reference` no es un filtro en este endpoint**
>
> Enviarlo no tiene efecto: el parámetro se ignora y se devuelve la página completa, sin filtrar. Para buscar una suscripción por referencia del comercio, conserva el `id` que recibiste al crearla, o recorre las páginas de este endpoint y haz la coincidencia del lado del cliente.

## Alcance y orden

La lista siempre está limitada a la única cuenta indicada en el encabezado `X-Account-Code`: no existe una variante entre cuentas. Los resultados se ordenan por `created_at` en orden descendente, por lo que una suscripción creada mientras recorres las páginas puede desplazar elementos entre los límites de página. Para un recorrido estable, filtra con `created_at_to` fijado en el momento en que empezaste.

Los filtros se pueden combinar y todos son opcionales; cada uno reduce aún más el conjunto de resultados. Si no se define ninguno, se devuelven las suscripciones en todos los estados, incluidas las `CANCELED` y `COMPLETED`.


## OpenAPI

````yaml openapi/es/subscriptions/list-subscriptions.json GET /subscriptions
openapi: 3.1.0
info:
  title: subscription
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - sec0: []
    sec1: []
paths:
  /subscriptions:
    get:
      summary: List Subscriptions
      description: >-
        Devuelve una lista paginada de las suscripciones de la cuenta, de la más
        nueva a la más antigua (`created_at` descendente). Los filtros se pueden
        combinar y todos son opcionales; sin ninguno definido, se devuelven las
        suscripciones de todos los estados. Paginación con índice desde 1.
      operationId: list-subscriptions
      parameters:
        - in: header
          name: X-Account-Code
          required: true
          schema:
            type: string
          description: >-
            El `account_id` que se encuentra en tu [Dashboard de
            Yuno](https://dashboard.y.uno/developers) (UUID). Obligatorio: la
            lista siempre se limita a una sola cuenta. Omitirlo devuelve `400
            INVALID_PARAMETERS` ("x-account-code header is required.").
        - name: customer_id
          in: query
          description: >-
            Filtra por el cliente que es dueño de la suscripción
            (`customer_payer.id`, UUID). Un valor que no es un UUID devuelve
            `400 BAD_REQUEST` ("Invalid customer_id.").
          schema:
            type: string
            example: 3t04911d-5df9-429e-8488-ad41abea1a2c
        - name: status
          in: query
          description: >-
            Filtra por estado. Acepta varios valores separados por comas, que
            coinciden con cualquiera de ellos: `ACTIVE,PAUSED`. Los valores
            deben escribirse exactamente como en [Estados de la
            suscripción](/es/reference/subscriptions/status-subscriptions); un
            valor desconocido devuelve `400 BAD_REQUEST` ("Invalid status:
            FOO.").
          schema:
            type: string
            example: ACTIVE,PAUSED
        - name: plan_id
          in: query
          description: >-
            Filtra por el [plan](/es/reference/plans/the-plan-object) al que
            está vinculada la suscripción (UUID). Un plan sin suscriptores, o
            uno que no existe, devuelve una lista vacía, no un error. Un valor
            que no es un UUID devuelve `400 BAD_REQUEST` ("Invalid plan_id.").
          schema:
            type: string
            example: 00000000-0000-4000-8000-000000000001
        - name: created_at_from
          in: query
          description: >-
            Devuelve solo las suscripciones creadas en este instante o después
            (ISO 8601 con desfase, inclusive). Un valor que no se puede
            interpretar devuelve `400 BAD_REQUEST` ("Invalid created_at_from.").
          schema:
            type: string
            example: '2024-01-01T00:00:00Z'
        - name: created_at_to
          in: query
          description: >-
            Devuelve solo las suscripciones creadas en este instante o antes
            (ISO 8601 con desfase, inclusive). Un valor que no se puede
            interpretar devuelve `400 BAD_REQUEST` ("Invalid created_at_to.").
          schema:
            type: string
            example: '2024-12-31T23:59:59Z'
        - name: payment_method_type
          in: query
          description: >-
            Filtra por el tipo de método de pago de la suscripción, por ejemplo
            `CARD`.
          schema:
            type: string
            example: CARD
        - name: page
          in: query
          description: >-
            Número de página con índice desde 1. Debe ser >= 1, de lo contrario
            `400 BAD_REQUEST` ("The page must be greater than or equal to 1.").
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: size
          in: query
          description: >-
            Tamaño de página. Debe estar entre 1 y 100 inclusive, de lo
            contrario `400 BAD_REQUEST` ("The size must be greater than or equal
            to 1." si es demasiado bajo, "The size must be at most 100." si es
            demasiado alto).
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value:
                    items:
                      - id: 7304911d-5df9-429e-8488-ad41abea1a4c
                        name: sub_001
                        status: ACTIVE
                        merchant_reference: 001_marzo_23
                        account_id: 2404911d-5df9-429e-8488-ad41abea1a4b
                        customer_payer:
                          id: 3t04911d-5df9-429e-8488-ad41abea1a2c
                        amount:
                          currency: USD
                          value: 12100
                        frequency:
                          type: MONTH
                          value: 1
                        billing_cycles:
                          total: 10
                          current: 2
                          next_at: '2023-02-16T20:00:00.786342Z'
                        payment_method:
                          type: CARD
                        plan_id: 00000000-0000-4000-8000-000000000001
                        created_at: '2023-12-16T20:46:54.786342Z'
                        current_period_start: '2023-01-16T20:00:00.912480Z'
                        current_period_end: '2023-02-16T20:00:00.786342Z'
                    pagination:
                      page: 1
                      size: 20
                      total: 1
                      total_pages: 1
                  summary: Result
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: El identificador único de la suscripción.
                        name:
                          type: string
                        status:
                          type: string
                          description: >-
                            Consulta [Estados de la
                            suscripción](/es/reference/subscriptions/status-subscriptions).
                        merchant_reference:
                          type: string
                        account_id:
                          type: string
                        customer_payer:
                          type: object
                          properties:
                            id:
                              type: string
                              description: El identificador único del cliente.
                        amount:
                          type: object
                          properties:
                            currency:
                              type: string
                            value:
                              type: number
                        frequency:
                          type: object
                          nullable: true
                          description: >-
                            `null` en suscripciones facturadas con
                            `billing_date` en lugar de una frecuencia.
                          properties:
                            type:
                              type: string
                            value:
                              type: integer
                            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
                          description: >-
                            Misma semántica que en [El objeto
                            Suscripción](/es/reference/subscriptions/the-subscription-object):
                            `current` es el próximo ciclo que se cobrará, no el
                            que está en curso.
                          properties:
                            total:
                              type: integer
                              nullable: true
                            current:
                              type: integer
                            next_at:
                              type: string
                            scheduling_date:
                              type: string
                              description: >-
                                Cuándo la instrucción de débito se entrega al
                                riel de Pix: `next_at` menos cuatro días. Solo
                                está presente en ítems `PIX_AUTOMATIC` que
                                ejecuta Yuno, y solo cuando el margen de
                                programación de cuatro días está habilitado para
                                la organización; está ausente, no es `null`, en
                                caso contrario. Solo lectura. Consulta [Pix
                                Automático](/es/docs/payment-features/subscriptions/pix-automatico#the-scheduling-date).
                            paid:
                              type: integer
                              description: >-
                                Cuántos ciclos se han pagado hasta ahora.
                                Distinto de `current`, que es el ciclo que se
                                está facturando.
                        payment_method:
                          type: object
                          properties:
                            type:
                              type: string
                              description: El tipo de método de pago, por ejemplo `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
                        plan_id:
                          type: string
                          nullable: true
                          description: >-
                            El plan al que está vinculada la suscripción, o
                            `null` para suscripciones creadas con un
                            `amount`/`frequency` directo.
                        created_at:
                          type: string
                        current_period_start:
                          type: string
                          nullable: true
                          description: >-
                            Misma semántica que en [El objeto
                            Suscripción](/es/reference/subscriptions/the-subscription-object):
                            inicio del período de facturación en el que está la
                            suscripción actualmente.
                        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`.
                        description:
                          type: string
                          example: streaming service
                          nullable: true
                        country:
                          type: string
                          description: El país de la suscripción (ISO 3166-1 alpha-2).
                          example: US
                        soft_descriptor:
                          type: string
                          example: ACME SUBSCRIPTION
                          nullable: true
                        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
                        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: ''
                        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_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'
                        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
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                        description: La página devuelta; repite la de la solicitud.
                      size:
                        type: integer
                        description: >-
                          El tamaño de página devuelto; repite el de la
                          solicitud.
                      total:
                        type: integer
                        description: >-
                          Total de suscripciones que coinciden con los filtros,
                          en todas las páginas.
                      total_pages:
                        type: integer
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value:
                    code: BAD_REQUEST
                    messages:
                      - The page must be greater than or equal to 1.
                  summary: Result
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: BAD_REQUEST
                  messages:
                    type: array
                    items:
                      type: string
      deprecated: false
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: public-api-key
      x-default: <Your public-api-key>
    sec1:
      type: apiKey
      in: header
      name: private-secret-key
      x-default: <Your private-secret-key>

````

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