Pular para o conteúdo principal
Uma 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ê altera items, 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 em create, get, update, delete, itens de list e em data.object dos webhooks subscription.*.
array
obrigatório
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.
string
Identificador da subscription. Usa o prefixo sub_*.
string
Sempre "subscription".
string
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.
string | null
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.
boolean
true quando a subscription está marcada para encerrar no fim do período atual; false caso contrário.
string | null
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.
object
Contexto do cancelamento. Os campos vêm null quando não há cancelamento.
string
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.
string
Data de criação em ISO 8601.
string
Moeda da subscription em código ISO de 3 letras minúsculas, como brl.
string
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.
string
Início do período de cobrança atual em ISO 8601.
string
ID do customer dono da subscription (cus_*).
integer | null
Número de dias até o vencimento das faturas criadas com collection_method: "send_invoice". Vem null quando não foi definido.
string | null
Payment method usado nas cobranças automáticas (pm_*). Vem null quando nenhum método padrão foi definido.
string | null
Desconto aplicado à subscription nas invoices recorrentes.
string | null
Data em que a subscription chegou a um estado final. Vem null enquanto a assinatura ainda pode renovar ou ser recuperada.
object
Lista dos itens recorrentes da subscription, no formato de lista padrão.
string | null
Invoice mais recente da subscription. Vem null antes da primeira invoice.
boolean
true em produção; false em ambiente de teste.
object
Objeto livre para correlacionar a subscription com o seu sistema. Quando vazio, retorna {}.
string
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.
string
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.
object | null
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.
object
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.
string | null
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.
object | 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.
string | null
Data da última retomada de uma subscription pausada. Vem null quando nunca foi retomada.
string | null
Subscription schedule (subsched_*) que controla mudanças programadas de fase desta assinatura. Vem null quando a assinatura não é gerenciada por uma schedule.
integer | null
Índice da fase atual dentro da schedule associada, começando em 0. Vem null quando não há schedule.
string
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.
string
Estado atual da subscription.
string | null
Fim do período de trial em ISO 8601 para subscriptions iniciadas em trial. Vem null em subscriptions sem trial.
object
Política aplicada quando o trial termina.
string | null
Início do trial em ISO 8601. Vem null em subscriptions sem trial.
string | null
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 fica trialing, 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.
Se 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. Use invoice_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.
Os itens dentro de 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

Itens metered 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.
No fechamento do ciclo, a Chargefy agrega os usage records conforme 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. Use cancel_at_period_end: true. A subscription continua active, mas cancel_at mostra a data de corte.
Para cancelar agora, use 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

  1. Use subscription.created, subscription.updated, subscription.canceled, subscription.paused e subscription.resumed para atualizar acesso e estado local.
  2. 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.
  3. Para liberar acesso, prefira uma regra explícita por status. trialing e active normalmente liberam acesso; past_due e unpaid dependem da sua política de produto; canceled e incomplete_expired são terminais.
  4. Para mudanças de plano, gere uma invoice preview, mostre o valor ao cliente e só depois aplique o update.
  5. Para trial sem cartão, acompanhe pending_setup_intent e colete o método reutilizável antes de trial_end.

Operações

Eventos

Mudanças nesse objeto disparam os seguintes eventos: O payload sempre carrega o objeto subscription completo em data.object; eventos de update também incluem data.previous_attributes com os valores anteriores dos campos alterados.