Skip to main content
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.*. 
{
  "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
}
​
id
string
Identificador único da invoice, com o prefixo inv_*.
​
object
string
Sempre "invoice".
​
amount_credit_balance_applied
integer
Valor de saldo de crédito aplicado à invoice, em centavos.
​
amount_discount
integer
Valor do desconto aplicado em centavos.
​
amount_due
integer
Valor devido em centavos. É imutável após a criação da invoice.
​
amount_due_now
integer
Valor a pagar no momento da resposta, incluindo multa e juros acumulados quando aplicáveis.
​
amount_paid
integer
Valor pago em centavos.
​
amount_remaining
integer
Valor restante devido em centavos.
​
amount_subtotal
integer
Subtotal em centavos, antes de descontos ou taxas.
​
amount_tax
integer
Valor de impostos/taxas calculados em centavos.
​
amount_total
integer
Valor total em centavos, equivalente a amount_subtotal - amount_discount + amount_tax.
​
billing_reason
string | null
O motivo de faturamento: subscription_create, subscription_cycle, subscription_update ou manual.
​
collection_method
string
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).
​
created_at
string
Data de criação em formato ISO 8601.
​
currency
string
Moeda da cobrança, em formato de 3 letras ISO (como brl).
​
customer
string | null
ID do customer (cus_*) ao qual a invoice pertence.
​
customer_billing_address
object | null
Snapshot do endereço de cobrança do comprador.
​
customer_billing_name
string | null
Nome de faturamento do comprador.
​
customer_document
string | null
Snapshot do documento fiscal (CPF/CNPJ) do comprador.
​
customer_document_type
string | null
Tipo de documento (cpf ou cnpj).
​
customer_email
string | null
Snapshot do e-mail do comprador.
​
customer_name
string | null
Snapshot do nome do comprador no momento em que a invoice foi criada.
​
default_payment_method
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.
​
description
string | null
Descrição interna ou observação sobre a invoice.
​
due_date
string | null
Data de vencimento da fatura em formato ISO 8601.
​
ending_balance
integer
Saldo final do customer após a invoice, em centavos.
​
hosted_invoice_url
string | null
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.
​
interest
object | null
Configuração de juros da invoice.
​
interest_amount
integer | null
Valor de juros acumulado no momento da resposta, em centavos.
​
invoice_pdf_url
string | null
URL pública para download do PDF da fatura.
​
late_fee
object | null
Configuração de multa por atraso da invoice.
​
late_fee_amount
integer | null
Valor de multa acumulado no momento da resposta, em centavos.
​
latest_charge
string | null
ID do charge (ch_*) gerado na tentativa de pagamento bem-sucedida.
​
line_items
array
Lista de itens de linha faturados.
​
livemode
boolean
true se gerada em produção; false se em testes.
​
marked_uncollectible_at
string | null
Data em que a cobrança foi marcada como incobrável.
​
metadata
object
Objeto de metadados customizados livre. Retorna {} quando vazio.
​
number
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.
​
paid_at
string | null
Data de liquidação da invoice.
​
payment_intent
string | null
ID do payment intent (pi_*) utilizado para a tentativa de pagamento mais recente desta invoice.
​
payment_method_types
array
Meios de pagamento permitidos para a cobrança da invoice.
​
payments
object
Lista dos pagamentos/tentativas vinculados à invoice.
​
starting_balance
integer
Saldo inicial do customer antes da invoice, em centavos.
​
statement_descriptor
string | null
Descrição amigável que aparece na fatura do cartão do cliente.
​
status
string
Estado atual da invoice: draft, open, paid, uncollectible ou void.
​
subscription
string | null
ID da assinatura (sub_*) associada a esta invoice.
​
updated_at
string | null
Data da última atualização em formato ISO 8601.
​
voided_at
string | null
Data em que a invoice foi cancelada.

​
Operações

​
Webhooks

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