Pular para o conteúdo principal
Um invoice_preview mostra quanto uma alteração de assinatura cobraria antes de você persistir qualquer mudança financeira. Ele calcula créditos, débitos, ajustes pró-rata, saldo aplicado e valor a cobrar, mas não cria invoice, payment intent, charge ou movimentação de saldo. Use previews em telas de upgrade, downgrade, troca de plano, alteração de quantidade de assentos ou adição/remoção de add-ons. O padrão mais seguro é: mostrar a prévia para o usuário, confirmar a decisão e só então chamar o endpoint que realmente altera a assinatura.
invoice_preview não tem id porque não é persistido. Cada chamada é um cálculo pontual feito com o estado atual da subscription e os itens enviados.

Objeto invoice_preview

Este é o formato retornado por POST /v1/invoice-previews.
string
Sempre "invoice_preview".
integer
Valor de saldo credor aplicado ao total, na menor unidade da moeda (centavos em brl). Quando o customer tem saldo negativo em starting_balance, parte desse crédito pode reduzir amount_due.
integer
Soma dos descontos calculados para a prévia, na menor unidade da moeda (centavos em brl).
integer
Valor que seria cobrado agora, na menor unidade da moeda (centavos em brl), depois de aplicar saldo credor. Em downgrade ou crédito líquido, pode ser 0.
integer
Soma dos itens antes de descontos, impostos e saldo aplicado. Pode ser negativo quando a alteração gera crédito líquido.
integer
Impostos calculados para a prévia, na menor unidade da moeda (centavos em brl).
integer
Total da prévia antes de aplicar saldo credor. Em centavos (menor unidade da moeda).
string
Moeda da subscription em ISO 4217 minúsculo, como brl.
string | null
Customer dono da subscription.
integer
Saldo estimado do customer depois da prévia. Um valor negativo representa crédito a favor do customer.
array
Linhas que explicam como a prévia chegou ao total. Em uma troca de plano no meio do ciclo, normalmente há uma linha negativa pelo tempo não usado do plano anterior e uma linha positiva pelo tempo restante do novo plano.
boolean
true em produção; false em ambiente de teste.
integer
Saldo do customer antes da prévia. Valores negativos representam crédito disponível.
string | null
Subscription usada como base do cálculo.

Como ler a prévia

  • Upgrade no meio do ciclo costuma gerar uma linha negativa pelo plano anterior e uma linha positiva pelo novo plano. O valor líquido aparece em amount_due.
  • Downgrade pode gerar amount_total negativo. Nesse caso, amount_due fica 0 e o crédito aparece em ending_balance.
  • Saldo credor existente reduz o que seria cobrado: compare starting_balance, amount_credit_balance_applied, amount_due e ending_balance.
  • Sem pró-rata (proration_behavior: "none") a prévia tende a refletir apenas o efeito futuro da troca, sem linhas proporcionais imediatas.

Próximos passos

Depois de mostrar e confirmar a prévia, aplique a mudança usando o endpoint de update da assinatura ou de itens de assinatura. A prévia não reserva preço, saldo ou estado: se a assinatura mudar entre a preview e o update, gere uma nova preview antes de confirmar.