Skip to main content
Quando você cria uma subscription sem trial pela API, ela não nasce ativa. Ela nasce incomplete: o acordo de cobrança recorrente existe, mas o relógio do faturamento só começa a contar depois que a primeira cobrança for paga. Esse estado é a porta de entrada de toda assinatura paga — é nele que a primeira fatura é aberta e o pagamento inicial é confirmado.
incomplete é transitório, não um erro.Ele significa “a assinatura foi registrada, mas ainda estou aguardando o primeiro pagamento”. Não libere o produto ou o acesso enquanto a subscription estiver incomplete — espere subscription.updated com data.object.status: "active".

​
O que a Chargefy cria junto

No mesmo POST /v1/subscriptions, três objetos nascem em cadeia. A subscription é só a ponta visível:
ObjetoEstado inicialPapel
subscriptionincompleteO acordo recorrente. Guarda items, currency, trial_* e o default_payment_method; a cadência vem de items.data[].recurring.
invoiceopenA primeira fatura (billing_reason: "subscription_create"), já criada com o valor total do primeiro ciclo.
payment_intentrequires_confirmation ou requires_payment_methodA cobrança que move o dinheiro da primeira fatura. Veja Payment Intents.
O payment_intent nasce em requires_confirmation quando você passou default_payment_method na criação — nesse caso a Chargefy já enfileira a tentativa de cobrança automaticamente. Sem método padrão, ele nasce em requires_payment_method e fica aguardando você definir o meio de pagamento e confirmar.

​
Ciclo de vida do incomplete

A partir de incomplete, só existem dois desfechos para o primeiro ciclo: a cobrança fecha e a subscription vira active, ou ela expira por inação.
StatusQuando ocorreÉ terminal?
incompleteSubscription criada sem trial; aguardando a primeira cobrança.Não
trialingSubscription criada com trial_period_days; a primeira cobrança só ocorre no fim do trial.Não
activeA primeira cobrança (ou a do fim do trial) foi paga. Faturamento recorrente em dia.Não
incomplete_expiredA primeira cobrança não fechou dentro de 23 horas.Sim
past_dueUma cobrança recorrente falhou ou uma invoice de fim de trial foi criada sem método de pagamento.Não
unpaidA cobrança foi marcada como não recuperável após política de cobrança/retry.Não
canceledA subscription foi cancelada.Sim
pausedTrial terminou sem método de pagamento e a política escolhida foi pausar a subscription.Não
incomplete_expired é terminal. Uma subscription que expirou não volta para incomplete nem active — para o cliente voltar a assinar, crie uma subscription nova.

​
Da criação até active

1

Crie a subscription com um método de pagamento padrão

Passe default_payment_method no create. A subscription nasce incomplete, a primeira fatura abre e a Chargefy enfileira a cobrança automaticamente no método informado.
curl https://api.chargefy.io/v1/subscriptions \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_456",
    "default_payment_method": "pm_789",
    "items": [{ "price": "price_123" }]
  }'
A resposta já volta com status: "incomplete" — o pagamento ainda não fechou de forma síncrona.
2

Aguarde a confirmação da primeira cobrança

Cartão costuma resolver na hora; PIX e boleto ficam pendentes até a confirmação assíncrona chegar. Acompanhe o desfecho da cobrança pelos eventos do payment_intent, não pela resposta do create.
3

Reaja ao subscription.updated

Quando a primeira fatura é paga, ela vira paid, o payment_intent vira succeeded e a subscription transiciona incomplete → active. É nesse ponto que você libera o produto ou o acesso.

​
Sem método padrão na criação

Se você criar a subscription sem default_payment_method, o payment_intent da primeira fatura nasce em requires_payment_method e nada é cobrado automaticamente. Você precisa definir o meio de pagamento e confirmar a cobrança você mesmo — por exemplo, conduzindo o comprador por um fluxo de Checkout Session ou orquestrando o payment intent diretamente. Enquanto a primeira cobrança não fechar, a subscription permanece incomplete.

​
Eventos que você recebe

A criação e a transição disparam uma sequência previsível de webhooks. Reaja a eles em vez de depender da resposta síncrona do create.
MomentoEventoO que carrega
Subscription criadasubscription.createdA subscription completa em data.object, com status: "incomplete".
Primeira fatura abertainvoice.createdA fatura subscription_create.
Cobrança iniciadapayment.intent.createdO intent da primeira cobrança.
Primeira cobrança pagapayment.intent.succeededA cobrança concluiu.
Subscription ativadasubscription.updateddata.object.status vem como active e data.previous_attributes.status traz incomplete.
Na ativação, o subscription.updated traz data.previous_attributes com { "status": "incomplete" } e o data.object com status: "active".

​
Quando a primeira cobrança não fecha

Se a primeira cobrança não for paga em até 23 horas, uma rotina agendada expira a subscription. Nesse passo, em cadeia:
1

A subscription vira incomplete_expired

incomplete → incomplete_expired. Esse estado é terminal.
2

A primeira fatura é anulada

A fatura subscription_create que estava open passa para void e dispara invoice.voided.
3

A cobrança pendente é cancelada

O payment_intent ainda em aberto (requires_payment_method, requires_confirmation, pending ou processing) vira canceled e dispara payment.intent.canceled.
A expiração emite subscription.updated com data.previous_attributes.status = "incomplete" e data.object.status = "incomplete_expired".
Uma falha na primeira cobrança (cartão recusado, por exemplo) não marca a subscription como past_due. A primeira fatura continua open e a subscription continua incomplete — você ainda pode tentar pagar essa fatura — até que a janela de 23 horas a leve a incomplete_expired.

​
incomplete vs past_due vs unpaid

É comum confundir o estado da primeira cobrança com o das renovações. A regra é direta:
CenárioStatus resultante
Primeira cobrança ainda não fechouincomplete
Primeira cobrança não fechou em 23hincomplete_expired
Cobrança de renovação falhoupast_due
Retry/política de cobrança esgotadaunpaid
past_due aparece em cobranças de renovação (billing_reason: "subscription_cycle") ou no fim de trial com trial_settings.end_behavior.missing_payment_method: "create_invoice" sem método de pagamento. Ele nunca decorre da primeira cobrança — a primeira só conhece incomplete, active e incomplete_expired.

​
E o trial?

Uma subscription criada com trial_period_days ou trial_end não passa por incomplete. Ela nasce trialing, grava trial_start/trial_end e a primeira cobrança só acontece no fim do trial. Se não houver método de pagamento salvo nesse momento, trial_settings.end_behavior.missing_payment_method decide se a Chargefy cria a invoice (create_invoice), pausa sem gerar invoice (pause) ou cancela a assinatura (cancel).

​
Próximos passos

Objeto subscription

Schema público completo, todos os status e os campos retornados.

Payment Intents

A cobrança que confirma a primeira fatura e leva a subscription a active.

Checkout Sessions

Página hospedada que cria a subscription e confirma a primeira cobrança por você.

Criar subscription (API)

Contrato do POST /v1/subscriptions.