Skip to main content

What are withholding taxes in Spain?

In Spain, certain invoices are subject to withholding taxes, known as retenciones.A withholding tax is a mechanism where the customer withholds part of the invoice amount and pays it directly to the Spanish tax authorities, instead of paying it to the supplier. As a result, the supplier receives a net amount, reduced by the withholding.In practice, Spanish withholding taxes mainly apply under two legal frameworks:
  • IRPF (Impuesto sobre la Renta de las Personas Físicas)
    This is the most common case and applies to self-employed professionals and freelancers.
    The legal name is Retención a cuenta del IRPF.
  • Impuesto sobre Sociedades (Corporate Income Tax)
    In some cases, withholding taxes also apply to companies.
    The legal name is Retención a cuenta del Impuesto sobre Sociedades.
Unlike VAT, withholding taxes are not line-level taxes, do not increase the invoice total, and must be handled separately at the accounting and API level. This structural difference is why they require dedicated modeling when booking invoices in accounting systems.

​
Key accounting impact of withholding taxes

A withholding tax:
  • Is calculated at the invoice header level, not per line
  • Reduces the total payable amount
  • Does not appear as VAT on invoice lines
  • Must be reported separately using specific tax codes
Because of this, modeling it as a “classic VAT tax line” leads to incorrect totals and broken accounting logic.

​
How withholding taxes are handled in Chift

To properly support Spanish withholding taxes, Chift has a dedicated and explicit model.

​
1. withholding_tax attribute on invoices

Awithholding_tax object is available in both input and output, located at the invoice header level (see here its definition). This object is mandatory when a withholding applies and contains three required attributes:
  • tax_rate – the withholding rate to apply
  • tax_code – a withholding-specific tax code (see section 3 of this article for more details)
  • tax_amount – the calculated withholding amount (always negative)

​
2. Impact on invoice totals and validation

Withholding taxes directly affect invoice totals. Chift enforces strict validation rules to ensure accounting accuracy.

​
Invoice total validation

When submitting an invoice, Chift validates that: 
Total invoice amount
= Sum of line totals
+ Withholding tax amount (negative)
  • The withholding tax reduces the total payable amount.
  • If this rule is not met, the API returns a validation error.
  • It is the integrator’s responsibility to ensure that line totals and the withholding amount satisfy this constraint.

​
Header tax_amount calculation

The tax_amount at the invoice header level is computed as: 
Header tax_amount
= Sum of line-level tax_amounts
+ Withholding tax amount (negative)
This guarantees that:
  • VAT reporting remains accurate
  • Withholding tax is clearly separated from line-level taxes
  • Invoice totals match Spanish accounting expectations

​
3. Dedicated VAT codes for withholding taxes

To avoid ambiguity and invalid bookings, wihtolding tax codes are explicitly marked.

​
Withholding tax VAT codes

  • Specific attribute: withholding_tax on VAT codes (true or false)
  • Marks a tax code as withholding-specific
Rules enforced by Chift:
  • Withholding tax VAT codes cannot be used on invoice lines
  • **Only withholding tax VAT codes can be used in the **withholding_taxattribute
  • Standard VAT codes remain line-level only
This strict separation prevents:
  • Mixing VAT and withholding logic
  • Incorrect tax reporting
  • Connector-specific inconsistencies

​
Booking an invoice with withholding tax via Chift

To correctly book a Spanish invoice with withholding tax:
  1. Use standard VAT codes on invoice lines
    • Lines behave exactly like any regular VAT invoice
  2. Declare the withholding at header level
    • Populate the withholding_tax object with:
      • The correct Spanish withholding tax code
      • Rate and calculated amount (negative)
  3. Let Chift handle totals and validations
    • Totals are adjusted automatically
    • Accounting systems receive a compliant structure
This approach matches how Spanish accounting software and ERPs model retenciones, while keeping a clean and predictable Unified API.
Why this matters
Spanish withholding taxes are not optional edge cases. They are a structural part of invoicing in Spain.By introducing:
  • A dedicated withholding_tax model
  • Clear validation rules
  • Explicit tax code separation
Chift ensures:
  • Accurate accounting
  • Consistent connector behavior
  • No hidden connector-specific hacks
If you’re integrating Spanish invoices, this model is the only correct way to handle retenciones.