Skip to main content
Las suscripciones de Therius te dan un motor completo de facturación recurrente listo para usar. Los planes definen el monto de facturación, la moneda y el intervalo. Las suscripciones inscriben a clientes individuales en un plan y almacenan su método de pago de forma segura. A partir de ahí, Therius maneja las renovaciones automáticas según lo programado, la lógica del período de prueba, los reintentos de gestión de cobros cuando un pago falla, y los eventos de ciclo de vida que puedes escuchar vía webhooks — para que te concentres en tu producto en vez de en los casos límite de facturación.

​
Estados de suscripción

Cada suscripción atraviesa un conjunto definido de estados a lo largo de su vida:

​
Planes

Un plan es la plantilla que define cuánto cobras y con qué frecuencia. Crea un plan una vez y adjúntale tantas suscripciones como necesites.
La respuesta incluye un id de plan que pasas al inscribir a un cliente.
Los campos amount e interval son inmutables después de crear un plan. Si necesitas cambiar el precio o la frecuencia de facturación, crea un plan nuevo y migra a los suscriptores existentes usando el endpoint de cambio de plan descrito abajo.

​
Crear una suscripción

Inscribir a un cliente es una Cardholder Initiated Transaction (CIT), y una CIT puede requerir 3D Secure. Pasa la tarjeta de una de dos formas:
  • card.nonceData / card.cardData — Therius ejecuta la CIT + el primer cobro aquí. Simple, pero esta CIT no puede hacer un desafío de 3D Secure, así que una tarjeta que requiere 3DS falla.
  • card.tokenData — una tarjeta que ya completó su CIT (con 3DS) vía /payment/authorization o /payment/purchase. Therius registra el mandato y, para el ciclo 1, o bien cobra un MIT o — si pasas firstPaymentId (el id de pago de esa CIT) — enlaza el pago que ya hiciste. Esta es la ruta confiable para tarjetas con 3DS. Ver la referencia del endpoint.
Sea cual sea la que uses, el cliente debe haber estado presente y consintiendo la facturación recurrente cuando se recolectó la tarjeta.
La respuesta incluye el id de la suscripción, su status inicial (trialing si el plan tiene prueba, de lo contrario pending hasta que el primer pago se acredite), las fechas de inicio y fin del período actual, y el objeto de la primera factura.
Sea como sea que suministres la tarjeta — nonce del SDK, cardData sin procesar, o un token vt_... — las reglas de las banderas de tarjeta requieren que el cliente esté activamente presente y consintiendo cuando su tarjeta se guarda por primera vez para cobros recurrentes. Si usas un nonce del SDK, debe ser fresco; no puedes reutilizar un nonce de una sesión anterior.

​
Gestión del ciclo de vida

Después de que una suscripción esté activa, usa los siguientes endpoints para administrarla. Todos los endpoints aceptan POST y requieren tu clave de API.

Pausar

POST /subscription/{id}/pauseSuspende las renovaciones de inmediato. No se intentan cobros mientras la suscripción está pausada. La fecha de facturación se recalcula cuando reanudas.

Reanudar

POST /subscription/{id}/resumeRestaura una suscripción pausada (recalcula la próxima fecha de facturación) o vuelve a cobrar de inmediato una suscripción suspendida para devolverla a activa.

Cancelar

POST /subscription/{id}/cancelCancela la suscripción de forma permanente. Therius dispara el evento de webhook subscription.cancelled. Las suscripciones canceladas no se pueden reactivar.

Cambiar de plan

POST /subscription/{id}/change-planMigra al suscriptor a un plan diferente. Pasa "applyAt": "now" para un cambio inmediato prorrateado, o "applyAt": "next_billing" para cambiar al final del período actual.

Actualizar método de pago

