subscription representa o acordo recorrente entre você e um customer.
Ela não é só uma cobrança repetida: é a máquina de estado que decide o que
será cobrado, quando será cobrado, como o cliente paga, o que acontece durante
trial, como updates geram pró-rata e quando a assinatura deve pausar, recuperar
ou cancelar.
Use subscriptions quando existe uma relação contínua: SaaS mensal, plano anual,
clube de assinatura, contrato com add-ons, assentos por usuário, cobrança por
consumo ou migração de assinaturas já ativas de outro sistema. Para uma compra
avulsa, prefira checkout sessions,
payment links ou
payment intents.
A subscription é a fonte de verdade para acesso e cobrança recorrente. Os
campos status, current_period_start, current_period_end,
next_billing_at, trial_end, default_payment_method, latest_invoice e
items.data[] dizem se o cliente pode usar o produto agora, quando será a
próxima tentativa de cobrança e qual valor compõe o ciclo.
Como ela nasce
No create,
payment_behavior define a falha da primeira cobrança:
allow_incomplete mantém a subscription incomplete para recuperação,
default_incomplete não tenta cobrar imediatamente e error_if_incomplete
retorna 402 sem criar o recurso público. Esse campo não aparece no objeto
retornado porque controla apenas a execução do request.
Cartão, setup intent e tokenização
default_payment_method aponta para um pm_* já salvo. Ele é usado nas
cobranças automáticas da primeira invoice, das renovações e de invoices de
update quando houver valor a cobrar.
Quando uma subscription em trial é criada sem cartão, pending_setup_intent
aponta para um seti_*. Esse setup intent existe para coletar um método de
pagamento reutilizável sem criar uma cobrança naquele momento. Ao confirmar o
setup intent no fluxo seguro, o cartão tokenizado vira o
default_payment_method da subscription e pending_setup_intent volta para
null.
O seu backend nunca precisa guardar dados brutos do cartão. Trabalhe com
setup intents,
payment methods e os IDs públicos
retornados pela Chargefy.
Pró-rata e mudanças de plano
Quando você alteraitems, troca price, muda quantity, adiciona um add-on
ou remove um item, a assinatura pode precisar ajustar o valor proporcional do
ciclo atual. Esse ajuste é o pró-rata.
Antes de aplicar a mudança, use
Invoice Previews para mostrar ao
cliente o impacto: crédito por tempo não usado, débito pelo novo plano, saldo
aplicado e valor que será cobrado agora ou na próxima invoice. Depois, no
update da subscription, proration_behavior e payment_behavior definem se a
alteração aplica imediatamente, gera invoice agora, fica em pending_update ou
é recusada se não puder cobrar.
Objeto subscription
Este é o formato completo retornado emcreate, get, update, delete,
itens de list e em data.object dos webhooks subscription.*.
Condições de comissão de afiliado registradas: cada item contém
affiliation e
affiliate_fee_rate em pontos-base; [] indica ausência de comissão de afiliado.
Esta seleção não comprova recebimento: o pagamento registra o resultado de
cada participante. Encerrar uma parceria retira sua participação nas
próximas cobranças e preserva os valores e as parcelas já divididos.Data que ancora os ciclos de cobrança em ISO 8601. Todo período é contado a
partir dela: âncora no dia 19 renova ciclos mensais todo dia 19. Âncora no
dia 31 renova no último dia dos meses mais curtos e volta ao dia 31 nos meses
que o têm (31/01, 28/02, 31/03, 30/04). Com período grátis, a âncora é o fim
do período grátis. Definida na criação (ou na importação) e redefinida quando
você reinicia o ciclo com
billing_cycle_anchor: "now" no update ou no
resume.Data em que a subscription termina, em ISO 8601. Vem
null quando não há
término definido.É um campo declarável: envie cancel_at no create ou no update para vender
com prazo — um plano anual entregue como um ano, um contrato com vigência.
Na data, a subscription encerra sozinha, sem nenhuma ação posterior.Também vem preenchida quando o término foi declarado por
cancel_at_period_end, caso em que reflete o fim do período atual. Os dois
caminhos escrevem esta mesma data; o que muda é como o término foi expresso.Término no meio de um período já pago credita o tempo não usado no saldo do
cliente, conforme proration_behavior. Término no fim do período não gera
crédito — não sobrou tempo a devolver.true quando a subscription está marcada para encerrar no fim do período
atual; false caso contrário.Data em que o cancelamento foi solicitado ou concluído em ISO 8601. Vem
null
enquanto a subscription não foi cancelada.Prazo declarado por cancel_at não preenche este campo: uma subscription que
termina na data combinada cumpriu o contrato, não foi cancelada.Forma de cobrança.
charge_automatically (padrão): cada ciclo é cobrado
automaticamente no método de pagamento padrão. send_invoice: a cada ciclo a
Chargefy envia um link de pagamento e a fatura é cobrada manualmente — não há
cartão arquivado. Nasce assim a assinatura paga com Pix ou boleto no
checkout, e também a paga com um cartão de uso único ou não suportado para
cobranças futuras (single_use_card): a primeira cobrança sai no cartão,
nada fica salvo e as renovações chegam por fatura. Quando um cartão é
definido como padrão, a assinatura passa automaticamente para
charge_automatically.Fim do período de cobrança atual em ISO 8601. É também quando a próxima
renovação ocorre. O primeiro período começa quando a subscription é criada e
não muda quando o primeiro pagamento é confirmado depois.
Número de dias até o vencimento das faturas criadas com
collection_method: "send_invoice". Vem null quando não foi definido.Payment method usado nas cobranças automáticas (
pm_*). Vem null quando
nenhum método padrão foi definido.Data em que a subscription chegou a um estado final. Vem
null enquanto a
assinatura ainda pode renovar ou ser recuperada.Momento da próxima cobrança de ciclo em ISO 8601. Acompanha
current_period_end: é a data da renovação, e avança junto com o período a
cada ciclo cobrado.Número legível da assinatura, formado pelo prefixo de faturas do cliente e
uma sequência própria de assinaturas (ex:
SUB-K7M2-001). Serve para identificar a assinatura no atendimento e na
contabilidade, sem depender do id. Sempre presente: é atribuído na criação
e não muda em troca de plano, pausa, retomada ou cancelamento. A sequência
começa em 001 para cada cliente, é independente das faturas e cresce além
de três dígitos quando necessário (999, 1000). Clientes de teste e
produção têm registros e contadores separados.Configuração para pausar a cobrança de faturas mantendo a subscription no
status atual. Vem
null quando a cobrança não está pausada.Durante a pausa o ciclo continua avançando e a invoice de cada ciclo continua
sendo criada — o que muda é apenas o destino dessa invoice, definido por
behavior.Condição de parcelamento contratada na venda e aplicada às próximas faturas
de cartão.
payment_method_options vem null quando a assinatura é cobrada
à vista.Setup intent pendente para coletar ou confirmar método de pagamento
reutilizável. Em trials criados sem
default_payment_method, a Chargefy cria
esse setup intent automaticamente; ao confirmá-lo, o método salvo vira o
default_payment_method da subscription e este campo volta para null.Atualização pendente criada por um update com
payment_behavior: "pending_if_incomplete". A alteração fica retida até a
invoice de update ser paga; se não for paga até expires_at, a atualização
é descartada e o campo volta para null, sem mudar a assinatura.Data da última retomada de uma subscription pausada. Vem
null quando nunca
foi retomada.Subscription schedule
(
subsched_*) que controla mudanças programadas de fase desta assinatura. Vem
null quando a assinatura não é gerenciada por uma schedule.Índice da fase atual dentro da schedule associada, começando em
0. Vem
null quando não há schedule.Instante em que a subscription foi criada e o primeiro período começou. A
data não muda quando o primeiro pagamento é confirmado depois: um boleto
emitido no dia 1 e pago no dia 5 renova no dia 1.
Fim do período de trial em ISO 8601 para subscriptions iniciadas em trial. Vem
null em subscriptions sem trial.Data da última atualização em ISO 8601. Vem
null enquanto a subscription
nunca foi atualizada.Como ler na prática
Cenários comuns
Trial com cartão a coletar
Uma subscription em trial pode começar sem cartão. Nesse caso, ela ficatrialing, aponta para um pending_setup_intent e só deve cobrar no fim do
trial. Seu produto pode liberar acesso durante o trial e, em paralelo, pedir ao
cliente para salvar o cartão antes de trial_end.
trial_settings.end_behavior.missing_payment_method for pause, a
subscription entra em paused quando o trial termina sem cartão. Se for
create_invoice, a primeira invoice é criada mesmo sem método automático. Se
for cancel, a assinatura termina no fim do trial.
Upgrade com pró-rata
Ao trocar de plano no meio do ciclo, a Chargefy pode calcular o crédito do plano antigo e o débito do novo plano. Useinvoice_preview antes de aplicar a troca.
Se o update usar payment_behavior: "pending_if_incomplete", a mudança fica em
pending_update até a invoice de update ser paga.
pending_update.subscription_items descrevem o alvo da
atualização e carregam apenas id, metadata, price, price_data e
quantity — os itens em items.data[] continuam mostrando o estado atual até
a invoice ser paga.
Quando a invoice é paga, a alteração é aplicada e o webhook
subscription.pending.update.applied é emitido. Se expirar sem pagamento, a
alteração é descartada e chega subscription.pending.update.expired.
Uso medido
Itensmetered cobram pelo consumo registrado no período. A subscription mostra
a janela atual de apuração no item; o consumo em si é enviado por
usage records.
aggregate_usage e gera a linha correspondente na invoice.
Cancelamento no fim do período
Quando o cliente deve manter acesso até o fim do ciclo atual, não cancele imediatamente. Usecancel_at_period_end: true. A subscription continua
active, mas cancel_at mostra a data de corte.
DELETE /v1/subscriptions/{id}. A assinatura vira
canceled, para de renovar e emite subscription.canceled.
Pausa de cobrança
pause_collection não é a mesma coisa que status: "paused". Pausar cobrança
mantém o ciclo avançando e decide o que fazer com as invoices criadas durante a
pausa. Já status: "paused" acontece quando um trial termina sem payment method
e a política de fim de trial manda pausar a assinatura.
Como processar no seu sistema
- Use
subscription.created,subscription.updated,subscription.canceled,subscription.pausedesubscription.resumedpara atualizar acesso e estado local. - Use eventos de invoice e payment intent para fulfillment financeiro. A subscription diz o contrato e o lifecycle; a invoice diz o que foi cobrado; o payment intent diz se a tentativa de pagamento teve sucesso, falhou ou exige ação.
- Para liberar acesso, prefira uma regra explícita por status.
trialingeactivenormalmente liberam acesso;past_dueeunpaiddependem da sua política de produto;canceledeincomplete_expiredsão terminais. - Para mudanças de plano, gere uma invoice preview, mostre o valor ao cliente e só depois aplique o update.
- Para trial sem cartão, acompanhe
pending_setup_intente colete o método reutilizável antes detrial_end.
Operações
- Listar subscriptions
- Criar subscription
- Consultar subscription
- Atualizar subscription
- Cancelar subscription imediatamente
Eventos
Mudanças nesse objeto disparam os seguintes eventos:subscription.createdsubscription.updatedsubscription.canceledsubscription.pausedsubscription.resumedsubscription.trial.will.endsubscription.pending.update.appliedsubscription.pending.update.expired
subscription completo em data.object; eventos de update também incluem data.previous_attributes com os valores anteriores dos campos alterados.
