Skip to main content
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.
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.

​
Key accounting impact of withholding taxes

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 (expressed as a negative value in standard usage)
  • tax_code – a withholding-specific tax code (see section 3 of this article for more details)
  • tax_amount – the calculated withholding amount ( expressed as a negative value in standard usage)

​
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.

​
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. Key points:
  • Specific attribute: withholding_tax on VAT codes (true or false)
  • Marks a tax code as withholding-specific
Chift validation rules:
  • Withholding tax VAT codes cannot be used on invoice lines
  • Only withholding tax VAT codes can be used in thewithholding_taxattribute
  • Standard VAT codes remain line-level only
This 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. Adjusttax_amountand totalat the invoice header
    • Amounts must respect the validation rules described above
This approach matches how Spanish accounting software and ERPs model retenciones, while keeping a clean and predictable Unified API.
Business Central does not natively support withholding taxes as a dedicated accounting concept.
As a result, withholding taxes are implemented using a specific VAT configuration and accounting mapping.
The rules below describe how this is modeled in Business Central and exposed through Chift.
  • VAT codes with a tax rate of 0 and a calculation type set to Full VAT are treated as withholding tax codes.
    These VAT codes are exposed via the API with withholding_tax = true.
    To add, or edit Withholding taxes you need to go to “VAT posting setup” page (use the search icon). See example here👇     Image
  • VAT codes flagged as withholding:
    • cannot be used on standard invoice lines
    • Can only be used in the withholding_tax attribute at invoice header level and are the only taxes accepted at header level.
  • On customer invoices and refunds, the Sales VAT Account defined on the VAT code is used as the general ledger account for the withholding tax.
  • On supplier invoices and refunds, the Purchase VAT Account defined on the VAT code is used instead.
  • For calculation purposes, Business Central relies on internal invoice lines linked to these VAT codes.
    These lines:
    • are used to compute the withholding_tax object returned by the API
    • are not included in the lines array of the invoice response
This approach allows withholding taxes to be correctly posted in Business Central while preserving a clean and explicit withholding tax model in the Unified API.

Example of a invoice booked with Withholding tax in Business central 👇Image