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.
Objeto invoice_preview
Este é o formato retornado porPOST /v1/invoice-previews.
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.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.Soma dos itens antes de descontos, impostos e saldo aplicado. Pode ser
negativo quando a alteração gera crédito líquido.
Saldo estimado do customer depois da prévia. Um valor negativo representa
crédito a favor do customer.
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.
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_totalnegativo. Nesse caso,amount_duefica0e o crédito aparece emending_balance. - Saldo credor existente reduz o que seria cobrado: compare
starting_balance,amount_credit_balance_applied,amount_dueeending_balance. - Sem pró-rata (
proration_behavior: "none") a prévia tende a refletir apenas o efeito futuro da troca, sem linhas proporcionais imediatas.

