Assinaturas
Receita recorrente com um ciclo de vida que dá para ler
Crie um preço mensal ou anual, mande o cliente para o checkout e acompanhe cada assinatura por cinco estados. Cada mudança chega como evento de webhook, então seu sistema sempre sabe quem tem acesso.
O modo de teste percorre o ciclo inteiro sem cobrar ninguém.
Clube de membros
Plano mensal · R$ 49,00/mês
sub_5Hn2RtK8wPz4Bq- Status atual
- Ativa
- Próxima cobrança
- 3 de dez. de 2026
Histórico da assinatura
Período de teste iniciado
20 de ago. de 2026O cliente assinou com cartão. Nada é cobrado durante o teste.subscription.createdPrimeira cobrança paga
3 de set. de 2026Fim do teste: R$ 49,00 cobrados e a assinatura está ativa.charge.paidRenovada
3 de out. de 2026R$ 49,00 cobrados pelo novo período.subscription.renewedRenovação recusada
3 de nov. de 2026O cartão estava sem limite. A assinatura ficou em atraso.subscription.past_duePagamento recuperado
5 de nov. de 2026O cliente atualizou o cartão e a renovação foi paga.subscription.renewed
Cinco estados
trialing, active, past_due, paused e canceled. Nada no meio do caminho.
Um evento por mudança
Cada transição envia um webhook, e o acesso acompanha o estado.
Mensal ou anual
Dois preços no mesmo produto, cada um com o próprio checkout.
O ciclo de vida
Escolha um estado e veja o que o muda
Toda assinatura está em exatamente um estado. Escolha um para ver o que ele significa, como a assinatura chega lá, para onde pode ir depois e qual evento de webhook avisa o seu sistema.
Produtos e preços
Um produto, mensal ou anual
O produto é o que você vende. Cada preço define um valor e um intervalo. Ofereça os dois na sua página de planos e abra o checkout do preço que o cliente escolher.
- Os preços ficam no produto, com intervalo mensal ou anual.
- O id do preço vai na requisição que cria a assinatura.
- Trocar de plano no meio do período não faz parte da proposta atual.
Os exemplos seguem uma proposta provisória de contrato de API. Não há SDK; as requisições são HTTP simples.
Quando uma renovação falha
Renovação com falha é um estado, não uma surpresa
A assinatura passa para past_due e seu sistema recebe dois eventos. O que vem depois depende da próxima cobrança: se for paga, a assinatura volta para active; senão, você pausa ou cancela.
charge.failed
A cobrança de renovação não foi paga. O payload traz o failure_code.
subscription.past_due
A assinatura agora está em past_due. É a hora de avisar o cliente.
charge.paid
Uma tentativa posterior é paga, por exemplo depois que o cliente atualiza o cartão.
subscription.renewed
A assinatura volta para active e o novo período começa.
Se ela não for recuperada, a decisão é sua: subscription.paused ou subscription.canceled.
Atenção: Política de novas tentativas: a ser anunciada
{ "id": "evt_3Uu4Vv5Ww6Xx7Y", "object": "event", "type": "subscription.past_due", "api_version": "2026-11-01", "created_at": "2026-12-03T12:00:12.000Z", "data": { "object": { "id": "sub_5Hn2RtK8wPz4Bq", "object": "subscription", "customer_id": "cus_8Hq2LmZr4TxN1a", "product_id": "prod_6Rj8YdF3nQs5Kv", "price_id": "price_9Tm4BxW2gLp7Zc", "status": "past_due", "method": "card", "started_at": "2026-09-03T12:00:00.000Z", "current_period_start": "2026-11-03T12:00:00.000Z", "current_period_end": "2026-12-03T12:00:00.000Z", "canceled_at": null, "cancel_at_period_end": false } }}Proposta provisória de contrato de API — não é um endpoint em operação.
Dúvidas sobre assinaturas
Respostas curtas. Quando algo ainda não está definido, a gente avisa.
Comece com um preço mensal
Crie sua conta, cadastre um produto com preço e acompanhe uma assinatura de teste pelos estados antes do seu primeiro cliente de verdade.
