Invoices & Billing

Aforo handles the complete invoicing lifecycle: automatic invoice generation via bill runs, dunning, credit notes, ERP sync, and payment processing.

Invoice States

DRAFT → OPEN → PAID
              ↘ OVERDUE → UNCOLLECTIBLE
              ↘ VOID

State	Description
`DRAFT`	Being assembled. Not yet sent to customer.
`OPEN`	Finalized and sent. Awaiting payment.
`PAID`	Fully collected.
`OVERDUE`	Payment not received by due date.
`UNCOLLECTIBLE`	Escalated after dunning is exhausted (4 steps by default). Write-off candidate.
`VOID`	Cancelled before collection.

Line Item Types

Each invoice contains line items describing individual charges:

Type	Description
`USAGE`	Metered usage charge
`FIXED`	Flat / recurring fee (base fee, platform fee)
`PRORATION`	Mid-period adjustment
`DISCOUNT`	Applied discount
`TAX`	Tax line
`CREDIT`	Credit note applied

Bill Runs

Bill runs batch-generate invoices for all customers in a billing period. Run them manually or let Aforo's scheduler trigger automatically at period close.

Creating a Bill Run

Navigate to Pricing Studio → Invoices → Bill Runs
Click + New Bill Run
Select the billing period
Click Execute

Aforo processes each customer subscription, calculates charges using the 10-stage billing pipeline, and generates individual invoices.

Billing Pipeline Stages

Quota Check → Rollover → Aggregate → Allowance → Rate →
Commit → Discount → Tax → Route → Settle

Stage	What it Does
Quota Check	Enforces hard usage caps
Rollover	Applies carried-over included quota
Aggregate	Sums raw metered usage events
Allowance	Subtracts included free quantities
Rate	Applies pricing model calculations
Commit	Enforces minimum spend / maximum spend
Discount	Applies percentage or fixed discounts
Tax	Calculates tax via the Avalara provider (or $0 when no provider is configured)
Route	Splits between wallet and invoice
Settle	Creates invoice line items and commits

Credit Notes

Issue credit notes to refund or adjust charges:

Draft the credit note with amount and reason
Issue it to make it customer-visible
Apply to Invoice to reduce the outstanding balance

If applying a credit note brings an invoice to $0, it is automatically marked PAID.

curl -X POST https://billing.aforo.ai/api/v1/credit-notes \
  -H "Authorization: Bearer $AFORO_API_KEY" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -d '{
    "invoiceId": "inv_abc123",
    "amount": 50.00,
    "reason": "PRORATION",
    "description": "Pro-rated refund for plan downgrade"
  }'

ERP	Auth Method
QuickBooks	OAuth 2.0
Xero	OAuth 2.0 + PKCE
NetSuite	Token-Based Auth (TBA)
Custom Webhook	HMAC-SHA256

The single-ERP invariant is per billing entity — each legal entity can wire its own ERP (Acme US → QuickBooks, Acme EU → Xero). There is no separate "multi-ERP mode" toggle; you get multiple ERPs by giving each billing entity its own connection.

Connect an ERP:

Go to Pricing Studio → Invoices → ERP Sync
Select your ERP provider
Complete the OAuth flow
Aforo syncs finalized invoices on the connection's configured schedule (sync frequency + time), retrying failed syncs with backoff

Tax Engine

Tax is computed through a pluggable provider. The shipped provider is Avalara AvaTax; when no provider is configured the default returns $0 (a no-op), preserving untaxed behaviour. Avalara quotes are cached for 24 hours per unique line-item combination, and voiding an invoice fans the void out to Avalara so the transaction is reversed there too.

Other providers (e.g. Vertex) are a provider-interface extension — not shipped today; add one when a customer needs it.

CSV Export

Export invoices for manual import into any accounting or reporting system: