Conceitos

O motor tem três camadas: produto (catálogo), plano (oferta) e assinatura (cliente vinculado a um plano). A fatura é derivada — o motor a gera sozinho a cada ciclo.

Produto

O catálogo puro: nome + preço mensal. Nada mais mora aqui — período, parcelamento e desconto são decisões de cada plano.

• Preço fixo: o valor mensal está cadastrado no produto (pricing.monthlyPriceCents).
• Preço variável: o produto não tem preço de tabela — a cada ciclo o motor pergunta o valor ao seu endpoint (veja o guia).

O preço é sempre o mensal. Quem multiplica é o período do plano: um plano semestral cobra 6 × o mensal, numa fatura só. O tipo de preço (fixo/variável) não muda depois de criado, e produto nunca é apagado — arquivar bloqueia novas assinaturas e mantém as existentes faturando.

Cada produto pode ter um espelho no seu gateway (quando ele tem catálogo de produtos): criamos automaticamente ou vinculamos a um produto que já existe lá.

Plano

A oferta comercial — montada sem cliente nenhum:

Campo	O que define
periodMonths	De quanto em quanto tempo nasce uma fatura (1, 3, 6 ou 12 meses)
defaultPaymentMethod	Cartão, Pix ou boleto — o padrão de quem assinar (cada assinatura pode mudar)
maxInstallments	Parcelamento máximo no cartão (1–12), independente do período
expirationDays	Dias entre a geração (no chargeDay) e o vencimento da cobrança (0–90, padrão 0) — vale para cartão, boleto e pix
commitmentCycles	Fidelidade em ciclos — só registro; a tratativa de quebra é sua
items[]	Os produtos do plano
items[].discounts[]	A régua de desconto de cada produto

Versões

Editar um plano (PUT /v1/plans/{id}, com a oferta completa de novo) cria uma versão nova: quem já assinou segue pinado na versão que assinou; só assinaturas novas pegam a nova. Para mudar as condições de um assinante, use POST /v1/subscriptions/{id}/customize — cria uma versão exclusiva daquela assinatura.

A régua de desconto

Cada produto do plano aceita múltiplas regras: percentual + faixa de ciclos (fromCycle até toCycle, ou sem toCycle = vale para sempre). Quando duas regras pegam o mesmo ciclo, a primeira da lista ganha — nada empilha.

Atenção à tradução de tempo: ciclo = fatura. Num plano semestral, “2 ciclos com desconto” significa 1 ano de desconto.

Produto variável não entra na régua — o valor já chega calculado do seu endpoint.

Assinatura

O vínculo cliente ⟷ plano, criado via API (POST /v1/subscriptions):

• externalRef: o identificador do cliente no seu sistema. É a chave de tudo — nos webhooks e no endpoint de preço, devolvemos o seu ID, não o nosso.
• chargeDay: dia da cobrança, de 1 a 28. Padrão: o dia da criação da assinatura (criou dia 29, 30 ou 31? Vira 28 — todo mês tem dia 28, a âncora nunca desliza).
• paymentMethod: opcional — omitido, herda o padrão do plano.
• firstChargeDate: opcional — adia a primeira fatura para uma data futura. Sem chargeDay junto, o dia dela vira a âncora dos próximos ciclos.
• gatewayConnectionId: em qual gateway esta assinatura fatura — congelado na criação. Com um gateway só, é automático; com mais de um, a escolha é obrigatória (as opções estão em GET /v1/integration).
• expirationDays: opcional — sobrescreve o prazo de vencimento do plano só para esta assinatura. A resposta devolve o efetivo e a origem (expirationDaysSource).

Trocar de gateway (POST /v1/subscriptions/{id}/gateway) re-pina a assinatura em outra conexão, valendo do próximo ciclo — ciclos e fidelidade seguem intactos. Sem externalCustomerId, criamos o cliente no gateway novo com os dados que guardamos; com ele, apontamos para o cliente importado pela portabilidade de cofre (caso cartão — o cofre migra entre os gateways, e GET /v1/integration/migration-map gera o de-para para o ticket).

Cancelar (POST /v1/subscriptions/{id}/cancel) encerra de vez: a fatura do ciclo corrente segue o fluxo normal, nenhuma nova é gerada. A resposta informa se a fidelidade (commitmentCycles) foi cumprida.

O ciclo de vida da fatura

A fatura é gerada no próprio chargeDay, sempre entre 05h e 22h (horário de Brasília) — nada roda de madrugada. É na geração que a régua congela os valores e o preço variável é apurado: a janela de uso do ciclo fecha à hora 0 do chargeDay, então o valor é perguntado com ela completa.

A cobrança sai no gateway vencendo em paymentDueDate = dueDate + expirationDays — o prazo é congelado na fatura na geração (mudar o plano depois não mexe em fatura já gerada), e ela só vira overdue depois desse vencimento.

draft → awaiting_value → ready → issued → paid | overdue

Estado	Significado
draft	Gerada; itens fixos calculados pela régua do plano
awaiting_value	Item variável sem resposta válida — fatura retida, você foi alertado
ready	Todos os valores congelados; pronta para emissão
issued	Cobrança avulsa criada no seu gateway
paid	Pagamento confirmado
overdue	Recusada ou vencida — se você tem a Recuperação, a régua assume daqui
canceled	Retirada do fluxo — não será emitida

Duas garantias do fluxo: nada é registrado como issued antes do gateway confirmar a criação da cobrança, e o valor de um item variável fica congelado na fatura junto com a resposta crua do seu endpoint — dá para auditar depois.

Duas credenciais, nunca confundidas

Credencial	Direção	Para quê
API key (rk_…)	você → motor	Autentica suas chamadas REST e MCP
Secret de integração	motor → você	Assina tudo que chamamos no seu sistema (preço, webhooks, eventos)