Atributos
Este objeto representa una suscripción que se puede asociar a un cliente.Campos que calcula Yuno
billing_cycles.scheduling_date, retries.stopped, retries.attempts_made, retries.outcome y retries.next_retry_at los calcula Yuno a partir del estado propio de la suscripción. Son de solo lectura: si los envías, se ignoran en Crear suscripción y en Actualizar suscripción, y los valores que lees siempre son los de Yuno.El identificador único de la suscripción (MAX 64 ; MIN 36).Ejemplo: 7304911d-5df9-429e-8488-ad41abea1a4c
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
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
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 coninitial_payment_validation: true; pasa aACTIVEcuando el primer pago es exitoso (o aCANCELEDsi 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 (consultaplan_id/current_phase). Pasa aACTIVEautomá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 aACTIVE, o aTRIALINGsi 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 enACTIVEmientras 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. Consultacancellation_sourcepara saber qué la originó.
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 coninitial_payment_validation: truecuyo 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íaretries.cancel_on_exhausted_retriesentrue. 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.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-000000000001Cuando 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.
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.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.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.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.786342ZLas 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 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.
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.912480ZEl 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[Opcional] Especifica el objeto billing_date. Es mutuamente excluyente con el objeto frequency.
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.
Especifica el objeto retries. Define si se deben reintentar en Yuno las transacciones rechazadas y la cantidad, si es necesario.
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.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.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.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.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.Indicador para identificar si la suscripción debe esperar el primer pago para continuar. False de forma predeterminada.Ejemplo: false
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.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-8bed3ed9c9faEspecifica el arreglo payments.Ejemplo: [“5104911d-5df9-229e-8468-bd41abea1a4s”]
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.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: 3Motivo 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”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.786342ZCuá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.786342ZFecha y hora de creación de la suscripción (ISO 8601 MAX 27; MIN 27).Ejemplo: 2023-12-16T20:46:54.786342Z
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