Visão geral
O Passinstance disponibiliza um motor determinístico e idempotente de transição de subscrições (Billing API em /api/v1/billing/subscription/* e Definições -> Faturação /settings/billing/overview, além de sessões alojadas Checkout/Portal em POST /api/v1/billing/checkout/session e /portal) que permite pré-visualizar créditos pro-rata ao minuto antes de confirmar uma mudança, executar upgrades instantâneos, agendar ou revogar downgrades para o fim do período e cancelar ou retomar subscrições sem interrupção dos cartões ativos.
Ciclo de Vida de Transição de Plano e Prorrateio
Importante: Só é possível efetuar downgrade para um nível inferior se a contagem atual de
activePassesdo seu espaço de trabalho for igual ou inferior ao limite de capacidade do plano de destino. Se os cartões ativos excederem o novo limite,/previewe/changedevolvem um bloqueio estruturado de capacidade indicando quantos cartões ativos devem ser reduzidos primeiro.
Endpoints de Transição de Subscrição (Billing API)
| Endpoint | Verbo HTTP | Comportamento Operacional |
|---|---|---|
/api/v1/billing/subscription/preview | POST | Avalia request payload ({ planId, promotionCode? }) e calcula o prorrateio exato, impostos e elegibilidade sem alterar estado. |
/api/v1/billing/subscription/change | POST | Executa request payload ({ planId, idempotencyKey, promotionCode?, paymentMethodId?, expectedAmountDueToday?, intent? }). |
/api/v1/billing/subscription/scheduled-change/cancel | POST | Revoga um downgrade pendente para o fim do período, mantendo o espaço no nível atual. |
/api/v1/billing/subscription/cancel | POST | Agenda o cancelamento da subscrição no final do período (request payload: { reason?, feedback? }). |
/api/v1/billing/subscription/resume | POST | Reverte um cancelamento agendado antes da chegada de currentPeriodEnd, preservando a renovação contínua. |
Guia da API: Pré-Visualizar e Executar Alterações de Plano
1. Pré-Visualizar Prorrateio Antes de Mudar de Plano
Invoque sempre POST /api/v1/billing/subscription/preview com o planId pretendido (obtido em 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 Resposta (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. Executar Upgrade ou Downgrade Idempotente
Envie planId e um idempotencyKey único (e opcionalmente a salvaguarda expectedAmountDueToday igual à pré-visualização) para 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. Revogar um Downgrade Agendado (scheduled-change/cancel)
Se foi agendado um downgrade para produzir efeito no final do ciclo de faturação, pode cancelar essa transição pendente a qualquer momento 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. Agendar Cancelamento para o Fim do Período e Retomar
Ao cancelar via POST /api/v1/billing/subscription/cancel, o espaço de trabalho mantém toda a capacidade paga até ao termo do período já faturado:
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 reverter o cancelamento antes de 2026-12-01T00:00:00.000Z, invoque POST /api/v1/billing/subscription/resume, que repõe cancelAtPeriodEnd: false de imediato.
Documentação Relacionada
-
Compare níveis de planos em Preços e Planos de Subscrição.
-
Transfira faturas PDF pro-rata em Faturas e Histórico de Faturação.
-
Gira cartões guardados e métodos de pagamento em Métodos de Pagamento.
