Suscripción

Una Subscription liga a un Customer con un Plan y es la entidad que Rekurra usa para agendar y ejecutar los cobros recurrentes sobre tu cuenta de Wompi.

Campos

Campo	Tipo	Descripción
`id`	string	Identificador único
`customer_id`	string	Cliente dueño de la suscripción
`plan_id`	string	Plan al que está suscrito
`status`	string	`trialing` · `active` · `past_due` · `paused` · `paused_insufficient_balance` · `canceled`
`cycle`	string	`monthly` o `annual`
`current_period_start`	datetime	Inicio del periodo de facturación actual
`current_period_end`	datetime	Fin del periodo de facturación actual
`next_charge_date`	datetime	Próxima fecha de cobro programada
`default_payment_method_id`	string	Método de pago usado para los cobros
`trial_end`	datetime?	Fin del periodo de prueba, si aplica
`cancel_at_period_end`	boolean	Si se cancelará al terminar el periodo actual
`failed_attempts`	integer	Intentos de cobro fallidos consecutivos
`created_at`	datetime	Fecha de creación

Estados

trialing — dentro del periodo de prueba (trial_days), sin cobros.
active — al día, cobros ejecutándose en cada ciclo.
past_due — el último cobro falló; Rekurra reintenta durante un periodo de gracia.
paused — pausada manualmente vía POST /{id}/pause.
paused_insufficient_balance — Rekurra pausó los cobros porque tu saldo prepago no alcanza para cubrir el fee proyectado. Ver Saldo prepago.
canceled — cancelada, ya sea inmediatamente o al final del periodo (cancel_at_period_end).

Acciones disponibles

POST /{id}/cancel — cancela, con at_period_end: true opcional.
POST /{id}/pause / POST /{id}/resume — pausa y reanuda manualmente.
POST /{id}/change-plan — cambia de plan/ciclo, con prorrateo opcional.
POST /{id}/change-plan/preview — dry-run: calcula el monto prorrateado sin aplicar el cambio.
POST /{id}/charge-now — fuerza un reintento manual de cobro.

Las suscripciones se crean con el checkout hospedado (ver Crear una suscripción); la creación de la checkout session respeta el header Idempotency-Key para evitar duplicados por reintentos de red.

Metadata

La metadata que envías (al crear la checkout session, o directamente al crear la suscripción) queda guardada en la Subscription y viaja con ella: checkout → suscripción → cada webhook que dispares para esa suscripción la incluye en data.metadata. Ver API → Subscriptions y Webhooks → metadata en cada evento.

Cambio de plan con prorrateo

Puedes mover una suscripción a otro plan (upsell o downsell) con POST /{id}/change-plan. El prorrateo es por tiempo restante del periodo actual: un upgrade se cobra de inmediato por la diferencia; un downgrade no se reembolsa y el precio más bajo aplica desde la siguiente renovación. Puedes previsualizar el monto antes de aplicarlo con POST /{id}/change-plan/preview. Ver el detalle completo en API → Subscriptions → Cambiar de plan.

Addons

Un Addon es un producto recurrente reutilizable (definido una sola vez en tu catálogo) que se adjunta a una suscripción para aumentar su monto de cobro por periodo. El monto recurrente de la suscripción siempre es precio del plan + suma de addons activos adjuntos. Ver API → Addons y la sección Addons de la suscripción.

Un plan solo puede eliminarse permanentemente desde el panel (no desde la API pública) y únicamente si no tiene suscripciones asociadas.

Ver la referencia completa en API → Subscriptions y la guía Crear una suscripción.

Plan Cliente