Tax report attributes

Taxes Attributes (taxes_attributes)

This guide explains how to correctly fill the taxes_attributes array when creating invoices via the API so integrators know which tax names and categories are expected per country.

Important

• The percentages shown are B2Brouter defaults to ease integration; tax rates can change. Always validate against the current law of each country.
• Tax names must match the expected values in this guide. Do not invent new names (e.g., "Exento", "Umsatzsteuer", "Sales tax").
• Many formats reuse comment as the exemption/“not subject” reason. Fill it whenever you set 0%/exempt/reverse-charge unless your account already has the correct default reason.

Use this guide together with:

• Invoice calculation
• JSON invoice mapping

Things to keep in mind

• Use only these fields inside each taxes_attributes object: name (string), category (string, enum), percent (float), comment (string or null). No other keys such as amount, base, type, etc.
• Percentages are defaults we expect; laws change. If your business case uses a different rate, send that rate but keep the correct name and category.
• For withholdings/retentions, use negative percent and the appropriate tax name (IRPF, IRNR, IRPEF, etc.).
• comment is used as the exemption/“not subject” reason in many formats (Facturae/Verifactu, Peppol categories, etc.). Provide a reason whenever percent is 0 and the operation is exempt/not subject/reverse charge (example: comment: "E2").
• Account settings impact calculation: apply_taxes_per_line (boolean) controls whether taxes are applied per line or on the sum; rounding_method controls rounding.

Structure of taxes_attributes

Each invoice line (invoice_lines_attributes) can contain an array of taxes:

"taxes_attributes": [
  {
    "name": "VAT",
    "category": "S",
    "percent": 21.0,
    "comment": "Standard VAT"
  }
]

For each tax object:

• name (required): Tax name (must match one of the expected values for the company’s country, see Country reference).
• category (recommended): Tax category code (see Tax categories).
• percent (required): Tax percentage. Use negative values for withholdings or retentions.
• comment (optional but recommended for 0%/exemption/reverse charge): Free text reason used by several formats and tax authorities.

Multiple taxes can be applied to the same line by adding multiple objects to taxes_attributes.

Only these fields are valid. Do not include amount, base, or other custom fields; they are calculated internally to avoid inconsistencies.

field	type	required	description
name	string	yes	Tax name (must match the country defaults)
category	string, enum	recommended	Tax category code (see list below)
percent	float	yes	Tax percentage (negative for withholdings)
comment	string or null	optional	Reason/explanation, required for many exempt/not-subject cases

Account-level tax settings that affect calculations

• apply_taxes_per_line (boolean): When true, taxes are applied per line and then summed; when false, bases are summed and tax is applied to the total.
• rounding_method: Rounding strategy (half_up by default). See Invoice calculation.

Tax categories

B2Brouter uses tax categories aligned with the PEPPOL/UNCL5305 codelist and, for some countries, additional codes required by the local tax authority.

Common category codes:

• S – Standard rate.
• H – High rate.
• AA – Reduced rate.
• AAA – Super reduced rate.
• Z – Zero rated supply (0% but subject to VAT).
• E – Exempt (0% and exempt from VAT).
• AE – Reverse charge / “Inversión del sujeto pasivo”.
• G – Free export item, VAT not charged.
• K – Intra-community supply of goods/services (VAT exempt within EEA).
• NS – Not subject.
• O – Outside scope of tax / other operations.

Only these category values are accepted; other codes will be rejected.

Singapore uses additional GST category codes (see Singapore), and Italy uses FatturaPA N.. “natura” codes (see Italy).

General recommendations

• Use the country’s default tax names from the tables below (they match B2Brouter’s default configuration used when a company is created). Keep names/codes even if your rate differs.
• For standard VAT, use the main VAT name and category: "S" with the appropriate percent.
• For reduced rates, use category: "AA" or category: "AAA" according to the defaults shown.
• For zero-rated or exempt operations:
  • Use percent: 0.
  • Choose category based on the legal situation:
    • Z: taxable but 0%.
    • E: exempt.
    • AE: reverse charge.
    • Local codes for specific regimes (Italy N.., Singapore GST categories, etc.).
• For withholdings/retentions, use negative percentages (e.g., -19 for Spanish IRPF) and the tax name for the withholding (e.g., IRPF, IRNR, IRPEF).
• When integrating with tax reporting (Verifactu, TicketBAI, LHDN, etc.), make sure your taxes_attributes are compatible with the corresponding guide.

