Line tax classification and exemptions

An invoice line carries more fiscal information than a rate. Four optional fields decide how the operation is classified, whether VAT is charged at all, and what the recipient actually pays:

All four are optional and additive. An invoice that omits every one of them behaves exactly as it did before they existed, fingerprint included.

When this applies

Declare an exemption cause when the operation is exempt or not subject under the Spanish VAT act. Declare withholding when you invoice as a professional or lease business premises. Declare a surcharge when your customer is a retailer under the equivalence-surcharge regime.

The distinction between the two families of codes is legal, not cosmetic (BR-INV-032):

What the API sends

Exemption and non-subjection

lines[].exemption_reason on POST /v1/invoices and PUT /v1/invoices/{id}. A value outside the eight-code catalogue answers 422 with allowed_values.

curl -X POST https://api.factuarea.com/v1/invoices \
  -H "Authorization: Bearer fact_live_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Content-Type: application/json" \
  -d '{
        "client_id": "0197a2a8-4cf0-7a31-9a5e-3f2b8c1d6e42",
        "series_id": "019e5584-7a72-7038-a8f6-561ed180b699",
        "issued_on": "2026-06-01",
        "due_on": "2026-07-01",
        "lines": [
          { "description": "Exportación de maquinaria", "quantity": 1, "unit_price": 100, "tax_rate": 0, "exemption_reason": "E2" },
          { "description": "Servicio de instalación", "quantity": 1, "unit_price": 50, "tax_rate": 21 }
        ]
      }'

The AEAT breakdown groups by the pair (tax rate, exemption reason), so a mixed invoice produces one group per combination and each group balances on its own. Lines that share both values are aggregated into a single group.

A line that omits the field falls back to the qualification derived from the invoice header. Because a v1-created invoice always has the general header regime, that fallback is "subject and not exempt" — which is why an exempt line must say so explicitly.

IRPF withholding subtracts

lines[].retention_rate is a percentage from 0 to 100, optionally paired with lines[].retention_rate_id, a reference to a withholding tax in your catalogue. The canonical total formula is:

total = subtotal + VAT − withholding + equivalence surcharge

Withholding is money the customer keeps back and pays to the tax authority on the professional's behalf, so it reduces the amount payable (BR-INV-033):

{
  "lines": [
    { "description": "Servicios de consultoría", "quantity": 1, "unit_price": 1000, "tax_rate": 21, "retention_rate": 15 }
  ]
}

That line invoices 1000, charges 210 of VAT, withholds 150, and the customer pays 1060.

If you send both retention_rate and retention_rate_id, they must agree. A mismatch is a 422 naming both percentages, rather than a silent decision about which one wins.

The equivalence surcharge matrix is closed

lines[].surcharge_rate is not a free number. Every line with a surcharge above zero is validated against the legal pairing with its VAT rate (BR-INV-034):

An illegal combination — 21% VAT with a 1,4% surcharge, say — answers 422 with the legal pairs in allowed_values. Comparison is by value rounded to two decimals, so 5.2 and 5.20 are the same pair.

Operations under this regime usually also carry regime_key: "18".

What comes back on each line

The invoice line object returns tax_rate, retention_rate, surcharge_rate, discount_percent, the computed subtotal, taxes and total, plus the fiscal fields: regime_key, exemption_reason, indirect_tax_regime and aeat_tax_code.

The last two are a frozen fiscal snapshot, written when the line is built and never recalculated (BR-TAX-023). An issued invoice does not change its indirect tax regime because the company later moves its registered address, and historical lines predating the snapshot stay empty rather than being back-filled from today's data.

Where the defaults come from

When you omit a rate, it is resolved by a single backend chain shared by every surface — dashboard, public API, agent tooling, importers, recurring invoices — in strict priority order (BR-TAX-025):

The chain is best-effort and never returns an error for an unresolvable default: it degrades to the next tier. If the customer is flagged as subject to the equivalence surcharge and the resolved VAT rate has a legally linked surcharge, that surcharge is injected into the defaults (BR-TAX-022).

Query it directly with GET /v1/taxes/defaults/{docType} when you want to show your users what will be applied before they commit.

What appears on the PDF

Two things change on the printed document.

The totals block reflects the formula above: withholding appears as a subtraction and the equivalence surcharge as an addition, so the amount payable differs from subtotal + VAT.

The legal mentions. When the invoice carries a document-level exemption cause, its legal sentence — citing the LIVA article — is added as the first legal mention of the invoice (BR-TAX-024). That cause is a header field, one per invoice, and it is read-only over the public API: the invoice object exposes exemption_reason and legal_mentions, but no v1 operation sets them. An invoice created through v1 therefore prints no automatic exemption sentence; put the wording in notes if the document needs it.

Line-level exemption_reason_text (up to 255 characters) exists for the same purpose at line level, and is presentation only — it has no fiscal effect.

What reaches the AEAT

Per breakdown group, one qualification. A line that declares an E code produces an exempt-operation entry carrying that literal code and no charged quota; a line that declares an N code produces a non-subject qualification. A line that declares nothing inherits the header-derived qualification (BR-VFC-029).

The grouping key is the pair (tax rate, exemption reason), which is what lets a mixed invoice pass AEAT validation: each group states its own base, its own rate and its own quota, and base × rate = quota holds within the group.

Withholding does not appear in the VeriFactu breakdown — it is not VAT. It is declared in the withholding returns instead, and it reduces the invoice total.

The equivalence surcharge is propagated only to subject-and-not-exempt lines; exempt lines carry neither VAT nor surcharge.

Traceability

Derived from the domain rules of the Factuarea backend:

• BR-INV-032 — the closed E1–E6 / N1–N2 catalogue, the fallback to the header, the grouping by (rate, cause), and the identical-fingerprint invariant.
• BR-INV-033 — per-line IRPF withholding in the v1 contract and the coherence check between rate and referenced tax.
• BR-INV-034 — the closed legal matrix of VAT-to-surcharge pairs.
• BR-TAX-008 — withholding stored with a sign but computed in absolute value.
• BR-TAX-022 — the legal link from a VAT rate to its equivalence surcharge.
• BR-TAX-023 — the immutable per-line fiscal snapshot.
• BR-TAX-024 — the document-level exemption cause and the automatic legal mention.
• BR-TAX-025 — the customer → company → global chain of fiscal defaults.
• BR-VFC-029 — how the qualification is derived when the line declares no cause.