Descripción general
Passinstance ofrece un motor determinista e idempotente de transición de suscripciones (Billing API en /api/v1/billing/subscription/* y Configuración -> Facturación /settings/billing/overview, junto con sesiones alojadas Checkout/Portal en POST /api/v1/billing/checkout/session y /portal) que permite previsualizar créditos de prorrateo al minuto antes de confirmar un cambio, ejecutar mejoras inmediatas, programar o revocar reducciones al final del período y cancelar o reanudar suscripciones sin interrumpir los pases activos.
Ciclo de vida de transición de plan y prorrateo
Importante: Solo puede bajar a un plan inferior si el recuento actual de
activePassesen su espacio de trabajo es igual o inferior al límite del plan de destino. Si sus pases activos superan el tope del nivel destino,/previewy/changedevuelven un bloqueo estructurado de capacidad indicando cuántos pases activos debe reducir previamente.
Endpoints de transición de suscripciones (Billing API)
| Endpoint | Verbo HTTP | Comportamiento operativo |
|---|---|---|
/api/v1/billing/subscription/preview | POST | Evalúa request payload ({ planId, promotionCode? }) y calcula prorrateo exacto, impuestos y elegibilidad de capacidad sin mutar estado. |
/api/v1/billing/subscription/change | POST | Ejecuta request payload ({ planId, idempotencyKey, promotionCode?, paymentMethodId?, expectedAmountDueToday?, intent? }). |
/api/v1/billing/subscription/scheduled-change/cancel | POST | Revoca una reducción pendiente de fin de período para mantener el espacio en su nivel actual. |
/api/v1/billing/subscription/cancel | POST | Programa la cancelación al finalizar el período (request payload: { reason?, feedback? }). |
/api/v1/billing/subscription/resume | POST | Revierte una cancelación pendiente antes de llegar a currentPeriodEnd, manteniendo la renovación continua. |
Recorrido por la API: previsualizar y ejecutar cambios de plan
1. Previsualizar prorrateo antes de cambiar de plan
Llame siempre a POST /api/v1/billing/subscription/preview con el planId de destino (obtenido de GET /api/v1/billing/plans):
POST /api/v1/billing/subscription/preview HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"planId": "scale_10k_monthly",
"promotionCode": "SCALEUP15"
}
Payload de respuesta (200 OK)
{
"eligible": true,
"transitionType": "IMMEDIATE_UPGRADE",
"currentPlan": { "planId": "growth_monthly", "activePassLimit": 2000 },
"targetPlan": { "planId": "scale_10k_monthly", "activePassLimit": 10000 },
"proration": {
"currency": "EUR",
"unusedCreditCents": -6000,
"proratedNewPlanCents": 20000,
"discountCents": -2100,
"subtotalCents": 11900,
"taxCents": 2261,
"totalDueNowCents": 14161,
"nextRenewalAmountCents": 40000,
"nextRenewalDate": "2026-12-01T00:00:00.000Z"
},
"blockers": []
}
2. Ejecutar subida o bajada de plan idempotente
Envíe planId y un idempotencyKey único (más el control opcional expectedAmountDueToday coincidente con la vista previa) a POST /api/v1/billing/subscription/change:
POST /api/v1/billing/subscription/change HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"planId": "scale_10k_monthly",
"idempotencyKey": "chg_20261116_scale10k",
"promotionCode": "SCALEUP15",
"expectedAmountDueToday": 141.61
}
{
"subscriptionId": "sub_019331b2-7e10-7a44-9b00-112233445566",
"status": "ACTIVE",
"planId": "scale_10k_monthly",
"effectiveActivePassLimit": 10000,
"appliedImmediately": true,
"invoiceId": "inv_01933220-5a11-7e00-9c44-887766554433"
}
3. Revocar un downgrade programado (scheduled-change/cancel)
Si había una reducción programada para entrar en vigor al final del período de facturación, puede anular dicha transición antes de currentPeriodEnd:
POST /api/v1/billing/subscription/scheduled-change/cancel HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
{
"subscriptionId": "sub_019331b2-7e10-7a44-9b00-112233445566",
"scheduledChangeCanceled": true,
"activePlanKey": "scale_10k"
}
4. Programar cancelación al final del período y reanudar
Al cancelar mediante POST /api/v1/billing/subscription/cancel, su espacio de trabajo conserva toda la capacidad contratada hasta que expire el período ya pagado:
POST /api/v1/billing/subscription/cancel HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"reason": "SEASONAL_EVENT_ENDED",
"feedback": "Our annual festival concluded; we will return next summer."
}
{
"subscriptionId": "sub_019331b2-7e10-7a44-9b00-112233445566",
"status": "ACTIVE",
"cancelAtPeriodEnd": true,
"accessValidUntil": "2026-12-01T00:00:00.000Z"
}
Para revertir la cancelación antes del 2026-12-01T00:00:00.000Z, llame a POST /api/v1/billing/subscription/resume, que restablece cancelAtPeriodEnd: false de inmediato.
Documentación relacionada
-
Compare niveles de planes en Precios y planes de suscripción.
-
Descargue facturas PDF prorrateadas en Facturas e historial de facturación.
-
Gestione tarjetas guardadas e instrumentos de pago en Métodos de pago.