Country reference – valid tax names and default rates

The following tables list the expected tax names per country with the default rates and categories we preload. Use them as reference for naming and categories; adjust percent if legislation or your scenario requires it.

Percentages may change over time; always verify with current local legislation. Rates and categories are aligned by position in each row (first rate → first category, etc.).

Andorra (ad)

name	percent	category	notes
IGI	4.5, 2.5, 1, 0	S, AA, AAA, Z	VAT (standard/reduced/0%).
IRNR	10, 5, 1.5, -20	S, AA, AAA, S	Non‑resident income tax (withholding when negative).

Austria (at)

name	percent	category	notes
MwSt	20, 10, 13, 0	S, AA, AA, Z	VAT.

Australia (au)

name	percent	category	notes
GST	10, 0	S, E	Goods and Services Tax.

Belgium (be)

name	percent	category	notes
TVA	21, 6, 12, 0	S, AA, AA, Z, E, AE	VAT (standard, reduced, exempt, reverse charge).

Bulgaria (bg)

name	percent	category	notes
ДДС	20, 9, 0	S, AA, Z	VAT.

Switzerland (ch)

name	percent	category	notes
VAT	8.1, 2.6, 3.8, 0	S, AA, AA, E	VAT; 0% typically exports.

Cyprus (cy)

name	percent	category
ΦΠΑ	19, 5, 9, 0	S, AA, AA, Z

Czech Republic (cz)

name	percent	category
DPH	21, 12, 0	S, AA, Z

Germany (de)

name	percent	category	notes
USt	19, 7, 0	S, AA, Z	VAT.

Denmark (dk)

name	percent	category
VAT	25, 0	S, Z, E

Estonia (ee)

name	percent	category
km	22, 9, 0	S, AA, Z

Spain (es)

Spain has several VAT regimes depending on the postal code of the company:

• Mainland/Balearic Islands: IVA.
• Canary Islands: IGIC.
• Ceuta/Melilla: IPSI.

comment is used for the exemption/not-subject reason in Facturae/Verifactu. If you send percent: 0 for an exempt or not-subject operation, add the reason in comment (example: comment: "E2"). If your account already sets the default reason, you can omit it.

Mainland/Balearic Islands (default)

name	percent	category	notes
IVA	21, 10, 7.5, 5, 4, 2, 0	S, AA, AA, AA, AAA, AAA, Z/E/AE	VAT.
IRPF	-19, -15, -7	S	Personal income tax withholding.

Canary Islands (IGIC) / Ceuta & Melilla (IPSI)

Examples (postal‑code dependent):

name	percent	category	notes
IGIC	15, 9.5, 7, 3, 1.5, 0	H, H, S, AA, AA, Z	Canary Islands VAT‑equivalent.
IPSI	10, 8, 4, 2, 1, 0.5	H, H, S, AA, AA, S	Local indirect tax for Ceuta/Melilla.
IRPF	-19, -15, -7	S	Withholding.

Notes (Spain)

• Use IVA/IGIC/IPSI with percent: 0 and the correct category (E, Z, or AE) plus a comment reason for exempt/not subject (e.g., E2).
• Use negative percent for IRPF withholdings.

See also: Verifactu and TicketBAI.

Finland (fi)

name	percent	category
ALV	25.5, 10, 14, 0	S, AA, AA, Z/E

France (fr)

name	percent	category
TVA	20, 5.5, 10, 2.1, 0	S, AA, AA, AAA, Z/AE

United Kingdom (gb)

name	percent	category
VAT	20, 5, 0	S, AA, Z

Greece (gr)

name	percent	category
ΦΠΑ	24, 6, 13, 0	S, AA, AA, Z

Croatia (hr)

name	percent	category
PDV	25, 5, 13, 0	S, AA, AA, Z

Hungary (hu)

name	percent	category
ÁFA	27, 5, 18, 0	S, AA, AA, Z

Ireland (ie)

name	percent	category
VAT	23, 9, 13.5, 4.8, 0	S, AA, AA, AA, Z

Iceland (is)

name	percent	category
VSK	24, 11, 0	S, AA, Z/E

Italy (it)

name	percent	category	notes
IVA	22, 10, 5, 4, 0	S, AA, AA, AAA, N.. / E / Z / AE	VAT.
IRPEF	negative (e.g., -20)	S	Withholding tax (when applicable via FatturaPA).

