Assinaturas
Criar uma assinatura
Cria uma subscription.
Cobranças positivas precisam satisfazer o mínimo do plano efetivo e do método.
Um valor insuficiente retorna
amount_too_small antes do processamento e não
autoriza repetição automática. Veja mínimos e tratamento do erro.active; se falhar, o comportamento depende de payment_behavior.
Só dois campos são obrigatórios: customer e items. Todo o resto tem
default ou é resolvido pela Chargefy — veja
o que você não precisa mandar.
Comissões de afiliados para vínculos ativos: cada item contém
affiliation (aff_*) e
affiliate_fee_rate, inteiro de 1 a 10000 pontos-base (3000 = 30%).
Os percentuais incidem em paralelo sobre o valor líquido da venda antes das
comissões de afiliados; a soma não pode ultrapassar 10000. Até 8 afiliados em venda
direta ou 7 com plataforma. Envie [] para remover a seleção.
Veja Comissões de afiliados.Itens recorrentes da assinatura — pelo menos um. Cada item aponta para um
preço de exatamente uma destas duas formas:
price— ID de um preço recorrente do catálogo (price_*). É o caminho normal.price_data— preço definido na hora, sem passar pelo catálogo.
product não
funciona — o item exige o preço, e o preço default do produto não é
resolvido automaticamente: envie o ID dele em price.Todos os itens precisam ter a mesma moeda e o mesmo intervalo — é
deles que a assinatura herda moeda e cadência.Payment method salvo (
pm_*). Quando enviado, a primeira cobrança é tentada
no mesmo request, exceto com payment_behavior: "default_incomplete".Controla a primeira cobrança de uma subscription sem trial quando
collection_method é charge_automatically e a primeira invoice tem valor
a pagar.allow_incomplete(padrão) — tenta cobrar no mesmo request. Se passar, retorna a subscriptionactive; se falhar ou não houver payment method, retorna200com a subscriptionincomplete, a invoice aberta e a janela de 23 horas para recuperação quando não há tentativa em andamento.default_incomplete— não tenta cobrar no create. Retorna200com a subscriptionincompletee o payment intent aguardando confirmação.error_if_incomplete— tenta cobrar no mesmo request. Se não conseguir concluir o primeiro pagamento, retorna402comtype: "card_error"e ocodeda recusa (o mesmo depayment_error.code;payment_failedquando não há motivo detalhado,no_payment_methodquando não há cartão), e a subscription não é criada como recurso público.
pending_if_incomplete é exclusivo de updates e retorna 400 quando usado
no create. Em trial ou invoice de valor zero, não existe
pagamento inicial para esse campo bloquear.Forma de cobrança de cada ciclo. Padrão:
charge_automatically.charge_automatically(padrão) — cada ciclo é cobrado automaticamente no payment method padrão da assinatura.send_invoice— a cada ciclo a fatura é emitida com um link de pagamento e cobrada manualmente; o vencimento é controlado pordays_until_due. A fatura nasceopenjá com o seupayment_intentemrequires_payment_method, sem nenhuma tentativa até o cliente pagar.
Dias até vencimento quando
collection_method é send_invoice. O vencimento
de cada ciclo é ancorado ao meio-dia UTC do dia alvo — veja Datas, fusos e
moedas.Condição de parcelamento escolhida pelo comprador no seu checkout. Você não
define uma política aqui — apenas transmite o que o comprador aceitou. Omitir
o campo (ou enviar
payment_method_options: null) significa cobrança à
vista.A única forma aceita é
payment_method_options.credit_card.installments.plan com type: "fixed_count", interval: "month" e count entre 2 e 12. Campos
desconhecidos, count: 1 dentro de plan, planos mensais ou mais curtos e
quantidades acima da regra efetiva são rejeitados — nunca ignorados. A regra
efetiva é o menor entre 12, o máximo configurado pela organização, os meses
do período de cobrança e o limite pelo valor (cada parcela precisa de pelo
menos R$ 7,00 sobre o valor recorrente com desconto; cobranças iniciais não
aumentam o máximo).A condição vale para todas as faturas de cartão da assinatura: cada fatura a
congela na criação e nenhuma retentativa recalcula quantidade, juros ou
total. Este campo é somente leitura na atualização da subscription.Itens avulsos cobrados somente na primeira fatura — o caso típico é uma
taxa de setup. Nunca entram em
items nem voltam nas renovações. Com trial,
ficam pendentes e são cobrados junto com o plano na primeira fatura do fim
do trial; se o trial for cancelado antes, são descartados.Timestamp ISO 8601 em que a subscription termina. Use para vender com prazo —
contrato com vigência, plano com data de encerramento combinada. Na data, a
subscription encerra sozinha.Precisa estar no futuro. Use apenas um entre
cancel_at e
cancel_at_period_end.true faz a subscription encerrar no fim do primeiro período, sem renovar.
É a forma de vender um período contratado sem calcular a data: um plano anual
entregue como um ano.A data resultante aparece em cancel_at na resposta. Use apenas um entre
cancel_at_period_end e cancel_at.Sem nenhum dos dois, a subscription renova indefinidamente até ser cancelada.
Em uma subscription com trial, se
default_payment_method não for enviado, a
resposta inclui pending_setup_intent. Busque esse setup intent para obter o
client_secret e confirmar um cartão antes do fim do trial.Dias de trial (inteiro >= 0). Com
0, a assinatura começa sem trial, mesmo
quando o preço tem teste configurado. Com valor maior que zero, fica
trialing pelos dias informados. Use apenas um entre trial_period_days e
trial_end. Omitir mantém o teste configurado no preço.Timestamp ISO 8601 exato para o fim do trial. Use apenas um entre
trial_end
e trial_period_days.O que você não precisa mandar
- Moeda e cadência — a assinatura herda dos itens. Por isso todos os itens precisam ter a mesma moeda e o mesmo intervalo; misturar dá erro 400.
- Trial configurado no preço — se o
pricetemtrial_period_daysno catálogo, a assinatura já nasce em trial sem você mandar nada. Se dois itens tiverem trials diferentes, a API pedetrial_period_daysoutrial_endexplícito. Envietrial_period_days: 0para criar sem trial. - Primeira cobrança — com
default_payment_method, a cobrança é tentada no mesmo request e a resposta já reflete o resultado. Sem cartão e sem trial,allow_incompleteretorna a assinaturaincompletecom a invoice aberta; cobre pela página hospedada ou tente novamente pelo endpointPOST /v1/invoices/{id}/pay. Com trial e sem cartão, a resposta trazpending_setup_intentpara coletar o cartão antes do fim do trial. - Descrição dos itens — vem do nome do preço ou do produto quando você
não manda
description.
Importar uma assinatura existente
Para migrar assinaturas ativas de outro sistema de cobrança, envie os três campos abaixo. A assinatura nasceactive com o período real preservado e sem
cobrar o período atual (já cobrado na origem) — nenhuma invoice é criada agora. A
primeira cobrança da Chargefy acontece no próximo ciclo (billing_cycle_anchor).
Sem default_payment_method, a assinatura fica em send_invoice: no próximo ciclo
uma invoice em aberto é gerada e a assinatura permanece active (o cartão pode ser
adicionado depois). Combine com o header Idempotency-Key
para reimportar em lote com segurança.
Timestamp ISO 8601 do início do período atual (já cobrado na origem). Vira
current_period_start e start_date. Deve estar no passado. A presença desse
campo ativa o modo de importação.Timestamp ISO 8601 da próxima cobrança. Vira
current_period_end e
next_billing_at. Deve estar no futuro. Obrigatório ao importar.Obrigatório ao importar e deve ser
none — confirma que o período atual não é
cobrado novamente (já foi cobrado na origem).Importar uma assinatura ainda em trial: envie
trial_end (timestamp ISO
futuro) no lugar de billing_cycle_anchor. A assinatura nasce trialing com
trial_start = backdate_start_date, e a primeira cobrança acontece no fim
do trial. trial_settings.end_behavior controla o que ocorre se o trial
terminar sem payment method.Importar uma assinatura já cancelada (histórico): envie
canceled_at
(timestamp ISO passado) no lugar de billing_cycle_anchor. A assinatura nasce
canceled — só um registro de histórico: não gera cobrança, job nem webhook.Resultado da primeira cobrança
Comallow_incomplete, a resposta é sempre 200: active quando a cobrança
passa e incomplete quando ela precisa ser recuperada. Com
error_if_incomplete, uma cobrança recusada retorna 402 e não existe uma
subscription para consultar ou recuperar depois. Repetir o request com a mesma
Idempotency-Key devolve o mesmo resultado.
Cobrança inicial aprovada
Trial com setup intent pendente
200
allow_incomplete com cobrança recusada
200
Erros de criação
400
401
402
Respostas de importação
Importada com send_invoice e sem cartão
200
Importada em trial
200
Importada cancelada para histórico
200

