Skip to main content
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.
Cria uma subscription para um customer. Sem trial, a Chargefy cria a primeira invoice e, por padrão, tenta cobrá-la no mesmo request quando existe um payment method salvo. Se o pagamento passar, a resposta já traz a subscription 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.
​
string
obrigatório
Customer da subscription (cus_*).
​
array
obrigatório
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.
Enviar os dois juntos, ou nenhum, dá erro 400. Enviar só 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.
​
string
Payment method salvo (pm_*). Quando enviado, a primeira cobrança é tentada no mesmo request, exceto com payment_behavior: "default_incomplete".
​
string
padrão:"allow_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 subscription active; se falhar ou não houver payment method, retorna 200 com a subscription incomplete, a invoice aberta e a janela de 23 horas para recuperação.
  • default_incomplete — não tenta cobrar no create. Retorna 200 com a subscription incomplete e o payment intent aguardando confirmação.
  • error_if_incomplete — tenta cobrar no mesmo request. Se não conseguir concluir o primeiro pagamento, retorna 402 com type: "card_error" e o code da recusa (o mesmo de payment_error.code; payment_failed quando não há motivo detalhado, no_payment_method quando 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, send_invoice ou invoice de valor zero, não existe pagamento inicial para esse campo bloquear.
​
string
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 por days_until_due. A fatura nasce open já com o seu payment_intent em requires_payment_method, sem nenhuma tentativa até o cliente pagar.
​
integer
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.
​
string
Desconto aplicado às invoices da subscription.
​
object
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.
​
array
Preços 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.
​
string
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.
​
boolean
padrão:"false"
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.
​
integer
Dias de trial. Durante o trial a subscription fica trialing. Use apenas um entre trial_period_days e trial_end.
​
string
Timestamp ISO 8601 exato para o fim do trial. Use apenas um entre trial_end e trial_period_days.
​
object
Política de fim de trial.
​
object
Metadata livre.

​
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 price tem trial_period_days no catálogo, a assinatura já nasce em trial sem você mandar nada. Se dois itens tiverem trials diferentes, a API pede trial_period_days explícito.
  • 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_incomplete retorna a assinatura incomplete com a invoice aberta; cobre pela página hospedada ou tente novamente pelo endpoint POST /v1/invoices/{id}/pay. Com trial e sem cartão, a resposta traz pending_setup_intent para 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 nasce active 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.
​
string
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.
​
string
Timestamp ISO 8601 da próxima cobrança. Vira current_period_end e next_billing_at. Deve estar no futuro. Obrigatório ao importar.
​
string
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

Com allow_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