Faturas

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. Toda invoice nasce pronta para cobrança em open ou já liquidada em paid, dependendo do fluxo que a criou. Em ciclos de assinatura com cobrança pausada, a invoice pode ficar em draft até ser revisada fora da cobrança automática. Os valores, itens de linha, vencimento e snapshots do customer ficam fixos desde a criação. Para corrigir esses dados, cancele a invoice (void) e crie uma nova. O campo hosted_invoice_url é a página pública dessa invoice em billing.chargefy.io/invoice/:token. O token é opaco e pode expirar; quando você recupera a invoice pela API, a resposta traz uma URL ativa. 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.

Data Object

Este é o formato completo retornado em create, get, itens de list, e em data.object dos webhooks invoice.*.

{
  "id": "inv_ZqV289zE9wukopkv",
  "object": "invoice",
  "allow_late_payment": true,
  "amount_credit_balance_applied": 0,
  "amount_discount": 0,
  "amount_due": 9990,
  "amount_due_now": 10290,
  "amount_paid": 10290,
  "amount_remaining": 0,
  "amount_subtotal": 9990,
  "amount_tax": 0,
  "amount_total": 9990,
  "attempt_count": 1,
  "billing_reason": "subscription_cycle",
  "collection_method": "charge_automatically",
  "created_at": "2026-05-19T18:00:00Z",
  "currency": "brl",
  "customer": "cus_riQwdVRaMZbu49FP",
  "customer_billing_address": {
    "city": "São Paulo",
    "country": "BR",
    "line1": "Av. Paulista, 1000",
    "line2": "Conjunto 101",
    "postal_code": "01310-100",
    "state": "SP"
  },
  "customer_billing_name": "Cliente Exemplo",
  "customer_document": "12345678901",
  "customer_document_type": "cpf",
  "customer_email": "nome@email.com",
  "customer_name": "Cliente Exemplo",
  "default_payment_method": "pm_dM9yuzBH4wYprmHc",
  "description": "Assinatura Plano Pro - Maio/2026",
  "due_date": "2026-05-19T12:00:00Z",
  "ending_balance": 0,
  "hosted_invoice_url": "https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D",
  "interest": {
    "percent_per_month": 1
  },
  "interest_amount": 100,
  "invoice_pdf_url": "https://billing.chargefy.io/invoice/inv_ZqV289zE9wukopkv.pdf",
  "late_fee": {
    "type": "fixed",
    "value": 200
  },
  "late_fee_amount": 200,
  "latest_charge": "ch_QyAci9G3TazkgL9H",
  "line_items": [
    {
      "id": "ili_FjNeAZaL5raPzCzC",
      "object": "invoice_line_item",
      "amount_discount": 0,
      "amount_subtotal": 9990,
      "amount_tax": 0,
      "amount_total": 9990,
      "currency": "brl",
      "description": "Plano mensal",
      "discountable": true,
      "metadata": {},
      "period_end": "2026-06-19T18:00:00Z",
      "period_start": "2026-05-19T18:00:00Z",
      "position": 0,
      "price": "price_3EcvQ8jVCuuZFbFW",
      "price_data": null,
      "product": "prod_rmChvoXo53adiW73",
      "proration": false,
      "proration_details": {},
      "quantity": 1,
      "recurring_interval": "month",
      "recurring_interval_count": 1,
      "subscription_item": "si_7B9yTmT89xREH5bG",
      "unit_amount": 9990
    }
  ],
  "livemode": true,
  "marked_uncollectible_at": null,
  "metadata": {},
  "next_payment_attempt": null,
  "number": "K7M2-0001",
  "paid_at": "2026-05-24T10:15:00Z",
  "payment_intent": "pi_trMR1peDCpkRpoVr",
  "payment_method_types": [
    "credit_card"
  ],
  "starting_balance": 0,
  "statement_descriptor": "PLANO PRO",
  "status": "paid",
  "subscription": "sub_1WS5HHHVNqfRkgoF",
  "updated_at": "2026-05-24T10:15:00Z",
  "voided_at": null
}

