Invoices

Invoices represent charges sent to customers. Each invoice contains line items detailing the products and amounts charged.

Invoice Statuses

draft → open → paid
  ↓       ↓
 void  uncollectible

Status	Description
draft	Draft. Can be edited, items can be added/removed
open	Finalized. Chargeable, can receive payments and have credits applied
paid	Fully paid
void	Voided. Applied credits are restored, installments canceled
uncollectible	Marked as uncollectible (write-off)

Invoice Fields

Identification

Field	Description
Number	Unique sequential number (format: INV-YYYY-NNNNNN)
Billing account	Customer who will receive the invoice
Subscription	Associated subscription (optional)
Company	Issuing company (for multi-company setups)

Amounts (in BRL)

Field	Description
Subtotal	Sum of line items before discounts and taxes
Discount	Total discount applied
Taxes	Total taxes calculated
Total withheld	Withheld taxes (PIS/COFINS/IRPJ)
Net amount	Net amount after withholdings
Total	Final amount (subtotal - discount + taxes)
Amount due	Total amount payable
Amount paid	Amount already received
Amount remaining	Outstanding balance

Configuration

Field	Description
Collection method	charge_automatically, manual_charge, or manual_invoice
Billing reason	subscription_cycle, subscription_create, subscription_update, or manual
NF-e policy	disabled, on_finalization, on_full_payment, or per_installment
Due date	Calculated from the customer's payment term days

Line Items

Each invoice contains line items that detail the charges:

Field	Description
Type	subscription or invoiceitem
Description	Descriptive text
Quantity	Quantity charged
Unit amount	Price per unit
Total amount	Quantity × unit amount
Proration	Whether the item is a prorated charge
Period	Start and end of the billed period

Operations

Create Invoice

When creating an invoice, provide:

• Billing account (required)
• Line items with description, quantity, and amount
• Due date (or uses the customer's payment term days)
• Installments (optional, minimum 2, sum must equal the total)
• NF-e policy (optional)

The invoice number is automatically generated using PostgreSQL advisory locks to prevent duplication.

Edit Invoice

draft and open invoices accept edits to every field. Once settled — paid, void or uncollectible — an invoice keeps its terms locked:

Status	Editable fields
draft, open	All
paid	Public ID, subscription, description, line items, metadata, external ID, NF-e issuance policy and NF-e description line
void, uncollectible	Public ID, subscription, description, line items, metadata and external ID

Company, collection method, late-fee policy, due date, billing period and footer are locked. Line items can be corrected (through the API or with inline editing on the items tab, after a warning), but not while the invoice has an issued or in-flight NF-e — cancel it first. The rule applies to the dashboard, the API and MCP alike: changing a locked field returns 422 with code INVOICE_FIELD_LOCKED, listing the refused fields. Sending a locked field with the value already stored is not a change.

Finalize (draft → open)

When finalizing an invoice:

1. Validates that at least 1 line item exists
2. Validates that the sum of installments = total (if installment-based)
3. Calculates taxes automatically
4. Applies credits automatically (FIFO: earliest expiration first, then oldest)
5. If collection method is charge_automatically: attempts to charge immediately

Mark as Paid

• Supports partial payments
• When the full amount is received, the status changes to paid
• Creates a transaction record

Void

When voiding an invoice:

• Applied credits are automatically restored
• Pending installments are canceled
• The void reason is stored

Undo Payment

Reverts an invoice from paid to open:

• Resets the paid amount to zero
• Creates an adjustment transaction (negative amount)
• Stores the reason in metadata

Mark as Uncollectible

Marks the invoice as a write-off. Irreversible. No automatic payment attempts will be made.

Automatic Number Generation

Invoice numbers are generated sequentially per year using PostgreSQL advisory locks. Format: INV-{year}-{6-digit sequence}.

Example: INV-2026-000147

Screenshots

Invoice list

The /dashboard/invoices screen lists all invoices with filters by status, billing account, issuing company, period and payment method. Each row shows number, customer, amount, due date, status and quick actions (download PDF, copy boleto/PIX, mark as paid).

Invoice detail

The /dashboard/invoices/[id] page shows the complete invoice: items (with quantity and unit price), totals, discounts, credits applied, taxes withheld, payment history, linked NF-e and event timeline.