Skip to main content

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.

Recorrência nativaNa Chargefy, assinaturas são gerenciadas pelo sistema de recorrência nativo da plataforma. Ao criar um produto com preço recorrente e um cliente confirmar o checkout com cartão de crédito, a Chargefy automaticamente configura o plano de recorrência.

​
Visão Geral

Uma assinatura na Chargefy representa uma relação contínua de cobrança entre um cliente e um produto. Diferente de pagamentos únicos, assinaturas cobram automaticamente o cliente em intervalos regulares.

​
Frequências suportadas

O preço carrega interval + interval_count:
Frequênciaintervalinterval_countExemplo
Diáriaday1R$ 1,99/dia
Semanalweek1R$ 19,90/semana
Quinzenalweek2R$ 34,90 a cada 2 semanas
Mensalmonth1R$ 49,90/mês
Trimestralmonth3R$ 129,90 a cada 3 meses
Semestralmonth6R$ 239,90 a cada 6 meses
Anualyear1R$ 399,90/ano
Assinaturas são cobradas exclusivamente via cartão de crédito. PIX e Boleto não suportam cobranças recorrentes automáticas. interval_count > 1 está no schema mas hoje só 1 é honrado na cobrança (roadmap).

​
Quantidade na assinatura

Cada linha de assinatura (subscription_product_prices) carrega um campo quantity (default 1). O total cobrado por ciclo é unit_amount × quantity. Use pra cobrar por assento, por licença, ou por unidade. Ver Precificação por Quantidade. 
// Upgrade de 5 pra 10 assentos
await chargefy.subscriptions.update(subscriptionId, {
  quantity: 10,
})
// Próxima cobrança: unit_amount * 10

​
Como funciona

​
Criação de assinatura

1

Produto recorrente

Crie um produto com ciclo de cobrança recorrente (mensal, anual, semanal ou diário) no dashboard ou via API.
2

Checkout

O cliente acessa o checkout (via link, embed ou API) e seleciona cartão de crédito como método de pagamento.
3

Primeira cobrança

Ao confirmar o checkout, a Chargefy processa a primeira cobrança e cria um plano de recorrência automaticamente.
4

Cobranças automáticas

A Chargefy cobra automaticamente o cartão do cliente no intervalo definido, atualizando o status a cada cobrança.

​
Fluxo técnico

Cliente confirma checkout
    ↓
Chargefy processa a primeira cobrança
    ↓
Chargefy cria plano de recorrência
    ↓
Cobranças automáticas no ciclo definido
    ↓
Chargefy atualiza status e dispara eventos

​
Ciclo de vida da assinatura

Criada → Ativa → Suspensa → Cancelada
           ↑        ↓
           └── Reativada

​
Status

StatusDescrição
activeAssinatura ativa, cobranças em dia
trialingEm período trial, sem cobrança
suspendedTemporariamente suspensa (ex: falha de pagamento)
canceledCancelada pelo cliente ou administrador
revokedRevogada pelo administrador

​
Gerenciamento

​
Suspender assinatura

Pausa temporariamente as cobranças sem cancelar a assinatura. O cliente perde acesso aos benefícios durante a suspensão. 
await chargefy.subscriptions.update(subscriptionId, {
  status: "suspended",
});

​
Reativar assinatura

Retoma as cobranças de uma assinatura suspensa. O cliente recupera acesso aos benefícios. 
await chargefy.subscriptions.update(subscriptionId, {
  status: "active",
});

​
Cancelar assinatura

Cancela permanentemente a assinatura. O cliente mantém acesso até o final do período já pago. 
await chargefy.subscriptions.cancel(subscriptionId, {
  cancel_at_period_end: true, // Cancela no final do período atual
});
Com cancel_at_period_end: true, o cliente mantém acesso até a data de renovação. Com false, o cancelamento é imediato.

​
Alterar plano (Upgrade/Downgrade)

Você pode trocar o preço de uma assinatura pra um upgrade ou downgrade. A Chargefy calcula o prorate automaticamente. 
await chargefy.subscriptions.update(subscriptionId, {
  product_price_id: "price_new_plan",
});
Ou ajustar a quantity sem trocar de preço (mesmo plano, mais/menos assentos): 
await chargefy.subscriptions.update(subscriptionId, {
  quantity: 8, // era 5
})
Saiba mais nos guias de Upgrade e Downgrade.

​
Período Trial

Assinaturas podem ter um período trial onde o cliente não é cobrado. Ao final do trial, a primeira cobrança é processada automaticamente.
  • O trial é configurado no produto (ex: 7 dias, 14 dias, 1 mês)
  • O cliente precisa fornecer dados do cartão no checkout
  • Se o cliente cancelar durante o trial, não há cobrança
Saiba mais em Trials.

​
Faturamento automático

A cada ciclo de cobrança, a Chargefy automaticamente:
  1. Processa a cobrança no cartão
  2. Cria um registro de transação
  3. Dispara webhooks (subscription.updated)
  4. Atualiza o acesso do cliente aos benefícios
Em caso de falha na cobrança, a Chargefy tenta novamente automaticamente conforme configuração de retry.

​
Webhook events

EventoQuando
subscription.createdAssinatura criada
subscription.activeAssinatura ativada (após primeiro pagamento ou trial)
subscription.updatedQualquer atualização na assinatura
subscription.canceledAssinatura cancelada
subscription.uncanceledCancelamento revertido
subscription.revokedAssinatura revogada pelo administrador

​
Particularidades das assinaturas na Chargefy

AspectoComportamento
RecorrênciaSistema próprio da Chargefy
Métodos de pagamentoApenas Cartão de Crédito
MoedaBRL (Real brasileiro)
InvoicesGeração automática
ProrationAutomático
TrialsSuportado
Parcelamento na recorrênciaNão suportado (apenas pagamento único)
Migrando de outra plataforma? Veja Migrar para Chargefy.