Prévias de fatura

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.

{
  "object": "invoice_preview",
  "amount_credit_balance_applied": 0,
  "amount_discount": 0,
  "amount_due": 5000,
  "amount_subtotal": 5000,
  "amount_tax": 0,
  "amount_total": 5000,
  "currency": "brl",
  "customer": "cus_qFDVGoDtUBqBaV3N",
  "ending_balance": 0,
  "line_items": [
    {
      "object": "invoice_preview_line_item",
      "amount_discount": 0,
      "amount_subtotal": -5000,
      "amount_tax": 0,
      "amount_total": -5000,
      "currency": "brl",
      "description": "Unused time on previous price",
      "discountable": false,
      "metadata": {},
      "period_end": "2026-06-01T00:00:00Z",
      "period_start": "2026-05-16T00:00:00Z",
      "price": "price_SBSNzHK2AE4M3o3X",
      "price_data": null,
      "product": "prod_gW7uwSfe6E9Qs5Lx",
      "proration": true,
      "proration_details": {
        "credited_items": null
      },
      "quantity": 1,
      "recurring_interval": "month",
      "recurring_interval_count": 1,
      "subscription_item": "si_QbP7F4262GefE5Y4",
      "unit_amount": -5000
    },
    {
      "object": "invoice_preview_line_item",
      "amount_discount": 0,
      "amount_subtotal": 10000,
      "amount_tax": 0,
      "amount_total": 10000,
      "currency": "brl",
      "description": "Remaining time on new price",
      "discountable": false,
      "metadata": {},
      "period_end": "2026-06-01T00:00:00Z",
      "period_start": "2026-05-16T00:00:00Z",
      "price": "price_9wtYA3Q9VQMRH77Z",
      "price_data": null,
      "product": "prod_gW7uwSfe6E9Qs5Lx",
      "proration": true,
      "proration_details": {
        "credited_items": null
      },
      "quantity": 1,
      "recurring_interval": "month",
      "recurring_interval_count": 1,
      "subscription_item": "si_QbP7F4262GefE5Y4",
      "unit_amount": 10000
    }
  ],
  "livemode": true,
  "starting_balance": 0,
  "subscription": "sub_VzZyRmJYQWv7NwuA"
}

string

Sempre "invoice_preview".

integer

Valor de saldo credor aplicado ao total, em centavos. 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, em centavos.

integer

Valor que seria cobrado agora, em centavos, 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, em centavos.

integer

Total da prévia antes de aplicar saldo credor. Em centavos.

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.

Show Campos de line_items[]

string

Sempre "invoice_preview_line_item".

integer

Desconto aplicado à linha, em centavos.

integer

Subtotal da linha antes de desconto e imposto.

integer

Imposto da linha, em centavos.

integer

Total da linha, em centavos.

string

Moeda da linha.

string | null

Descrição calculada para exibir ao usuário ou registrar em logs.

boolean

Se a linha aceita desconto.

object

Metadata associada à linha. Quando vazia, retorna {}.

string | null

Início do período representado pela linha.

string | null

Fim do período representado pela linha.

string | null

Price de catálogo usado na linha, quando houver.

object | null

Preço inline usado na linha, quando não há price de catálogo.

string | null

Produto associado à linha.

boolean

true quando a linha é ajuste proporcional de ciclo.

object

Detalhes do pró-rata. Quando não há detalhe adicional, retorna {} ou campos nulos.

integer

Quantidade considerada na linha.

string | null

Intervalo recorrente da linha, como month.

integer | null

Quantidade de intervalos por ciclo.

string | null

Item da subscription relacionado à linha, quando houver.

integer

Valor unitário da linha, em centavos. Pode ser negativo em créditos.

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.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Prévias de fatura

Objeto invoice_preview

Como ler a prévia

Próximos passos

​Objeto invoice_preview

​Como ler a prévia

​Próximos passos

Objeto invoice_preview

Como ler a prévia

Próximos passos