Skip to content
Guia da Central de Ajuda · Planos e utilização
3 min de leituraVerificado 2026-11-16

Alterações de plano e cancelamento

Faça upgrades imediatos, altere ciclos de faturação e cancele no fim do período já pago sem surpresas.

Neste guia

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

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
MÁQUINA DE ESTADOS DE TRANSIÇÃO E PRORRATEIO
ETAPA 01 PASSO 1: PRÉ-VISUALIZAÇÃO PRO-RATA
POST/api/v1/billing/subscription/preview (request payload)
Calcula crédito do período não utilizado vs. tempo restante no plano de destino
Valida activePasses atuais face ao limite de capacidade do nível pretendido
ETAPA 02 PASSO 2: EXECUÇÃO IDEMPOTENTE
Upgrade Intermédio / Troca de Ciclo
Desbloqueio imediato capacidade
Valida expectedAmountDueToday para evitar variação de preço
Downgrade de Nível
Agendado para currentPeriodEnd
Revogável via `/scheduled-change
/cancel` antes da renovação
POST/api/v1/billing/subscription/change (request payload)
ETAPA 03 PASSO 3: CANCELAMENTO NO FIM DO PERÍODO E RETOMA
POST/api/v1/billing/subscription/cancel (CANCEL_AT_PERIOD_END / Cancel)
POST/api/v1/billing/subscription/resume (Restaura renovação automática)

Importante: Só é possível efetuar downgrade para um nível inferior se a contagem atual de activePasses do 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, /preview e /change devolvem um bloqueio estruturado de capacidade indicando quantos cartões ativos devem ser reduzidos primeiro.

Endpoints de Transição de Subscrição (Billing API)

EndpointVerbo HTTPComportamento Operacional
/api/v1/billing/subscription/previewPOSTAvalia request payload ({ planId, promotionCode? }) e calcula o prorrateio exato, impostos e elegibilidade sem alterar estado.
/api/v1/billing/subscription/changePOSTExecuta request payload ({ planId, idempotencyKey, promotionCode?, paymentMethodId?, expectedAmountDueToday?, intent? }).
/api/v1/billing/subscription/scheduled-change/cancelPOSTRevoga um downgrade pendente para o fim do período, mantendo o espaço no nível atual.
/api/v1/billing/subscription/cancelPOSTAgenda o cancelamento da subscrição no final do período (request payload: { reason?, feedback? }).
/api/v1/billing/subscription/resumePOSTReverte 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):

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 Resposta (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. 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:

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. 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:

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. 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:

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

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.