> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Proration de assinaturas
> Deixe o cliente mudar de plano no meio do ciclo e cobre só a diferença justa, sem esperar a próxima renovação.
**Proration** é o que torna a mudança de plano justa. Quando o cliente faz
upgrade ou downgrade no meio de um ciclo já pago, a Chargefy não cobra o plano
novo inteiro nem ignora o que ele já pagou: ela calcula proporcionalmente o tempo
que falta e ajusta só a diferença.
Sem proration, mudar de plano vira uma decisão chata: cobrar duas vezes ou
deixar dinheiro na mesa. Com proration, o cliente muda quando quiser e cada lado
paga exatamente pelo que usou.
## O que você consegue fazer
| Possibilidade | O que isso te dá |
| --------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Upgrade na hora** | O cliente sobe de plano e passa a usar o plano novo imediatamente, pagando só a diferença do tempo restante. |
| **Downgrade com crédito** | O cliente desce de plano e o valor não usado vira crédito para as próximas faturas. |
| **Prévia antes de aplicar** | Mostre ao cliente exatamente quanto ele vai pagar (ou receber de crédito) antes de confirmar a mudança. |
| **Crédito que se acumula** | Saldo a favor do cliente entra automaticamente nas próximas cobranças, sem você controlar isso na mão. |
## Como o ajuste é justo
A conta é simples de explicar pro cliente: a Chargefy olha quanto falta do ciclo
atual e divide o valor proporcionalmente.
* **O tempo não usado do plano antigo vira crédito.**
* **O tempo restante no plano novo vira cobrança.**
* A diferença entre os dois é o que aparece numa fatura imediata.
**Exemplo de upgrade.** Plano mensal de R$ 100,00, trocado para R$ 200,00 na
metade do ciclo:
```text theme={}
crédito do tempo não usado (R$ 100): -R$ 50,00
cobrança do tempo restante (R$ 200): +R$ 100,00
o cliente paga agora: R$ 50,00
```
**Exemplo de downgrade.** O mesmo cliente desce de R$ 200,00 para R$ 100,00 na
metade do ciclo:
```text theme={}
crédito do tempo não usado (R$ 200): -R$ 100,00
cobrança do tempo restante (R$ 100): +R$ 50,00
crédito a favor do cliente: R$ 50,00
```
## Escolha quando faturar
Por padrão, `proration_behavior: "create_prorations"` cria itens pendentes que
entram na próxima invoice da assinatura. Use `always_invoice` quando a diferença
deve virar invoice imediatamente. Use `none` para aplicar a mudança sem criar
proration.
No upgrade com `always_invoice`, a diferença costuma ser positiva, então a
Chargefy abre uma fatura imediata e cobra o método de pagamento padrão. Se o
cliente já tiver crédito acumulado, ele é usado primeiro para abater o valor. Se
a cobrança da diferença falhar, a assinatura pode entrar em atraso — a mesma
rede de segurança das renovações vale aqui.
Use `payment_behavior: "pending_if_incomplete"` quando o upgrade só deve valer
depois do pagamento dessa fatura imediata. Nesse modo, a Chargefy cria a invoice
e preenche `subscription.pending_update`; os itens novos só entram na
subscription quando a invoice é paga. Se a pending update expirar antes do
pagamento, a invoice é anulada e a assinatura continua no plano anterior.
## Downgrade: gera crédito a favor do cliente
No downgrade, a diferença costuma ser negativa. Em vez de devolver o dinheiro, a
Chargefy registra um **crédito** no saldo do cliente. Esse crédito é aplicado
automaticamente nas próximas faturas da mesma moeda, reduzindo o que ele paga nas
renovações seguintes. Quando o crédito cobre uma fatura inteira, ela é quitada
sem precisar de nova cobrança.
## Mostre antes de cobrar
Você pode **simular** a mudança e ver o resultado exato — total a cobrar, linhas
de crédito e débito, saldo antes e depois — antes de aplicar qualquer coisa.
Isso permite mostrar ao cliente "ao mudar para este plano, você paga R\$ X agora"
e só então confirmar. Sem surpresa na fatura.
## O que esta versão cobre
A proration funciona para mudança de `price`, `price_data`, `quantity`, adição
e remoção de itens. A assinatura continua exigindo itens com a mesma moeda e a
mesma cadência recorrente. Tax ainda não é calculado em subscriptions; linhas de
proration retornam `amount_tax: 0`.
## Mantenha seu sistema em sincronia
Uma mudança de plano com proration dispara eventos para você acompanhar a fatura
e a cobrança do ajuste:
| Evento | Quando dispara |
| ------------------------ | ----------------------------------------- |
| `subscription.updated` | O valor recorrente da assinatura mudou. |
| `invoice.created` | A fatura de ajuste foi criada. |
| `payment.intent.created` | Há diferença positiva a cobrar. |
| `invoice.paid` | A fatura foi paga ou coberta por crédito. |
| `invoice.payment.failed` | A cobrança do ajuste falhou. |
## Próximos passos
Como a proration se encaixa no ciclo de vida da assinatura.
O período gratuito antes do cliente começar a pagar.
O contrato técnico para simular o ajuste antes de aplicar.