Saltar al contenido principal

Atributos

Este objeto representa una suscripción que se puede asociar a un cliente.
Campos que calcula Yunobilling_cycles.scheduling_date, retries.stopped, retries.attempts_made, retries.outcome y retries.next_retry_at los calcula Yuno a partir del estado propio de la suscripción. Son de solo lectura: si los envías, se ignoran en Crear suscripción y en Actualizar suscripción, y los valores que lees siempre son los de Yuno.
string
El identificador único de la suscripción (MAX 64 ; MIN 36).Ejemplo: 7304911d-5df9-429e-8488-ad41abea1a4c
string
El nombre de la suscripción (MAX 255; MIN 3).Ejemplo: sub_001
string
La descripción de la suscripción (MAX 255; MIN 3).Ejemplo: Servicio de streaming
string
El identificador único de la cuenta que tendrá disponible el plan de suscripción para usar (MAX 64 ; MIN 36).Ejemplo: 2404911d-5df9-429e-8488-ad41abea1a4b
string
Identificación del plan de suscripción (MAX 255; MIN 3).Ejemplo: 001_marzo_23
string
Descriptor que aparece en el estado de cuenta bancario del titular de la tarjeta (MAX 255). Cuando se define, se propaga a cada pago de recobro que genera el motor de suscripciones. Los límites de longitud y formato varían según el proveedor; consulta Descriptor en pagos recurrentes.Ejemplo: ACME SUBSCRIPTION
string
El país de la suscripción.Ejemplo: CO
enum
Estado de la suscripción.Valores posibles del enum:
  • CREATED = Estado transitorio mientras el pago inicial aún no se ha procesado. Solo ocurre cuando la suscripción se crea con initial_payment_validation: true; pasa a ACTIVE cuando el primer pago es exitoso (o a CANCELED si falla y se agotan los reintentos).
  • ACTIVE = La suscripción se creó con un cliente asociado y ya está activa.
  • TRIALING = La suscripción está dentro de la fase de prueba inicial de un plan (consulta plan_id/current_phase). Pasa a ACTIVE automáticamente cuando termina la prueba; esto se notifica por webhook como cualquier otro cambio de estado.
  • PAST_DUE = Un cobro recurrente falló y la suscripción espera su recuperación. Sigue facturando y aún se puede cancelar; el siguiente cobro exitoso la devuelve a ACTIVE, o a TRIALING si la fase de prueba aún está en curso, y cada transición se notifica por webhook. Si el estado no está habilitado para tu cuenta, un cobro fallido deja la suscripción en ACTIVE mientras se ejecutan los reintentos. Consulta Reintentos.
  • PAUSED = La suscripción se pausó y se puede reactivar.
  • COMPLETED = La suscripción se completó porque llegó a la fecha y hora de finalización.
  • CANCELED = Suscripción cancelada. Consulta cancellation_source para saber qué la originó.
enum
Qué causó la cancelación de la suscripción. Solo se define cuando la suscripción llega a CANCELED; en otro caso es null.Valores posibles:
  • MERCHANT = Tú cancelaste la suscripción, mediante Cancelar suscripción o el dashboard.
  • SYSTEM = Yuno canceló la suscripción automáticamente. Esto incluye una suscripción creada con initial_payment_validation: true cuyo primer pago no fue exitoso.
  • PLAN_CHANGE = La suscripción se reemplazó como parte de un cambio de plan. Una nueva suscripción continúa la facturación del cliente con el nuevo plan.
  • RETRIES_EXHAUSTED = Los reintentos de un ciclo de facturación terminaron sin un pago exitoso mientras la suscripción tenía retries.cancel_on_exhausted_retries en true. Consulta Reintentos.
