Skip to content
Guía del Centro de ayuda · Planes y uso
3 min de lecturaVerificado 2026-11-16

Cambios de plan y cancelación

Amplía o reduce capacidad de forma ordenada, cambia ciclo de pago y cancela al fin del periodo sin sorpresas.

En esta guía

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

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
MÁQUINA DE ESTADOS DE TRANSICIÓN Y PRORRATEO
ETAPA 01 PASO 1: VISTA PREVIA DE PRORRATEO
POST/api/v1/billing/subscription/preview (request payload)
Calcula crédito por tiempo no usado del plan actual vs. tiempo restante destino
Valida activePasses actuales frente al tope de capacidad del plan destino
ETAPA 02 PASO 2: EJECUCIÓN IDEMPOTENTE
Mejora / Cambio de intervalo
Desbloqueo inmediato de capacidad
Valida expectedAmountDueToday para evitar variaciones de precio
Reducción de nivel (Downgrade)
Programado en currentPeriodEnd
Revocable vía `/scheduled-change
/cancel` antes de renovar
POST/api/v1/billing/subscription/change (request payload)
ETAPA 03 PASO 3: CANCELACIÓN AL CIERRE DE PERÍODO Y REANUDACIÓN
POST/api/v1/billing/subscription/cancel (CANCEL_AT_PERIOD_END / Cancel)
POST/api/v1/billing/subscription/resume (Restaura renovación en cualquier m.)

Importante: Solo puede bajar a un plan inferior si el recuento actual de activePasses en 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, /preview y /change devuelven un bloqueo estructurado de capacidad indicando cuántos pases activos debe reducir previamente.

Endpoints de transición de suscripciones (Billing API)

EndpointVerbo HTTPComportamiento operativo
/api/v1/billing/subscription/previewPOSTEvalúa request payload ({ planId, promotionCode? }) y calcula prorrateo exacto, impuestos y elegibilidad de capacidad sin mutar estado.
/api/v1/billing/subscription/changePOSTEjecuta request payload ({ planId, idempotencyKey, promotionCode?, paymentMethodId?, expectedAmountDueToday?, intent? }).
/api/v1/billing/subscription/scheduled-change/cancelPOSTRevoca una reducción pendiente de fin de período para mantener el espacio en su nivel actual.
/api/v1/billing/subscription/cancelPOSTPrograma la cancelación al finalizar el período (request payload: { reason?, feedback? }).
/api/v1/billing/subscription/resumePOSTRevierte 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):

HTTP
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)

JSON
{
  "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:

HTTP
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
}
JSON
{
  "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:

HTTP
POST /api/v1/billing/subscription/scheduled-change/cancel HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
JSON
{
  "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:

HTTP
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."
}
JSON
{
  "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

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.