Suscripciones

La suscripción une un cliente con un plan. Desde que existe, Ripei genera las facturas automáticamente según la frecuencia del plan y envía los recordatorios de pago (email, SMS, WhatsApp).

Depende de: cliente + plan. La necesitan: las facturas automáticas.

Crear una suscripción


POST /subscription/company

Scope requerido: subscription.create

Cuerpo

Campo	Tipo	Requerido	Descripción
`planId`	número	Sí	ID del plan. Debe pertenecer a tu empresa.
`companyUserId`	número	Sí	ID del cliente (companyUser). Debe pertenecer a tu empresa.
`nextPaymentAt`	fecha ISO	No	Fecha del primer cobro (ej. `2026-08-01T00:00:00Z`).
`paymentCutoffAt`	número	No	Días de corte de pago. Default: `5`.
`lateFee`	número	No	Recargo por factura atrasada.
`lateFeeType`	string	No	Tipo del recargo: porcentaje o monto fijo.
`remainingInstallments`	número	No	Cuotas restantes. Si el plan tiene configuración de cuotas, se toma automáticamente de ahí.

Ciclo automático. Ripei revisa diariamente las suscripciones activas: 3 días antes de nextPaymentAt genera la factura del ciclo, y avanza nextPaymentAt según la frecuencia del plan. En planes por cuotas, cada factura descuenta una cuota; al llegar a 0 no se generan más.

Un cliente no puede tener dos suscripciones activas al mismo plan — la API responde RIPEI-SUBS-005. Sí puede tener suscripciones a planes distintos.

Ejemplo


curl -X POST https://api.qa.pagosripei.com/subscription/company \
  -H "Authorization: Bearer $RIPEI_TOKEN" \
  -H "company: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": 88,
    "companyUserId": 4275,
    "nextPaymentAt": "2026-08-01T00:00:00Z"
  }'

Respuesta `201`


{
  "id": 512,
  "planId": 88,
  "companyUserId": 4275,
  "status": "ACTIVE",
  "nextPaymentAt": "2026-08-01T00:00:00.000Z",
  "paymentCutoffAt": 5
}

Errores

Código	Causa
`RIPEI-SUBS-003`	Cliente no encontrado (o de otra empresa).
`RIPEI-SUBS-004`	Plan no encontrado (o de otra empresa).
`RIPEI-SUBS-005`	El cliente ya tiene una suscripción activa a ese plan.