O modelo em uma frase
Produto agrupa ofertas. Cada oferta é única (pagamento uma vez) ou recorrente (assinatura com régua de preços). Cada oferta tem umcheckout_url próprio.
Produto
A vitrine: nome, descrição, imagem. Sozinho não cobra nada; ele reúne as ofertas.
Oferta
O que o cliente compra.
one_time (um preço) ou recurring (assinatura com régua). Tem checkout_url.Os dois tipos de oferta
Cobrança única. Um
amount em centavos. O checkout_url leva a um checkout de pagamento avulso (/c/{hash}).Assinatura. Um
interval (monthly, quarterly, half-yearly, yearly) e uma régua de ciclos (cycles). O checkout_url leva a um checkout de assinatura (/s/{hash}).A régua de preços (cycles)
A régua é o coração da oferta recorrente. Ela diz quanto cobrar em cada ciclo, por faixas. Isso vai muito além de “desconto no primeiro mês”: você desenha qualquer escada de preços.- Começa no ciclo 1.
- É contígua: cada faixa começa onde a anterior terminou (
end + 1). - Não se sobrepõe, e cada faixa tem
start <= end. - Só a última faixa pode ser aberta (
end: null= “em diante”).
A régua congela na assinatura no momento em que o cliente assina. Editar a oferta depois muda só quem assinar dali para frente: nunca reprecifica quem já é assinante. Por isso reescrever a régua é seguro.
Como o cliente paga
Toda oferta devolve umcheckout_url pronto. Você tem três caminhos, e todos falam o mesmo modelo:
1
Compartilhe o checkout_url da oferta
O jeito mais direto. O comprador abre o link, informa os próprios dados e paga. Nada mais a integrar.
2
Seletor de planos (opcional)
Ligue
show_plan_selector no produto e ele ganha um selector_url (/s/p/{hash}) que mostra todas as ofertas recorrentes lado a lado, para o cliente escolher.3
Headless por offer_id
Se você já tem os dados do cliente e do cartão, crie a assinatura direto em
POST /charges/subscriptions passando offer_id. A assinatura herda a régua e o intervalo da oferta.Próximos passos
Criar produto
POST /v1/productsCriar oferta (com régua)
POST /v1/products/{id}/offersGerenciar ofertas
Editar, arquivar e restaurar
Assinar por offer_id
Headless via API