For FatturaPA, non‑taxable operations use category codes like N1, N2.1, N2.2, N3.1, N3.2, N3.3, N3.4, N3.5, N3.6, N4, N5, N6.1… (see your FatturaPA configuration). They must be sent as 0% VAT with name: "IVA" and category: "N..".

Recommendation (Italy)

• For standard operations: name: "IVA", category: "S", percent: 22.
• For non‑taxable operations: name: "IVA", percent: 0, and the appropriate N.. code in category.

See also: Send an invoice through SDI.

Japan (jp)

name	percent	category	notes
VAT	10, 8, 0	S, AA, E/G/O	Japanese consumption tax.

Lithuania (lt)

name	percent	category
PVM	21, 5, 9, 0	S, AA, AA, Z

Luxembourg (lu)

name	percent	category
TVA	17, 3, 8, 14, 0	S, AA, AA, AA, Z

Latvia (lv)

name	percent	category
PVM	21, 5, 12, 0	S, AA, AA, Z

Monaco (mc)

name	percent	category
TVA	20, 5.5, 10, 2.1, 0	S, AA, AA, AAA, Z/AE

Malta (mt)

name	percent	category
VAT	18, 5, 7, 0	S, AA, AA, Z

Malaysia (my)

name	percent	category	notes
SST	10, 8, 6, 5, 0	T, T, T, T, E/O	Sales and Service Tax.

See also: Submit tax report to LHDN.

Netherlands (nl)

name	percent	category
BTW	21, 9, 0	S, AA, Z/AE

Norway (no)

name	percent	category
MVA	25, 15, 12, 0	S, AA, AA, Z/E

New Zealand (nz)

name	percent	category
GST	15, 0	S, Z/E

Poland (pl)

name	percent	category
PTU	23, 5, 8, 0	S, AA, AA, Z

Portugal (pt)

name	percent	category
IVA	23, 6, 13, 0	S, AA, AA, Z

Romania (ro)

name	percent	category
TVA	19, 9, 5, 0	S, AA, AA, Z

Sweden (se)

name	percent	category
Moms	25, 6, 12, 0	S, AA, AA, Z/E

Saudi Arabia (sa)

name	percent	category
ضريبة القيمة المضافة	15, 0	S, Z/E/O

Singapore (sg)

Singapore uses specific GST categories mandated by IRAS. The tax name is always GST; the category encodes the GST treatment.

name	percent	category	notes
GST	9	SR	Standard‑rated supply.
GST	0	ZR	Zero‑rated supply.
GST	0 / 9	SRCA-S	Customer accounting – sales.
GST	9	SRCA-C	Customer accounting – purchase.
GST	9	SRRC	Reverse charge.
GST	9	SROVR-RS	Overseas vendor registration – remote services.
GST	9	SROVR-LVG	Overseas vendor registration – low‑value goods.
GST	9	SRLVG	Local low‑value goods.
GST	0	ES33	Exempt: regulation 33.
GST	0	ESN33	Exempt: non‑regulation 33.
GST	9	DS	Disregarded supplies.
GST	0	OS	Out‑of‑scope.
GST	0	NG	Non‑GST charge.

Recommendation (Singapore)

• Always use name: "GST".
• Use the appropriate IRAS GST category in category and set percent accordingly (usually 9 or 0).

Slovenia (si)

name	percent	category
DDV	22, 9.5, 0	S, AA, Z

Slovakia (sk)

name	percent	category
DPH	20, 10, 0	S, AA, Z

United States (us)

name	percent	category	notes
VAT	0	O	Used to indicate “no VAT” / outside scope.

Recommendation (US)

• For companies without VAT ID, use a single tax with name: "VAT", percent: 0, category: "O", and optionally comment: "Company without VAT ID".
• Do not create local sales tax names in taxes_attributes; VAT handling is modeled as 0% outside scope.

Examples

Example – Spanish invoice line with VAT and IRPF

"taxes_attributes": [
  {
    "name": "IVA",
    "category": "S",
    "percent": 21.0
  },
  {
    "name": "IRPF",
    "category": "S",
    "percent": -15.0
  }
]

Example – German exempt sale within EU (reverse charge)

"taxes_attributes": [
  {
    "name": "USt",
    "category": "AE",
    "percent": 0.0,
    "comment": "Intra‑community supply – reverse charge"
  }
]

Example – Singapore standard‑rated GST

"taxes_attributes": [
  {
    "name": "GST",
    "category": "SR",
    "percent": 9.0
  }
]