> ## 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.
# Editando valor, itens e pro-rata de uma assinatura
> Aprenda a alterar preço, quantidade ou itens de uma assinatura pelo Dashboard e escolha se o ajuste proporcional entra agora, na próxima fatura ou não será cobrado.
Use este guia quando precisar mudar uma assinatura que já existe. Você pode
trocar o preço, mudar a quantidade, adicionar um item, remover um item e decidir
como tratar o **pro-rata** do período atual.
Pro-rata é o ajuste proporcional quando a mudança acontece no meio do ciclo. Em
vez de cobrar o mês inteiro de novo, a Chargefy calcula apenas a parte que ainda
falta até a próxima cobrança.
O painel sempre mostra uma prévia antes de você confirmar. Revise essa prévia
para saber se o cliente será cobrado agora, receberá crédito ou verá o ajuste
na próxima fatura.
## O que você pode editar
No painel **Atualizar assinatura**, você consegue fazer mudanças como:
| Mudança | Exemplo |
| ------------------------ | ------------------------------------------------------------------- |
| Trocar o preço | Cliente saiu do plano Básico e foi para o plano Pro. |
| Alterar quantidade | Cliente tinha 1 licença e passou para 3 licenças. |
| Adicionar item | Cliente contratou um produto extra na mesma assinatura. |
| Remover item | Cliente não quer mais um produto cobrado junto da assinatura. |
| Aplicar ou remover cupom | Cliente ganhou um desconto recorrente ou perdeu um desconto antigo. |
Você não edita o valor de um preço existente. Para cobrar outro valor, escolha
outro preço já cadastrado ou crie um novo preço no produto.
## Antes de começar
Confira estes pontos para evitar erro na hora de salvar:
* O novo preço precisa estar ativo.
* O novo preço precisa ter a mesma moeda e o mesmo ciclo da assinatura atual.
Por exemplo: uma assinatura mensal em BRL só aceita outro preço mensal em BRL.
* A assinatura precisa continuar com pelo menos um item ativo.
* Assinaturas canceladas ou expiradas não aceitam troca de valor, quantidade ou
item.
* Se a assinatura estiver em trial, você pode trocar os itens, mas não há
cobrança proporcional do período atual. O novo valor passa a valer quando o
trial acabar.
## 1. Abra a assinatura
No Dashboard, vá em **Assinaturas**, abra a assinatura que deseja alterar e
clique em **Atualizar assinatura**.
O painel tem duas áreas principais:
| Área | Para que serve |
| -------------------------- | ------------------------------------------------------------------------- |
| **Detalhes da assinatura** | Onde você muda preço, quantidade, cupom, trial e pro-rata. |
| **Prévia** | Onde você confere o valor atual, novo valor, diferença e fatura estimada. |
## 2. Mude o valor recorrente
Na seção **Valor recorrente**, edite os itens da assinatura.
Você verá três números importantes na prévia:
| Campo | O que quer dizer |
| ------------- | -------------------------------------------- |
| **Atual** | Valor que a assinatura cobra hoje por ciclo. |
| **Novo** | Valor que ela cobrará depois da alteração. |
| **Diferença** | Quanto o valor recorrente sobe ou desce. |
Exemplo simples:
```text theme={}
Valor atual: R$ 100,00 por mês
Novo valor: R$ 150,00 por mês
Diferença: +R$ 50,00 por mês
```
Essa diferença de R\$ 50,00 é o novo valor recorrente. Ela vale para os próximos
ciclos completos. O que acontece no ciclo atual depende da opção de pro-rata que
você escolher.
## 3. Escolha o pro-rata
Depois de mudar preço, quantidade ou item, escolha como tratar o período atual.
Você tem três alternativas:
| Opção | O que significa | Quando usar |
| ---------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------- |
| **Lançar na próxima fatura** | A assinatura muda agora, mas o ajuste proporcional entra na próxima fatura. | Quando você não quer cobrar nada imediatamente. |
| **Gerar fatura agora** | A assinatura muda agora e a diferença proporcional vira uma fatura imediata. | Quando o cliente precisa pagar a diferença agora. |
| **Desligar pro-rata** | A assinatura muda, mas não há crédito nem cobrança proporcional do ciclo atual. | Quando você decidiu não compensar o período atual. |
Na maioria dos upgrades, use **Gerar fatura agora** se o cliente terá acesso a
mais produto imediatamente. Em downgrades, muitas operações preferem
**Lançar na próxima fatura** para deixar o crédito aparecer no próximo ciclo.
## Exemplos
### Upgrade no meio do mês
O cliente paga R$ 100,00 por mês e troca para um plano de R$ 200,00 quando ainda
falta metade do ciclo.
```text theme={}
Crédito pelo plano antigo não usado: -R$ 50,00
Cobrança pelo plano novo até o fim do ciclo: +R$ 100,00
Diferença do pro-rata: +R$ 50,00
```
Se você escolher **Gerar fatura agora**, o cliente paga R$ 50,00 agora. A
próxima fatura virá com o novo valor cheio de R$ 200,00.
Se você escolher **Lançar na próxima fatura**, o cliente já muda de plano, mas
esse ajuste de R\$ 50,00 entra junto da próxima fatura.
### Downgrade no meio do mês
O cliente paga R$ 200,00 por mês e troca para um plano de R$ 100,00 quando ainda
falta metade do ciclo.
```text theme={}
Crédito pelo plano antigo não usado: -R$ 100,00
Cobrança pelo plano novo até o fim do ciclo: +R$ 50,00
Diferença do pro-rata: -R$ 50,00
```
Nesse caso, o cliente fica com R\$ 50,00 de crédito. Esse crédito é usado
automaticamente para abater próximas faturas da mesma moeda.
### Aumento de quantidade
O cliente tem 1 licença de R\$ 80,00 por mês e passa para 2 licenças no meio do
ciclo.
```text theme={}
Valor atual: R$ 80,00 por mês
Novo valor: R$ 160,00 por mês
Diferença recorrente: +R$ 80,00 por mês
```
O pro-rata calcula apenas a parte desses R\$ 80,00 referente ao tempo restante do
ciclo atual.
## 4. Escolha como lidar com pagamento
Essa parte só importa quando você escolhe **Gerar fatura agora** e existe valor
a cobrar.
Em **Configurações avançadas**, use **Comportamento de pagamento**:
| Opção | Use quando |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Aplicar agora** | A assinatura deve mudar imediatamente, mesmo que a fatura siga o fluxo normal de cobrança. |
| **Aguardar pagamento** | O upgrade só deve entrar depois que a fatura imediata for paga. |
| **Bloquear se cobrar** | Você não quer criar uma cobrança pendente. Se houver valor a cobrar, a atualização não será aplicada. |
| **Incompleta padrão** | A fatura pode exigir uma ação de pagamento depois. Use apenas se esse fluxo fizer sentido para sua operação. |
Para liberar mais acesso ao cliente, **Aguardar pagamento** costuma ser a opção
mais segura. A assinatura só muda depois que a fatura de atualização for paga.
## 5. Revise a prévia da fatura
Abra a aba **Fatura** para ver o cálculo antes de salvar.
Leia assim:
| Campo | Como interpretar |
| -------------------- | ------------------------------------------------------------- |
| **Ajuste** | Resultado líquido do pro-rata. Pode ser positivo ou negativo. |
| **A cobrar** | Valor que será cobrado se você gerar fatura agora. |
| **Crédito aplicado** | Crédito do cliente usado para abater a fatura. |
| **Saldo final** | Crédito que sobra ou saldo final depois do ajuste. |
Se **Ajuste** for positivo, o cliente deve pagar a diferença. Se for negativo,
o cliente ganha crédito para próximas faturas.
## 6. Salve a alteração
Quando a prévia estiver correta, clique em **Atualizar assinatura**.
O resultado depende da opção escolhida:
| Sua escolha | O que acontece |
| ------------------------------------------- | ---------------------------------------------------------------------- |
| **Lançar na próxima fatura** | A assinatura muda agora e o ajuste entra na próxima fatura. |
| **Gerar fatura agora** | A assinatura muda e uma fatura de atualização é criada agora. |
| **Gerar fatura agora + Aguardar pagamento** | A fatura é criada agora, mas a assinatura só muda depois do pagamento. |
| **Desligar pro-rata** | A assinatura muda sem ajuste proporcional do ciclo atual. |
Se sua equipe técnica acompanha webhooks, os eventos mais comuns são:
| Evento | Para que serve |
| ------------------------ | -------------------------------------------- |
| `subscription.updated` | A assinatura mudou. |
| `invoice.created` | Uma fatura foi criada. |
| `payment.intent.created` | Uma cobrança foi criada para valor positivo. |
| `invoice.paid` | A fatura foi paga ou coberta por crédito. |
| `invoice.payment.failed` | A cobrança da fatura falhou. |
## Mobile
No mobile, o painel aparece empilhado. Comece pelos itens da assinatura, depois
role para revisar a prévia antes de atualizar.
## Problemas comuns
| Situação | O que fazer |
| -------------------------------------------------------- | ------------------------------------------------------------------------------- |
| O preço novo não aparece | Verifique se ele está ativo e se usa a mesma moeda e ciclo da assinatura. |
| A prévia não mostra pro-rata | Confirme se algum item mudou e se o pro-rata está ligado. |
| O valor a cobrar parece menor que a diferença recorrente | Isso é esperado. O valor a cobrar considera só o tempo restante do ciclo atual. |
| **Aguardar pagamento** está desabilitado | Essa opção exige fatura imediata e cobrança automática. |
| O botão **Atualizar assinatura** não habilita | Revise os campos, mantenha pelo menos um item ativo e espere a prévia terminar. |
## Relacionados
Como o cálculo proporcional funciona em assinaturas.
Simule o ajuste antes de aplicar por API.
Contrato técnico para atualizar uma assinatura por API.