Pular para o conteúdo principal
Uma invoice (fatura) representa a cobrança periódica de uma assinatura ou de itens cobrados manualmente de um cliente. Ela centraliza as informações de valores devidos e pagos, os itens cobrados, os descontos aplicados e as referências aos recursos financeiros que permitem o pagamento, como o payment_intent e o customer. Na Chargefy, as invoices são geradas automaticamente pelo ciclo de faturamento de uma assinatura (subscription_cycle, subscription_create ou subscription_update) ou podem ser criadas de forma avulsa (manual) para cobranças específicas. Compras avulsas diretas (one-off) não geram invoices — essas passam direto pelos payment_intents para manter o fluxo leve e limpo. Uma invoice pode estar em draft enquanto você revisa os itens e termos. O rascunho não é exibido ao comprador e retorna number, finalized_at, hosted_invoice_url e invoice_pdf_url como null. Na API, a criação continua finalizada por padrão; envie finalize: false para optar pelo rascunho. O painel salva inicialmente como rascunho. Ao finalizar, a invoice recebe número e retrato atual do cliente, aplica o crédito disponível uma única vez e fica open ou paid. Itens, valores, vencimento e retrato do cliente ficam definitivos. A partir daí, corrija a cobrança cancelando a invoice e criando outra. O campo hosted_invoice_url é a página pública dessa invoice em billing.chargefy.io/invoice/:token. O token é opaco e vale 30 dias desde a emissão; quando você recupera a invoice pela API, a resposta traz uma URL ativa. Abrir não renova o prazo. A página expirada permite solicitar outro acesso pelo e-mail cadastrado, sem alterar a dívida. Enquanto a invoice está open, essa página pode receber pagamento pelos métodos permitidos em payment_method_types. Depois que a invoice é paga, cancelada ou marcada como incobrável, uma URL ativa continua servindo para visualização do estado da fatura, sem aceitar novo pagamento. Essa URL pertence a uma invoice específica. Ela não é um payment_link: payment links são URLs reutilizáveis de oferta que materializam checkout sessions novas a cada clique.
string | null
Instante ISO 8601 da finalização. null enquanto a invoice é um rascunho.

Data Object

