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.

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)

Austria (at)

Australia (au)

Belgium (be)

Bulgaria (bg)

Switzerland (ch)

Cyprus (cy)

Czech Republic (cz)

Germany (de)

Denmark (dk)

Estonia (ee)

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)

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

Examples (postal‑code dependent):

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)

France (fr)

United Kingdom (gb)

Greece (gr)

Croatia (hr)

Hungary (hu)

Ireland (ie)

Iceland (is)

Italy (it)

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)

Lithuania (lt)

Luxembourg (lu)

Latvia (lv)

Monaco (mc)

Malta (mt)

Malaysia (my)

See also: Submit tax report to LHDN.

Netherlands (nl)

Norway (no)

New Zealand (nz)

Poland (pl)

Portugal (pt)

Romania (ro)

Sweden (se)

Saudi Arabia (sa)

Singapore (sg)

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

Recommendation (Singapore)

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

Slovenia (si)

Slovakia (sk)

United States (us)

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
  }
]