POST /subscription/{id}/payment-methodReemplaza la tarjeta almacenada y su mandato. Cambiar la tarjeta es una CIT y puede necesitar 3D Secure — o bien registra una tarjeta que ya CIT’aste en otro lugar (card.tokenData, sin cobro, sin 3DS aquí), o ejecuta una CIT de valor cero aquí (card.nonceData / card.cardData). Solo la ruta en modo CIT puede reactivar una suscripción suspended. Ver la referencia del endpoint.

Reintentar pago

POST /subscription/{id}/retry-paymentEncola un intento de gestión de cobros inmediato para una suscripción past_due sin esperar el próximo reintento programado.

Mover día de facturación

POST /subscription/{id}/update-billing-dayEstablece el día del mes en el que se cobran las renovaciones. Acepta valores 1–28.

​
Facturación por uso e híbrida

Además del amount fijo de un plan, puedes cobrar por el consumo medido — un híbrido de tarifa base fija y tarifa variable por uso. Hay tres piezas: 1. Medidores. Un medidor es un contador con nombre, propio de tu cuenta de comercio, p. ej. api_requests o data_stored_gb. Cada medidor tiene un modo de agregación que decide cómo se combinan los eventos de un período en una única cantidad facturable: 2. Tarificación por plan. Cada medidor se tarifica en un plan con un esquema:
  • per_unit — un precio fijo por unidad.
  • volume — todas las unidades se tarifican a la tarifa del único tramo en el que cae la cantidad total.
  • graduated — cada tramo tarifica solo las unidades que caen dentro de su propio rango.
Una franquicia de includedUnits se resta antes de tarificar cada período.
Los medidores y su tarificación por plan se gestionan en el Dashboard, en Suscripciones → Medidores de uso. No hay API para configurar medidores ni precios.
3. Reportar uso. A lo largo del período de facturación, llama a POST /subscription/usage por cada evento de uso:
Envía un header Idempotency-Key si tu trabajo de reporte puede reintentar — un (meterCode, Idempotency-Key) duplicado devuelve el evento original. Un occurredAt opcional fija a qué período de facturación cuenta el evento (por defecto, ahora). En cada renovación Therius agrega los eventos del período, aplica la tarificación y suma el resultado a la factura. Una factura híbrida lleva un array lines — una línea para la tarifa base más una por cada complemento medido — y el amount de la factura es su suma. Consulta Ver facturas.

​
Gestión de cobros

Cuando una renovación programada falla — por ejemplo, por fondos insuficientes o una tarjeta expirada — Therius mueve automáticamente la suscripción a past_due y comienza la secuencia de gestión de cobros. Los reintentos se espacian según los topes de reintento de las banderas de tarjeta y tu configuración de comercio. Una vez agotados todos los reintentos, la suscripción pasa a suspended y Therius dispara un webhook subscription.suspended. Ver el catálogo de eventos de webhook para cada evento de suscripción al que te puedes suscribir. Para reactivar una suscripción suspendida, el cliente debe proporcionar un nuevo método de pago:
Therius intenta de inmediato un cobro de recuperación. Si tiene éxito, la suscripción vuelve a active.
Esta ruta de reactivación ejecuta su propia CIT y no puede completar un desafío de 3D Secure. Si la nueva tarjeta requiere 3DS, ejecuta tú mismo una CIT + cobro de recuperación con capacidad 3DS vía /payment/purchase, y luego registra el token resultante con card.tokenData — ver la referencia de Actualizar tarjeta archivada.

​
Suscripciones padre / hijo

Puedes enlazar suscripciones entre sí pasando parentSubscriptionId al crear una hija. Esto es útil para complementos, ampliaciones de asientos, o cualquier modelo de facturación donde varios ítems de línea deban compartir un ciclo de vida.
Establece propagateLifecycle: true para propagar en cascada los cambios de estado — pausar, reanudar y cancelar — desde la suscripción padre a todas sus hijas automáticamente. Cuando propagateLifecycle es false (el valor por defecto), cada suscripción administra su ciclo de vida de forma independiente.