Invoices & Billing

Aforo handles the complete invoicing lifecycle: automatic invoice generation via bill runs, invoice PDFs, email delivery to your customers, dunning, credit notes, ERP sync, and payment processing.

Invoice States

DRAFT → OPEN → PAID
              ↘ OVERDUE → UNCOLLECTIBLE
              ↘ VOID

Line Item Types

Each invoice contains line items describing individual charges:

Outcome-based usage lines

A usage line for an Outcome-Based billable unit spells out how the billed units were counted:

Agent calls usage — 927.5 billed of 1000 (SUCCESS 900 × 1, PARTIAL 40 × 0.5, TIMEOUT 30 × 0.25, ERROR 30 × 0)

The first number is the sum of units × weight; the second is the raw count. The amount is that first number, minus any included free units, times the rate — here 927.5 × $0.02 = $18.55. Events that arrived without a status are listed as no status N × 1. A very long breakdown is cut at 512 characters and ends in …).

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

1. Navigate to Pricing Studio → Invoices → Bill Runs
2. Click + New Bill Run
3. Select the billing period
4. 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

Credit Notes

Issue credit notes to refund or adjust charges:

1. Draft the credit note with amount and reason
2. Issue it to make it customer-visible
3. 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"
  }'

Invoice PDF and Preview

Every finalized invoice has a PDF your customer can keep: your logo and company details, bill-to, line items, tax, totals, and payment terms. Money and dates are formatted for the issuing billing entity's locale and timezone, and billing periods show the inclusive last day (a period ending at midnight on 1 May reads "… – 30 Apr").

• Preview — open an invoice (row menu or the invoice drawer) and choose Preview. You see the same document the PDF is produced from, so what you check is what your customer gets.
• Open PDF shows the real PDF in a new tab; Download PDF saves it as invoice-<invoice number>.pdf.

Draft, void, and uncollectible invoices carry a watermark on the PDF so a copy that leaves your team can't be mistaken for a payable invoice.

Send Invoices by Email

Use this when you want your customer to receive the invoice directly from Aforo, with the PDF attached.

1. Open the invoice and choose Send.
2. Recipients default to the invoice's billing contact. Add up to 10 addresses; duplicates are removed regardless of letter case.
3. Optionally add a message (up to 2,000 characters). It appears above the invoice summary in the email.
4. Leave Attach PDF on unless the customer only needs the link.
5. Expand the preview to see the exact subject, body, sender, and attachment name before you send.
6. Choose Send now or Schedule.

You can email invoices that are Open, Overdue, Paid, or Uncollectible. Drafts must be finalized first, and void invoices can't be sent. Sending an invoice marks it as sent in its timeline.

Schedule a send

Pick Schedule and choose a time at least 2 minutes and at most 1 year ahead. Scheduled emails appear in the invoice's Emails tab with status Scheduled, where you can cancel them until they go out.

If the invoice is voided before its scheduled time, the email is skipped rather than sent.

Send many invoices at once

Select invoices with the row checkboxes on the Invoices page (up to 200 per send) and choose Send in the bar that appears. Each invoice goes to its own billing contact with its own PDF.

The dialog tells you up front how many invoices will be sent, how many can't be (drafts and void invoices), and how many have no billing email on file — those are skipped. After you confirm, the dialog tracks progress until every email has either gone out or is waiting to retry.

Email Delivery Status

The Emails tab on each invoice lists every delivery, one row per recipient, newest first.

Temporary failures are retried after 1 minute, 5 minutes, 15 minutes, 1 hour, and 3 hours. Each retry reuses the same delivery, so the customer never receives duplicates when an earlier attempt actually got through.

Sender Name and Reply-To

Invoice emails use your email brand kit, the same one every other customer email uses. Set it under Channels → Customize Storefront → Email Templates:

• Company Display Name becomes the sender name customers see in their inbox.
• Reply-To Email is where customer replies land — use your billing or support inbox.

Without a brand kit, emails go out under the default sender and replies go to the sending address.

ERP Integration

Sync invoices automatically to your accounting system:

Connect an ERP:

1. Go to Pricing Studio → Invoices → ERP Sync
2. Select your ERP provider
3. Complete the OAuth flow
4. 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: on the Invoices page choose Export to download every invoice in the workspace as a CSV file. The export ignores the page's search and status filters.

Troubleshooting

What Invoice Email Doesn't Do Yet

• Translated email copy. Amounts and dates follow the customer's locale, but the email and PDF text are in English.
• Chinese, Japanese, and Korean characters in the PDF render as boxes.
• A/B testing of invoice email templates isn't available.