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 5 dunning steps. Write-off candidate.
`VOID`	Cancelled before collection.

Line Item Types

Each invoice contains line items describing individual charges:

Type	Description
`CHARGE`	Standard usage or flat fee
`USAGE_FEE`	Metered usage charge
`SETUP_FEE`	One-time activation fee
`DISCOUNT`	Applied discount
`TAX_ADJUSTMENT`	Tax line
`CREDIT`	Credit note applied
`PRORATION`	Mid-period adjustment

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 (Avalara AvaTax or Vertex)
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 Integration

Sync invoices automatically to your accounting system:

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

ℹ

By default, only one ERP can be connected at a time (single-ERP invariant). Enable multi-ERP mode in Settings → Billing → Advanced if you need simultaneous sync to multiple systems.

Connect an ERP:

Go to Pricing Studio → Invoices → ERP Sync
Select your ERP provider
Complete the OAuth flow
Aforo automatically syncs new invoices within 60 seconds of finalization

Tax Engine

Aforo integrates with:

Avalara AvaTax v2 — tax calculation and filing
Vertex O Series — enterprise tax management

Tax calculations are cached for 24 hours per unique line item combination. Override tax amounts directly on invoices if needed.

CSV Export

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