Este é o formato retornado em create, get, itens de list e nos webhooks de fatura. invoice.deleted retorna apenas { id, object: "invoice", deleted: true }.
array
obrigatório
Condições de comissão de afiliado registradas: cada item contém affiliation e affiliate_fee_rate em pontos-base; [] indica ausência de comissão de afiliado. Esta seleção não comprova recebimento: o pagamento registra o resultado de cada participante. Encerrar uma parceria retira sua participação nas próximas cobranças e preserva os valores e as parcelas já divididos.
string
Identificador único da invoice, com o prefixo inv_*.
string
Sempre "invoice".
integer
Valor de saldo de crédito aplicado à invoice, na menor unidade da moeda (centavos em brl).
integer
Valor do desconto aplicado na menor unidade da moeda (centavos em brl).
integer
Valor devido na menor unidade da moeda (centavos em brl). É imutável após a criação da invoice.
integer
Valor a pagar no momento da resposta, incluindo multa e juros acumulados quando aplicáveis.
integer
Valor pago na menor unidade da moeda (centavos em brl).
integer
Valor restante devido na menor unidade da moeda (centavos em brl).
integer
Subtotal na menor unidade da moeda (centavos em brl), antes de descontos ou taxas.
integer
Valor de impostos/taxas calculados na menor unidade da moeda (centavos em brl).
integer
Valor total na menor unidade da moeda (centavos em brl), equivalente a amount_subtotal - amount_discount + amount_tax + surcharge_amount. Juros de parcelamento não entram no total.
integer
Quantas tentativas de pagamento esta fatura acumulou, do ponto de vista da régua de recuperação. A primeira tentativa conta como 1; depois dela, apenas as retentativas automáticas incrementam.Cobrar a fatura manualmente — por POST /v1/invoices/:id/pay ou pelo painel — não move a régua. Isso é proposital: uma cobrança manual não deve consumir as tentativas automáticas que ainda restam ao cliente.Por isso o valor não é o tamanho de payments.data[]. Uma tentativa manual cria um pagamento sem contar, e uma retentativa que a régua pula — porque a recusa anterior foi de um tipo que repetir não resolve — conta sem criar pagamento nenhum.
string | null
O motivo de faturamento.
string
Método de cobrança.
string
Data de criação em formato ISO 8601.
string
Moeda da cobrança, em formato de 3 letras ISO (como brl).
string | null
ID do customer (cus_*) ao qual a invoice pertence.
object | null
Snapshot do endereço de cobrança do comprador.
string | null
Nome de faturamento do comprador.
string | null
Snapshot do documento fiscal (CPF/CNPJ) do comprador.
string | null
Tipo de documento fiscal do comprador.
string | null
Snapshot do e-mail do comprador.
string | null
Snapshot do nome do comprador no momento em que a invoice foi criada.
string | null
Payment method (pm_*) escolhido para esta invoice. Quando a invoice é paga sem payment_method explícito, a ordem de resolução é: payment_method do request, default_payment_method da invoice, default_payment_method da subscription, e default_payment_method do customer.
string | null
Descrição interna ou observação sobre a invoice.
string | null
Data de vencimento da fatura em formato ISO 8601.
integer
Saldo final do customer após a invoice, na menor unidade da moeda (centavos em brl).
string | null
URL pública ativa onde o cliente pode ver a invoice. Enquanto a invoice está open, a página também permite pagamento pelos métodos em payment_method_types. O token da URL é opaco e pode ser renovado pela Chargefy; não tente montá-lo manualmente.
object | null
Configuração de juros da invoice.
integer | null
Valor de juros acumulado no momento da resposta, na menor unidade da moeda (centavos em brl).
string | null
URL pública para download do PDF da fatura.
object | null
Configuração de multa por atraso da invoice, com type e value.Valores de type:
integer | null
Valor de multa acumulado no momento da resposta, na menor unidade da moeda (centavos em brl).
string | null
ID do charge (ch_*) gerado na tentativa de pagamento bem-sucedida.
array
Lista de itens de linha faturados.
boolean
true se gerada em produção; false se em testes.
string | null
Data em que a cobrança foi marcada como incobrável.
object
Metadata livre. Retorna {} quando vazio.
string | null
Data e hora ISO 8601 da próxima tentativa automática de cobrança.É null quando a régua de recuperação terminou e sempre null quando collection_method é send_invoice, já que nesse modo a Chargefy não cobra automaticamente.
string | null
Número legível da fatura, sequencial por cliente (ex: K7M2-0001). Cada cliente recebe um prefixo próprio e a numeração reinicia nele. Sempre presente: atribuído na criação da fatura a partir do prefixo do cliente.
string | null
Data de liquidação da invoice.
boolean
true quando a invoice foi marcada como paga por um recebimento fora da Chargefy, como dinheiro em espécie ou transferência direta, por POST /v1/invoices/{id}/pay com paid_out_of_band. Nenhuma cobrança liquidou essa invoice: não há transação, taxa nem repasse associados ao valor.
string | null
ID do payment intent (pi_*) da invoice. Nasce junto com ela, na emissão, sempre que há valor a receber, e fica em requires_payment_method até uma tentativa ser armada nele (página hospedada, pay ou cobrança automática). Cada tentativa é uma charge dentro desse mesmo intent. null apenas em invoices sem nada a cobrar (valor zero).
array
Meios de pagamento permitidos para a cobrança da invoice.
object
Condição de parcelamento congelada desta invoice — a mesma estrutura do objeto Subscription, porém aplicada: toda tentativa de pagamento desta invoice cobra exatamente o plano congelado aqui, sem recálculo em retentativas. payment_method_options vem null numa invoice cobrada à vista. O plano é sempre { type: "fixed_count", interval: "month", count: 2..12 }.
integer
Saldo inicial do customer antes da invoice, na menor unidade da moeda (centavos em brl).
string | null
Descrição amigável que aparece na fatura do cartão do cliente.
string
Estado atual da invoice.
string | null
ID da assinatura (sub_*) associada a esta invoice.
integer
Repasse de tarifa pago pelo comprador, na menor unidade da moeda (centavos em brl), já incluído em amount_total. Só aparece numa invoice de compra por checkout com has_surcharge; nas demais é 0. Veja Repassar a tarifa de venda ao comprador.
string | null
Data da última atualização em formato ISO 8601.
string | null
Data em que a invoice foi cancelada.

Operações

Eventos

Mudanças nesse objeto disparam os seguintes eventos: O payload sempre carrega o objeto invoice completo em data.object.