Trata este campo como abierto. Pueden incorporarse valores nuevos a medida que Yuno agregue comportamientos de cancelación, por lo que debes manejar un valor desconocido sin errores en lugar de evaluar de forma exhaustiva la lista anterior. RETRIES_EXHAUSTED es la incorporación más reciente.
string
El identificador único del plan a partir del cual se creó esta suscripción, si existe (MAX 64; MIN 36). Solo está presente cuando la suscripción está vinculada a un plan, y no aparece (no es null) en las suscripciones creadas con un amount/frequency directos en lugar de un plan_id.Ejemplo: 00000000-0000-4000-8000-000000000001
Timestamp
Cuando la suscripción está vinculada a un plan, el momento en que se asoció el plan: al crearla a partir de un plan, al migrarla a un plan o en un cambio de plan. Solo está presente en suscripciones vinculadas a un plan.
string
Cuando esta suscripción se creó mediante un cambio de plan (pasar una suscripción existente a un plan distinto), este es el id de la suscripción que reemplazó. Solo está presente en ese caso.Un plan_change programado con Actualizar suscripción, ya sea que se ejecute más adelante en el siguiente ciclo de facturación o que se aplique de inmediato (IMMEDIATE) en la misma llamada, se aplica a esta misma suscripción y nunca define este campo. Reactivar una suscripción CANCELED o COMPLETED tampoco lo define: al reactivar, se devuelve la misma suscripción a un estado activo en lugar de crear una sucesora.
array of objects
Las definiciones de fases del plan vinculado, tal como las declara el plan. Solo está presente en suscripciones vinculadas a un plan que tiene fases.Esta es la escala del plan, no la de este suscriptor. A diferencia de billing_phases, incluye la fase terminal REGULAR, y se lee del plan en lugar de capturarse al crear la suscripción, por lo que refleja el plan tal como está hoy. En la fila REGULAR, duration, frequency y amount son todos null: esa fase se ejecuta hasta que termina la suscripción y su precio se resuelve desde el plan en cada facturación.Usa billing_phases para saber lo que realmente se cobrará a esta suscripción, y phases para describir el plan en que se basa.
enum
En qué fase de la escala de prueba del plan vinculado se encuentra actualmente la suscripción. Solo está presente en suscripciones vinculadas a un plan. Tampoco aparece cuando la suscripción se creó mediante un cambio de plan con skip_trial: true: esa suscripción está vinculada a un plan y su plan tiene fases, pero nunca entra en la escala.Valores posibles: TRIAL, REGULAR.
Timestamp
Cuándo la fase indicada por current_phase pasa a la siguiente: para una suscripción en su prueba, el momento en que cambia al precio regular. Es el final del último período de facturación que cubre la fase, por lo que en el último período de una prueba es igual a current_period_end.Es null en suscripciones que no están dentro de una fase: las que no tienen plan y las vinculadas a un plan que ya salieron de la escala y están en el precio regular del plan.Ejemplo: 2023-03-16T20:00:00.786342Z
array of objects
Las fases TRIAL iniciales del plan, capturadas para el país de este suscriptor en el momento de la creación. Solo está presente en suscripciones vinculadas a un plan que tiene fases. Tampoco aparece cuando la suscripción se creó mediante un cambio de plan con skip_trial: true: esa suscripción está vinculada a un plan y su plan tiene fases, pero nunca entra en la escala.
La fase terminal REGULAR nunca se incluye aquí. Su precio no se fija al crear la suscripción: se resuelve desde el plan en cada facturación, de modo que los cambios de precio del plan llegan a las suscripciones en curso. Cuando current_phase es REGULAR, la escala está agotada y la suscripción factura el precio regular del plan; no hay una fila correspondiente en este arreglo.
object
Especifica el objeto de monto de la suscripción, con el valor y la moneda.
object
La frecuencia definida para la suscripción de pago. Si no se define, los valores predeterminados son MONTH para el tipo y 1 para el valor.
object
Especifica el objeto billing_cycles.
Timestamp
El inicio del período de facturación actualmente en curso: una cadencia de facturación antes de current_period_end. Se deriva del calendario, no de los pagos, por lo que una suscripción informa su ventana desde el momento en que se crea, antes de que se haya intentado cualquier cobro.La cadencia utilizada es la que programó la ventana. Dentro de una fase de un plan (una prueba, un precio introductorio, cualquier fase de un plan), es el paso propio de la fase, por lo que una prueba de 14 días informa períodos de 14 días aunque el plan facture mensualmente. En el primer ciclo después de que termina una fase, la ventana todavía mide la cadencia de la fase que la programó.Nunca queda antes de availability.start_at: el primer período de una suscripción comienza cuando comienza la suscripción.Se devuelve en Obtener suscripción, en Listar suscripciones y en los payloads de webhook de suscripciones.Las suscripciones terminales informan su último período de facturación en lugar de pasar a null: una suscripción CANCELED o COMPLETED conserva la última ventana que tuvo, igual que PAUSED congela su ventana en lugar de avanzarla. Es null, junto con current_period_end, solo cuando la suscripción no tiene ninguna cadencia recurrente. En las respuestas REST, las claves pueden omitirse por completo en lugar de enviarse como null: trata null y ausente como lo mismo.Ejemplo: 2023-01-16T20:00:00.912480Z
Timestamp
El final del período de facturación actualmente en curso, que también es cuando se programa el siguiente cobro. Siempre es igual a billing_cycles.next_at.Este par describe el período en el que la suscripción está programada, no uno que necesariamente esté pagado: si el cobro de un ciclo falló y sus reintentos siguen en ejecución, la ventana ya se movió al período que ese cobro debía abrir. Una suscripción PAUSED conserva la ventana dentro de la cual se pausó en lugar de avanzarla, y una suscripción CANCELED o COMPLETED conserva su ventana final en lugar de borrarla; en ambos casos current_period_end puede estar muy en el pasado, así que revisa status antes de leerlo como una fecha futura.Es null bajo las mismas condiciones que current_period_start; los dos siempre se devuelven juntos.Ejemplo: 2023-02-16T20:00:00.786342Z
object
[Opcional] Especifica el objeto billing_date. Es mutuamente excluyente con el objeto frequency.
object
Especifica el objeto customer_payer.
object
Especifica el objeto payment_method.
object
Especifica el objeto trial_period.
object
Especifica el objeto availability. Las fechas en que la suscripción estará disponible. Si es null, la fecha de inicio será el día de la creación y no tendrá fecha de finalización.
object
Especifica el objeto retries. Define si se deben reintentar en Yuno las transacciones rechazadas y la cantidad, si es necesario.
object
La cancelación programada para esta suscripción, o null cuando no hay ninguna pendiente. Programa una con el bloque schedule en POST /v1/subscriptions/{id}/cancel; deshazla con "schedule": null. Consulta Cancelar suscripción.
object
La regla vigente que se usa para calcular un reembolso CUSTOM al cancelar cuando la solicitud de cancelación no incluye refund_amount. Se omite (no es null) cuando no hay ninguna regla configurada. Defínela en Crear suscripción o Actualizar suscripción; envía "refund_rule": null en la actualización para borrarla. Disponible para las organizaciones que la tienen habilitada; contacta a Yuno. Consulta Cancelar suscripción para ver cómo se usa.
Timestamp
Cuándo se reanudará por sí sola una suscripción pausada. Solo está presente mientras status es PAUSED y se indicó una duración al pausar; se omite (no es null) en una pausa sin fecha de fin y en cualquier otro estado. Se define con pause_cycles o pause_until en Pausar suscripción; una duración indicada en ciclos se resuelve a un instante una sola vez, en el momento de la pausa, y se informa aquí en cada lectura posterior.
object
El ciclo de facturación actual, cuando está PAST_DUE y no se ha saldado. Se omite (no es null) en cualquier otro estado.
Si este campo sigue informando el ciclo sin saldar una vez que la suscripción llega a CANCELED, o se omite en ese momento, está pendiente de confirmación del producto; verifica con una respuesta real antes de depender de ello.
object
La cotización de reembolso de la última cancelación inmediata, o null/se omite cuando nunca se calculó ninguna. Se solicita con el modo refund en POST /v1/subscriptions/{id}/cancel; consulta Cancelar suscripción. Una vez calculada, persiste y sigue apareciendo en cada lectura posterior de la suscripción.
bool
Indicador para identificar si la suscripción debe esperar el primer pago para continuar. False de forma predeterminada.Ejemplo: false
object
El cambio de plan programado para el siguiente ciclo de facturación, o null cuando no hay ninguno pendiente. Programa uno con el bloque plan_change en PATCH /v1/subscriptions/{id}; deshazlo con "plan_change": null.Un cambio programado se aplica a esta misma suscripción: no se crea ninguna suscripción nueva, y no se define ni previous_subscription_id ni cancellation_source: PLAN_CHANGE.
array of objects
Especifica el arreglo metadata.
string
Vincula esta suscripción con el pago inicial creado con el mismo ID de acuerdo. Se usa para seguimiento, conciliación y gestión de contracargos (MAX 255).El valor debe coincidir exactamente con el subscription_agreement_id enviado en payment_method.detail.card.stored_credentials.subscription_agreement_id en el pago de origen (payment_method.detail.wallet.stored_credentials.subscription_agreement_id cuando el pago de origen es un CIT de wallet).Ejemplo: sa_6af2dfcd-44c0-4f16-a331-8bed3ed9c9fa
Array of strings
Especifica el arreglo payments.
Actualmente este arreglo siempre está vacío en los payloads de webhook. Suscríbete a los webhooks payment.* para dar seguimiento a los cobros. Para el historial completo de cobros de la suscripción (montos, proveedor, contexto de fase), usa Listar pagos de la suscripción en lugar de este campo.
Ejemplo: [“5104911d-5df9-229e-8468-bd41abea1a4s”]
int
Cantidad de días antes de la siguiente fecha de facturación en que se envía el webhook subscription.close_to_renewal. null significa que no se envía ninguna notificación de renovación para esta suscripción.Ejemplo: 3
string
Motivo libre del estado actual de la suscripción, cuando se registró uno. Es null en suscripciones cuyo estado cambió sin motivo, de máximo 255 caracteres.Se define con el campo reason propio de la suscripción en Crear suscripción, Actualizar suscripción, Pausar suscripción y Reanudar suscripción; cada una escribe su propio reason, por lo que uno posterior sobrescribe a uno anterior. Reactivar una suscripción CANCELED o COMPLETED lo devuelve a null.Ejemplo: “merchant request”
Timestamp
Cuándo se canceló la suscripción (ISO 8601). Solo se define cuando la suscripción llega a CANCELED; en otro caso es null. Consulta cancellation_source para saber qué la originó.Ejemplo: 2023-12-16T20:46:54.786342Z
Timestamp
Cuándo se completó o venció la suscripción (ISO 8601). Solo se define cuando la suscripción llega a COMPLETED; en otro caso es null.Ejemplo: 2024-12-16T20:46:54.786342Z
Timestamp
Fecha y hora de creación de la suscripción (ISO 8601 MAX 27; MIN 27).Ejemplo: 2023-12-16T20:46:54.786342Z
Timestamp
Fecha y hora de la última actualización de la suscripción (ISO 8601 MAX 27; MIN 27).Ejemplo: 2023-12-16T21:00:54.786342Z
object
Especifica el objeto additional_data. Este objeto no es obligatorio. Sin embargo, si envías esta información, la experiencia de pago de tu usuario mejorará.