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.
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 deprice, 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
Assinaturas
Como a proration se encaixa no ciclo de vida da assinatura.
Trial
O período gratuito antes do cliente começar a pagar.
Prévia de fatura (API)
O contrato técnico para simular o ajuste antes de aplicar.