Future: VAT-aware bbInvoicing as a separate extension

[avandenberghe]

Context

Tax (VAT, sales tax) is the most visible "real accounting" feature missing from bbAccounts, but the architectural challenge isn't the rates — it's that tax is cross-cutting in a way the GL alone can't capture.

Why a real VAT implementation can't live in bbAccounts

A GL-only "post to account 4510 Output VAT 21%" works for posting but loses what's needed to file a return:

• Net amount per tax code (not per account) — the return aggregates by code, not GL account.
• Partner VAT number — needed for EC sales lists.
• Tax point date vs accounting date — these can diverge (e.g. invoice issued 2026-01-31, paid 2026-02-15; the tax point is the invoice date but the cash booking is later).
• Reverse-charge / zero-rated / exempt — distinct codes that all map to a single output-VAT GL account but file in different return boxes.

Forcing this metadata onto journal lines bloats the line schema and conflates two different domains. The tax codes belong on document lines (invoice lines, bill lines), not journal lines.

The right shape

A separate avathar/bbinvoicing extension that:

• Owns the document model — invoice / bill / credit note headers, lines with (net_amount, tax_code, gross_amount).
• Owns tax-return metadata — partner VAT number, tax point date, country.
• Posts each invoice line through ledger::create_entry() as a (revenue, output-VAT) pair of journal lines.
• Aggregates the VAT return by joining its own tax-code data, NOT by walking the GL.

This fits the source-agnostic design — bbAccounts stays the GL, the invoicing extension owns the document model and tax aggregation. Same shape we documented for #4 (bbDKP) and #3 (ultimatepoints) integration.

Out of scope for bbAccounts

This issue is filed in the bbAccounts repo as a placeholder reference — the extension itself would live at avathar/bbinvoicing and is its own multi-quarter project. Nothing in bbAccounts code needs to change to support it; the existing reference_source = 'bbinvoicing.invoice' namespacing pattern is sufficient.

When this matters

• Forum is run by a small business using phpBB as a customer portal.
• Forum hosts a service / store that issues invoices.
• Anyone who wants real bookkeeping (not just guild points).

For the current bbDKP / UltimatePoints integration story, this is irrelevant — points aren't taxable transactions.

Status

Not planned. Kept as architectural reference. Re-open / re-prioritise if a real invoicing use case comes up.