Prévias de fatura
Criar uma prévia de fatura
Pré-visualiza a invoice de uma alteração de assinatura.
curl -X POST "https://api.chargefy.io/v1/invoice-previews" \
-H "Authorization: Bearer {{API_KEY}}" \
-H "Content-Type: application/json" \
-d '{
"subscription": "sub_F9kSoc8hWeUSGcMT",
"subscription_details": {
"items": [
{
"id": "si_MAQBiqgWNTcosD2T",
"price": "price_b4sNSEvWcsee5Suj"
}
]
}
}'
{
"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_WcaG6ecGdu5iR7vA",
"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_dKsUQG8EKQStWMYn",
"price_data": null,
"product": "prod_VhhVXiH9HdVFSZHG",
"proration": true,
"proration_details": {
"credited_items": null
},
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"subscription_item": "si_MAQBiqgWNTcosD2T",
"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_b4sNSEvWcsee5Suj",
"price_data": null,
"product": "prod_VhhVXiH9HdVFSZHG",
"proration": true,
"proration_details": {
"credited_items": null
},
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"subscription_item": "si_MAQBiqgWNTcosD2T",
"unit_amount": 10000
}
],
"livemode": true,
"starting_balance": 0,
"subscription": "sub_F9kSoc8hWeUSGcMT"
}
Cria uma preview de invoice para uma alteração de assinatura. Use o mesmo
payload de
items que seria enviado no update da subscription.
Obrigatórios: subscription e subscription_details.items (array
não-vazio). O resto tem padrão — proration_behavior cai em
create_prorations. A prévia é só cálculo: nada muda na assinatura e nenhuma
invoice ou cobrança é criada.
string
required
Subscription que será alterada (
sub_*).array
required
Array não-vazio (máx. 20 entradas) com as alterações nos itens da
assinatura. Use
id para atualizar um item, deleted: true para remover,
ou omita id para adicionar um novo item. Itens da assinatura que não
aparecem no array permanecem como estão.Show items[]
Show items[]
boolean
Quando
true, remove o item na prévia. Exige id (sem id retorna 400).string
ID do item da assinatura (
si_*) a atualizar ou remover. Omita para adicionar um item novo.string
ID de um preço recorrente do catálogo. Exatamente um entre
price e price_data — os dois juntos retorna 400. Item novo (sem id) exige um dos dois; em item existente, ambos podem ser omitidos (ex.: mudar só quantity).object
Preço recorrente ad-hoc definido inline, alternativa a
price. Mutuamente exclusivo com price.integer
default:"1"
Inteiro >= 1. Em item existente sem troca de preço, mantém a quantidade atual quando omitido.
string
default:"create_prorations"
Como o pró-rata da alteração é calculado. Padrão:
create_prorations.| Valor | Descrição |
|---|---|
create_prorations | Calcula ajustes pró-rata do tempo não utilizado e do tempo restante, cobrados na próxima invoice. |
always_invoice | Calcula os ajustes pró-rata e os cobra imediatamente em uma nova invoice. |
none | Não calcula pró-rata para a alteração. |
string
Timestamp ISO 8601 usado para calcular a parte restante do ciclo. Só válido
quando
proration_behavior é create_prorations ou always_invoice —
combinar com none retorna 400. Quando omitido, a Chargefy usa o momento da
chamada.curl -X POST "https://api.chargefy.io/v1/invoice-previews" \
-H "Authorization: Bearer {{API_KEY}}" \
-H "Content-Type: application/json" \
-d '{
"subscription": "sub_F9kSoc8hWeUSGcMT",
"subscription_details": {
"items": [
{
"id": "si_MAQBiqgWNTcosD2T",
"price": "price_b4sNSEvWcsee5Suj"
}
]
}
}'
{
"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_WcaG6ecGdu5iR7vA",
"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_dKsUQG8EKQStWMYn",
"price_data": null,
"product": "prod_VhhVXiH9HdVFSZHG",
"proration": true,
"proration_details": {
"credited_items": null
},
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"subscription_item": "si_MAQBiqgWNTcosD2T",
"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_b4sNSEvWcsee5Suj",
"price_data": null,
"product": "prod_VhhVXiH9HdVFSZHG",
"proration": true,
"proration_details": {
"credited_items": null
},
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"subscription_item": "si_MAQBiqgWNTcosD2T",
"unit_amount": 10000
}
],
"livemode": true,
"starting_balance": 0,
"subscription": "sub_F9kSoc8hWeUSGcMT"
}
⌘I
curl -X POST "https://api.chargefy.io/v1/invoice-previews" \
-H "Authorization: Bearer {{API_KEY}}" \
-H "Content-Type: application/json" \
-d '{
"subscription": "sub_F9kSoc8hWeUSGcMT",
"subscription_details": {
"items": [
{
"id": "si_MAQBiqgWNTcosD2T",
"price": "price_b4sNSEvWcsee5Suj"
}
]
}
}'
{
"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_WcaG6ecGdu5iR7vA",
"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_dKsUQG8EKQStWMYn",
"price_data": null,
"product": "prod_VhhVXiH9HdVFSZHG",
"proration": true,
"proration_details": {
"credited_items": null
},
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"subscription_item": "si_MAQBiqgWNTcosD2T",
"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_b4sNSEvWcsee5Suj",
"price_data": null,
"product": "prod_VhhVXiH9HdVFSZHG",
"proration": true,
"proration_details": {
"credited_items": null
},
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"subscription_item": "si_MAQBiqgWNTcosD2T",
"unit_amount": 10000
}
],
"livemode": true,
"starting_balance": 0,
"subscription": "sub_F9kSoc8hWeUSGcMT"
}