A assinatura é o acordo. Cada ciclo é uma cobrança.A assinatura guarda o relacionamento ao longo do tempo: quem é o cliente, o que
ele paga e quando renova. A cada ciclo ela gera automaticamente uma fatura e a
cobrança que move o dinheiro. Você cuida do acordo; a Chargefy cuida das
cobranças.
O que você consegue fazer
| Possibilidade | O que isso te dá |
|---|---|
| Faturamento automático | A cada renovação, a fatura é aberta e o método de pagamento padrão é cobrado sem intervenção. |
| Cadência flexível | Cobre por mês, por trimestre, por ano — qualquer intervalo que faça sentido pro seu negócio. |
| Vários itens na mesma assinatura | Junte planos, add-ons e quantidades numa cobrança só, com um total consolidado por ciclo. |
| Período gratuito (trial) | Comece a assinatura sem cobrar e converta o cliente no fim do trial. |
| Upgrade e downgrade no meio do ciclo | Mude o valor a qualquer momento e a Chargefy ajusta a diferença de forma justa (proration). |
| Cancelamento na hora ou no fim do período | Encerre agora ou deixe o cliente aproveitar até o fim do ciclo já pago. |
| Recuperação de cobranças que falham | Renovação recusada é reprocessada conforme a política, sem perder a assinatura na primeira falha. |
| Crédito do cliente | Saldo a favor do cliente entra automaticamente nas próximas faturas. |
O que você cobra
Toda assinatura tem pelo menos um item — uma linha que é cobrada a cada ciclo. Você monta os itens de dois jeitos, e pode misturar a estratégia conforme a necessidade:- A partir do catálogo — quando você já cadastrou o preço e quer reaproveitar valor, moeda e cadência. Bom pra planos padronizados.
- Valor na hora — quando você quer definir um valor específico para aquele cliente sem precisar criar um preço no catálogo. Bom pra acordos sob medida.
Como a assinatura tem uma única frequência e uma única moeda, todos os itens
compartilham a mesma cadência e a mesma moeda. Pense na assinatura como “uma
fatura recorrente” — tudo que está nela vence junto.
O ciclo de vida, sem você cuidar dele
Uma assinatura nasce, é cobrada, renova e um dia termina. A Chargefy move a assinatura entre esses estados automaticamente — você só reage aos que importam pro seu produto (liberar acesso, avisar o cliente, bloquear).| Estado | O que significa pro seu negócio |
|---|---|
Criando (incomplete) | Acabou de ser criada e está esperando a primeira cobrança fechar. Não libere o acesso ainda. |
Em trial (trialing) | Cliente está no período gratuito. A primeira cobrança só vem no fim do trial. |
Ativa (active) | Cobrança em dia. É aqui que o cliente tem acesso ao que comprou. |
Em atraso (past_due) | Uma renovação falhou. A Chargefy ainda tenta recuperar — você decide se restringe o acesso. |
Não paga (unpaid) | As tentativas automáticas se esgotaram. A Chargefy para de cobrar sozinha, mas as faturas continuam open: você pode trocar o método e cobrar manualmente, e pagar uma fatura reativa a assinatura. |
Pausada (paused) | Trial acabou sem cartão e você escolheu pausar em vez de cobrar. |
Cancelada (canceled) | Encerrada. Para o cliente voltar, é uma nova assinatura. |
A virada para Ativa acontece quando a primeira fatura é efetivamente paga —
e isso é assíncrono. Libere o produto ao receber
subscription.updated com
data.object.status: "active", não no momento em que a assinatura é criada. O caminho completo está em
Subscription incomplete.Cada renovação se cuida sozinha
Quando chega a data da próxima cobrança, a Chargefy abre a fatura do novo ciclo, cobra o método de pagamento padrão e avança o período — tudo automático. Você não precisa agendar nada.- Cobrou → a assinatura segue ativa e o período já avançou.
- Falhou → a assinatura entra em atraso e a cobrança fica disponível para nova tentativa, conforme a política de recuperação.
Trial: ganhe o cliente antes de cobrar
Você pode começar a assinatura com um período gratuito. O cliente entra agora e a primeira cobrança só dispara quando o trial termina. Dá pra coletar o cartão durante o período gratuito (cobrança automática no fim) ou deixar o cliente começar sem cartão e decidir o que acontecer depois.Conheça o trial
Período gratuito por dias ou data fixa, coleta de cartão durante o trial e o
que fazer quando ele termina: cobrar, pausar ou cancelar.
Mudar de plano no meio do ciclo
O cliente quer fazer upgrade hoje, faltando 15 dias pra renovar? A Chargefy calcula o ajuste proporcional automaticamente: cobra só a diferença do tempo que falta no plano novo e credita o tempo não usado do plano antigo. Downgrade gera crédito a favor do cliente para as próximas faturas. Você ainda pode simular o resultado antes de aplicar.Conheça a proration
Upgrade, downgrade, crédito proporcional e prévia do ajuste antes de gravar.
Encerrar uma assinatura
Cancelar não é uma coisa só — depende da intenção:| Intenção | O que acontece |
|---|---|
| Cancelar agora | A assinatura encerra na hora e as renovações futuras são desmarcadas. |
| Cancelar no fim do período | O cliente continua com acesso até o fim do ciclo que já pagou, e a assinatura encerra sozinha na virada. |
| Voltar atrás | Enquanto o corte não chegou, dá pra desfazer o cancelamento agendado. |
Mantenha seu sistema em sincronia
Em vez de ficar consultando a API, você reage a eventos. A cada mudança relevante a Chargefy dispara um webhook — esse é o jeito confiável de liberar acesso, avisar o cliente e atualizar seu sistema no momento certo.| Evento | Quando dispara |
|---|---|
subscription.created | A assinatura foi criada. |
subscription.updated | Algum campo mudou. |
subscription.canceled | A assinatura foi encerrada. |
subscription.paused | A assinatura entrou em pausa. |
subscription.resumed | A assinatura voltou da pausa. |
subscription.trial.will.end | O trial está perto de terminar — bom momento para lembrar o cliente. |
subscription.pending.update.applied | Uma pending update foi aplicada. |
subscription.pending.update.expired | Uma pending update expirou antes de ser aplicada. |
Próximos passos
Trial
Período gratuito, coleta de cartão e o que fazer no fim do trial.
Proration
Upgrades, downgrades e crédito proporcional no meio do ciclo.
Subscription incomplete
Como a assinatura sai de “criando” para “ativa” e o que fazer se a primeira
cobrança não fechar.
Preços
Como modelar valor, moeda e recorrência dos itens da assinatura.
Clientes
O cliente dono da assinatura e seus métodos de pagamento.
Objeto subscription (API)
O contrato técnico completo: todos os campos, status e respostas.

