Pular para o conteúdo principal
O valor de cada item e a soma de preço × quantidade devem caber em o teto da moeda (999999999 na menor unidade em brl), antes de descontos e juros. Valores acima retornam 400 amount_too_large, com param indicando o campo ou a coleção de itens. Por padrão, cria e finaliza a invoice na mesma operação, preservando a resposta com hosted_invoice_url. Ela fica open quando há valor a receber, ou paid quando o total é zero ou o crédito do cliente cobre a dívida. Uma falha na finalização desfaz a criação. Envie finalize: false para criar um rascunho (draft). Nesse estado, você pode editar os termos e itens, sem número definitivo, link público, consumo de crédito, pagamento ou envio de e-mail. Quando estiver pronto, finalize a fatura. Os dados financeiros e o retrato do cliente ficam fixos na finalização. Uma invoice finalizada com valor a receber tem seu payment_intent em requires_payment_method. A cobrança acontece quando o cliente paga pela página hospedada, quando você chama pay ou issue_boleto, ou pela cobrança automática da assinatura.
boolean
padrão:"true"
Finaliza a invoice na criação. Envie false para salvar um rascunho sem link público.
Obrigatórios: customer e a cobrança em si (line_items ou amount). Todo o resto tem padrão ou é resolvido pela Chargefy — inclusive o vencimento: sem due_date nem days_until_due, vale o prazo padrão configurado em Configurações → Assinaturas e faturamento → Faturas. Sem line_items nem amount o request falha com 400; se os dois forem enviados, line_items prevalece e amount é ignorado. Dentro de cada item de line_items, a regra é estrita: exatamente um de price ou price_data — os dois juntos ou nenhum dá erro 400. Para uma cobrança avulsa (com vencimento, multa/juros e URL de fatura para o cliente), envie due_date, defina late_fee/interest quando quiser penalidades por atraso, e deixe delivery: "chargefy" para que a Chargefy envie a fatura por email e cuide dos lembretes. Use amount quando a cobrança não tiver produtos. A resposta inclui hosted_invoice_url, uma URL pública ativa em billing.chargefy.io/invoice/:token. Compartilhe esse campo quando quiser que o cliente visualize ou pague a invoice manualmente. O token pertence à invoice criada, pode ser renovado pela Chargefy, e não é um payment_link reutilizável.
object
Plano fixo no cartão: payment_method_options.credit_card.installments.plan com type: "fixed_count", interval: "month" e count entre 2 e o limite de parcelas configurado (máximo 12). O principal deve comportar pelo menos R$ 7,00 por parcela. Sem esse campo, não fixa um parcelamento na fatura.
integer
Dias antes do vencimento para lembrar. Inteiro não negativo; sem o campo, usa a configuração da organização.
integer
Dias após o vencimento para lembrar. Inteiro não negativo; sem o campo, usa a configuração da organização.
array
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.
string
obrigatório
Customer que receberá a invoice (cus_*).
integer
Valor total na menor unidade da moeda (centavos em brl) (inteiro ≥ 0), quando a cobrança não tem produtos. Vira um item de linha único com quantity: 1 e a description enviada no top-level. Considerado apenas quando line_items está ausente ou vazio.O teto depende da moeda. Em brl, o máximo é 999999999 na menor unidade. Acima do teto, a API retorna 400 amount_too_large com param e maximum_amount. Quando o valor já está associado a uma moeda, a resposta inclui currency.
array
Itens da invoice, para cobranças com produtos. Obrigatório quando você não envia amount; deve ser um array não-vazio. Todos os itens usam a mesma moeda da invoice.
string
Moeda da fatura. Quando há uma assinatura vinculada, a fatura usa a moeda da assinatura. Para faturas avulsas, vale a moeda comum dos itens ou, se eles não informarem a moeda, a moeda padrão da organização. Uma divergência retorna 400 currency_mismatch e indica o campo em error.param.Aceita hoje: brl. Maiúsculas valem como minúsculas (BRL é lido como brl); outra moeda retorna 400 com code: "unsupported_currency". Veja Moedas.
string
Método de cobrança. Padrão: send_invoice.
string
Subscription (sub_*) à qual a invoice pertence. É obrigatória quando collection_method é charge_automatically, porque o worker de cobrança automática processa invoices de assinatura. Para cobrança avulsa, use send_invoice e compartilhe hosted_invoice_url.
string
Vencimento como instante absoluto em RFC 3339, com Z ou offset numérico (ex.: 2026-06-10T12:00:00Z ou 2026-06-10T09:00:00-03:00). O instante é preservado exatamente como enviado.Só é válido com collection_method igual a send_invoice, e é mutuamente exclusivo com days_until_due — envie um ou outro. Sem nenhum dos dois, o vencimento usa o prazo padrão da organização (Configurações → Assinaturas e faturamento → Faturas).Formatos recusados com 400:
Ao converter um dia escolhido pelo vendedor em instante, ancore ao meio-dia UTC (12:00:00Z) — meia-noite fica na fronteira do dia e é lida como a data anterior por quem está a oeste. Veja Datas, fusos e moedas.
integer
Número de dias, a partir da criação, até o vencimento. Só é válido com collection_method igual a send_invoice, e é mutuamente exclusivo com due_date.O vencimento resultante é ancorado ao meio-dia UTC do dia alvo: 0 vence hoje, 7 vence daqui a sete dias. A resposta devolve o due_date já resolvido.
string
Descrição da invoice, exibida na fatura. Com amount, também vira a descrição do item de linha único.
string
Descritor exibido para o cliente na fatura.
object
Multa aplicada uma vez após o vencimento.
object
Juros mensais que acumulam por dia após o vencimento.
boolean
Permite pagamento após o vencimento (multa/juros acumulam, lembretes continuam até o limite). Padrão: true quando há late_fee ou interest; senão, o padrão configurado na organização (Configurações → Assinaturas e faturamento → Faturas).
array
Meios de pagamento permitidos na página da invoice. Padrão: os métodos habilitados no checkout da organização (todos, quando não configurado).
string
Quem entrega a fatura ao cliente. Padrão: chargefy.
string
Payment method salvo (pm_*) escolhido como padrão desta invoice. Precisa pertencer ao customer e estar válido. Ao pagar sem payment_method explícito, a Chargefy tenta usar o padrão da invoice, depois o padrão da subscription, e por fim o padrão do customer.
object
Metadata livre. Padrão {}.

O que a Chargefy resolve sozinha

  • payment_method_types — herdam os métodos habilitados no checkout da organização.
  • allow_late_payment, late_fee, interest e o vencimento — campos omitidos seguem os padrões da organização (Configurações → Assinaturas e faturamento → Faturas); late_fee/interest com null explícito desligam o encargo. Com late_fee ou interest definidos, allow_late_payment vira true automaticamente.
  • Envio e lembretes — com delivery: "chargefy", a fatura é enviada por email na criação quando já está vencendo e os lembretes seguintes são agendados.
  • Snapshot do customer — nome, email, documento e endereço de cobrança são copiados do customer no momento da criação.
  • hosted_invoice_url — gerada (e renovada quando expira) pela Chargefy.
  • amount → item de linha — o valor avulso vira um item único com quantity: 1 e a description da invoice.