string

Identificador único da invoice, com o prefixo inv_*.

string

Sempre "invoice".

integer

Valor de saldo de crédito aplicado à invoice, em centavos.

integer

Valor do desconto aplicado em centavos.

integer

Valor devido em centavos. É 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 em centavos.

integer

Valor restante devido em centavos.

integer

Subtotal em centavos, antes de descontos ou taxas.

integer

Valor de impostos/taxas calculados em centavos.

integer

Valor total em centavos, equivalente a amount_subtotal - amount_discount + amount_tax.

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.

Valor	Descrição
`subscription_create`	Primeiro ciclo de uma assinatura recém-criada.
`subscription_cycle`	Ciclo recorrente de cobrança da assinatura.
`subscription_update`	Alteração da assinatura no meio do ciclo.
`manual`	Cobrança avulsa criada manualmente.

string

Método de cobrança.

Valor	Descrição
`charge_automatically`	Tenta cobrar o cartão salvo automaticamente.
`send_invoice`	Envia um link/fatura para o cliente pagar manualmente via Pix/boleto.

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.

Show Campos de customer_billing_address

string | null

Rua, número e complemento principal.

string | null

Complemento opcional.

string | null

Cidade.

string | null

Estado ou província.

string | null

CEP ou código postal.

string | null

País em código ISO de 2 letras, como BR.

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.

Valor	Descrição
`cpf`	Documento de pessoa física.
`cnpj`	Documento de pessoa jurídica.

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, em centavos.

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, em centavos.

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:

Valor	Descrição
`percentage`	Multa percentual sobre o valor da invoice; `value` é o percentual.
`fixed`	Multa de valor fixo; `value` é em centavos.

integer | null

Valor de multa acumulado no momento da resposta, em centavos.

string | null

ID do charge (ch_*) gerado na tentativa de pagamento bem-sucedida.

array

Lista de itens de linha faturados.

Show Campos de line_items[]

string

Identificador único do item.

string

Sempre "invoice_line_item".

integer

Descontos aplicados especificamente a este item.

integer

Subtotal do item em centavos (unit_amount * quantidade).

integer

Impostos calculados para o item.

integer

Total líquido do item em centavos.

string

Moeda (ex: brl).

string | null

Descrição detalhada do item.

boolean

Indica se o item pode receber descontos.

object

Metadados associados ao item.

string | null

Fim do período correspondente à cobrança do item.

string | null

Início do período correspondente à cobrança do item.

integer

Posição/ordem do item na lista.

string | null

ID do preço (price_*) associado.

object | null

Snapshot dos dados do preço no momento do faturamento.

string | null

ID do produto (prod_*) associado.

boolean

true quando o item representa ajuste proporcional de assinatura.

object

Detalhes públicos do ajuste proporcional. Retorna {} quando vazio.

integer

Quantidade contratada/faturada.

string | null

Intervalo de recorrência (month, year, etc.).

integer | null

Multiplicador do intervalo de recorrência.

string | null

Item de assinatura (si_*) que originou a linha, quando existir.

integer

Valor unitário do item em centavos.

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

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.

string | null

ID do payment intent (pi_*) utilizado para a tentativa de pagamento mais recente desta invoice.

array

Meios de pagamento permitidos para a cobrança da invoice.

Valor	Descrição
`pix`	Pagamento via Pix.
`boleto`	Pagamento via boleto bancário.
`credit_card`	Pagamento com cartão de crédito.

integer

Saldo inicial do customer antes da invoice, em centavos.

string | null

Descrição amigável que aparece na fatura do cartão do cliente.

string

Estado atual da invoice.

Valor	Descrição
`draft`	Rascunho, ainda fora da cobrança automática.
`open`	Em aberto e pronta para pagamento.
`paid`	Liquidada.
`uncollectible`	Marcada como incobrável.
`void`	Cancelada.

string | null

ID da assinatura (sub_*) associada a esta invoice.

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.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Data Object

Operações

Eventos

​Data Object

​Operações

​Eventos

Data Object

Operações

Eventos