[Docs D-22] Reference — Tax categories and VAT handling

[nielsdrost7]

Wiki section: Reference
Tier: 3 — Reference
Publish when: InvoicePlane v1.8.0 is released

---

How VAT flows through the generators

For each line item, InvoicePlane provides:

• item_tax_rate_percent — the VAT rate as a decimal (e.g. 21, 6, 0)
• item_tax_total — the computed tax amount for the line

The generators group line items by tax rate to produce the document-level TaxTotal / TaxSubtotal block required by EN 16931.

---

Tax category codes (BT-151)

EN 16931 defines these tax category codes (cbc:TaxCategoryCode in UBL, ram:CategoryCode in CII):

Code	Name	When to use
S	Standard rate	Normal taxable supplies
AA	Lower rate	Reduced VAT rate
Z	Zero rated	Zero-rated taxable supplies
E	Exempt	VAT-exempt supplies
K	Intra-community	Intra-EU B2B supplies (reverse charge)
AE	Reverse charge	Domestic reverse charge
G	Export	Exports outside the EU
O	Outside scope	Outside VAT scope

InvoicePlane maps tax rates to these codes automatically:

• Rate > 0 → S (standard) or AA (reduced, if configured)
• Rate = 0 → Z (zero rated)
• Special cases → set via the notax mechanism or TaxName option

---

The notax item type

When a line item is marked as notax in InvoicePlane:

• CII generator emits category code O (outside scope)
• UBL generator emits cbc:TaxCategoryCode = O
• No TaxPercent element is emitted (required by EN 16931 when category = O)

---

Belgian tax name mapping (TaxName option)

Belgian CIUS (rule ubl-BE-15) requires cbc:Name on every cac:TaxCategory. The TaxName option maps rates to category name codes:

'TaxName' => [
    21 => ['03'],            // R03 — standard rate
    12 => ['02'],            // R02 — intermediate rate
    6  => ['01'],            // R01 — reduced rate
    0  => ['NS', 'BETE-NS'], // R00 — zero rate
],

Only use rates that appear in this mapping. Other rates will fail ubl-BE-15.

---

Tax totals at line level (InvoiceLineTaxTotal)

Some CIUS variants require a cac:TaxTotal block on each invoice line in addition to the document-level total. Set 'InvoiceLineTaxTotal' => true in the config options.

Formats that require this: Ublciusv131vatbe.php (UBL.BE VAT variant).

---

KSeF tax rates (Poland)

Polish KSeF FA-3 only accepts these rates:

Rate	Code
23%	A
22%	A (legacy)
8%	B
7%	B (legacy)
5%	C

Other rates cause schema validation failure. See KSeF country guide.

---

Reverse charge (KSeF)

The KSeF generator supports a reverse charge annotation on the invoice when the applicable rate is coded for reverse charge. Configure this in the KSeF options if needed for your scenario.

---

Migrated from InvoicePlane/InvoicePlane-e-invoices#46.