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 cents, ÷100 for 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 (in cents)
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.

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