> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> O objeto Invoice
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 viabilizam 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 transitam direto sobre `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.*`.
```json theme={}
{
"id": "inv_123",
"object": "invoice",
"allow_late_payment": true,
"amount_credit_balance_applied": 0,
"amount_discount": 0,
"amount_due": 9990,
"amount_due_now": 9990,
"amount_paid": 9990,
"amount_remaining": 0,
"amount_subtotal": 9990,
"amount_tax": 0,
"amount_total": 9990,
"billing_reason": "subscription_cycle",
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"customer": "cus_123",
"customer_billing_address": {},
"customer_billing_name": "Ada Lovelace",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "ada@example.com",
"customer_name": "Ada Lovelace",
"default_payment_method": "pm_123",
"description": null,
"due_date": "2026-05-19T18:00:00Z",
"ending_balance": 0,
"hosted_invoice_url": "https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D",
"interest": null,
"interest_amount": null,
"invoice_pdf_url": null,
"late_fee": null,
"late_fee_amount": null,
"latest_charge": "ch_123",
"line_items": [
{
"id": "ili_123",
"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_123",
"price_data": null,
"product": "prod_123",
"proration": false,
"proration_details": {},
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"subscription_item": "si_123",
"unit_amount": 9990
}
],
"livemode": true,
"marked_uncollectible_at": null,
"metadata": {},
"number": "K7M2-0001",
"paid_at": "2026-05-19T18:01:02Z",
"payment_intent": "pi_123",
"payment_method_types": [
"credit_card"
],
"payments": {
"object": "list",
"data": [
{
"id": "inpay_123",
"object": "invoice_payment",
"amount_paid": 9990,
"amount_requested": 9990,
"canceled_at": null,
"charge": "ch_123",
"created_at": "2026-05-19T18:00:05Z",
"currency": "brl",
"default": true,
"livemode": true,
"metadata": {},
"paid_at": "2026-05-19T18:01:02Z",
"payment_intent": "pi_123",
"status": "paid",
"updated_at": "2026-05-19T18:01:02Z"
}
],
"has_more": false,
"url": "/v1/invoices/inv_123/payments"
},
"starting_balance": 0,
"statement_descriptor": null,
"status": "paid",
"subscription": "sub_123",
"updated_at": "2026-05-19T18:01:02Z",
"voided_at": null
}
```
Identificador único da invoice, com o prefixo `inv_*`.
Sempre `"invoice"`.
Valor de saldo de crédito aplicado à invoice, em centavos.
Valor do desconto aplicado em centavos.
Valor devido em centavos. É imutável após a criação da invoice.
Valor a pagar no momento da resposta, incluindo multa e juros acumulados
quando aplicáveis.
Valor pago em centavos.
Valor restante devido em centavos.
Subtotal em centavos, antes de descontos ou taxas.
Valor de impostos/taxas calculados em centavos.
Valor total em centavos, equivalente a `amount_subtotal - amount_discount +
amount_tax`.
O motivo de faturamento: `subscription_create`, `subscription_cycle`,
`subscription_update` ou `manual`.
Método de cobrança: `charge_automatically` (tenta cobrar o cartão salvo
automaticamente) ou `send_invoice` (envia um link/fatura para o cliente pagar
manualmente via Pix/boleto).
Data de criação em formato ISO 8601.
Moeda da cobrança, em formato de 3 letras ISO (como `brl`).
ID do customer (`cus_*`) ao qual a invoice pertence.
Snapshot do endereço de cobrança do comprador.
Rua, número e complemento principal.
Complemento opcional.
Cidade.
Estado ou província.
CEP ou código postal.
País em código ISO de 2 letras, como `BR`.
Nome de faturamento do comprador.
Snapshot do documento fiscal (CPF/CNPJ) do comprador.
Tipo de documento (`cpf` ou `cnpj`).
Snapshot do e-mail do comprador.
Snapshot do nome do comprador no momento em que a invoice foi criada.
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.
Descrição interna ou observação sobre a invoice.
Data de vencimento da fatura em formato ISO 8601.
Saldo final do customer após a invoice, em centavos.
URL pública ativa onde o cliente final 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.
Configuração de juros da invoice.
Valor de juros acumulado no momento da resposta, em centavos.
URL pública para download do PDF da fatura.
Configuração de multa por atraso da invoice.
Valor de multa acumulado no momento da resposta, em centavos.
ID do charge (`ch_*`) gerado na tentativa de pagamento bem-sucedida.
Lista de itens de linha faturados.
Identificador único do item.
Sempre `"invoice_line_item"`.
Descontos aplicados especificamente a este item.
Subtotal do item em centavos (unit\_amount \* quantidade).
Impostos calculados para o item.
Total líquido do item em centavos.
Moeda (ex: `brl`).
Descrição detalhada do item.
Indica se o item pode receber descontos.
Metadados associados ao item.
Fim do período correspondente à cobrança do item.
Início do período correspondente à cobrança do item.
Posição/ordem do item na lista.
ID do preço (`price_*`) associado.
Snapshot dos dados do preço no momento do faturamento.
ID do produto (`prod_*`) associado.
`true` quando o item representa ajuste proporcional de assinatura.
Detalhes públicos do ajuste proporcional. Retorna `{}` quando vazio.
Quantidade contratada/faturada.
Intervalo de recorrência (`month`, `year`, etc.).
Multiplicador do intervalo de recorrência.
Item de assinatura (`si_*`) que originou a linha, quando existir.
Valor unitário do item em centavos.
`true` se gerada em produção; `false` se em testes.
Data em que a cobrança foi marcada como incobrável.
Objeto de metadados customizados livre. Retorna `{}` quando vazio.
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.
Data de liquidação da invoice.
ID do payment intent (`pi_*`) utilizado para a tentativa de pagamento mais
recente desta invoice.
Meios de pagamento permitidos para a cobrança da invoice.
Lista dos pagamentos/tentativas vinculados à invoice.
ID do invoice payment (`inpay_*`).
Sempre `"invoice_payment"`.
Valor pago por esta tentativa, em centavos.
Valor solicitado nesta tentativa, em centavos.
Data de cancelamento desta tentativa.
Charge (`ch_*`) vinculada à tentativa, quando existir.
Data de criação.
Moeda em ISO 4217, como `brl`.
Indica a tentativa principal/atual da invoice.
`true` em produção; `false` em testes.
Metadados da tentativa.
Data de liquidação desta tentativa.
Payment intent (`pi_*`) vinculado à tentativa.
`open`, `paid` ou `canceled`.
Data da última atualização.
Saldo inicial do customer antes da invoice, em centavos.
Descrição amigável que aparece na fatura do cartão do cliente.
Estado atual da invoice: `draft`, `open`, `paid`, `uncollectible` ou `void`.
ID da assinatura (`sub_*`) associada a esta invoice.
Data da última atualização em formato ISO 8601.
Data em que a invoice foi cancelada.
## Operações
* [Criar invoice](/api-reference/invoices/create)
* [Listar invoices](/api-reference/invoices/list)
* [Consultar invoice](/api-reference/invoices/get)
* [Enviar invoice](/api-reference/invoices/send)
* [Pagar invoice](/api-reference/invoices/pay)
* [Cancelar invoice](/api-reference/invoices/void)
## Webhooks
Mudanças nesse objeto disparam os seguintes eventos de webhook:
* [`invoice.created`](/api-reference/webhooks/invoice.created)
* [`invoice.paid`](/api-reference/webhooks/invoice.paid)
* [`invoice.payment.failed`](/api-reference/webhooks/invoice.payment.failed)
* [`invoice.voided`](/api-reference/webhooks/invoice.voided)
O payload sempre carrega o objeto `invoice` completo em `data.object`.