CompanyTaxConfiguration

Update the tax configuration of a company

Updates the tax configuration of a company. Fields you omit keep their current value; default_main_tax, when sent, replaces the stored one wholesale.

  • Regime coherence: the main tax and its VeriFactu regime key must be coherent. Regime key 18 (equivalence surcharge) only exists for IVA, so pairing it with any other regime answers 422 INVALID_REGIME_KEY_FOR_TAX_TYPE, with details naming the rejected key, the tax type and the keys that type admits.
  • Surcharge: applying the surcharge without regime key 18 answers 422 RECARGO_REQUIRES_REGIME_RE.
  • Exemption reason: default_exemption_reason travels with default_main_tax — sending the tax without a reason clears the stored one, and sending only the reason applies it to the tax already stored.
  • Coherence of the result: the configuration as it stands after the change is checked as a whole, and answers 422 with one of these codes: MAIN_TAX_REQUIRED (there is no default_main_tax, stored or sent), IRPF_REQUIRED_WHEN_NOT_EXEMPT (apply_irpf without irpf_exempt and no default_irpf_rate), RECARGO_EQUIVALENCIA_REQUIRED (apply_equivalence_surcharge without default_equivalence_surcharge), RECARGO_IVA_COMBINATION_INVALID (a surcharge rate that does not go with the main IVA rate), EXEMPTION_REASON_NOT_ALLOWED_AS_DEFAULT (a default_exemption_reason that only makes sense line by line), EXEMPTION_REASON_REQUIRES_ZERO_RATE (an exemption reason on a main tax that is not 0%), ZERO_RATE_REQUIRES_EXEMPTION_REASON (a 0% main tax with no reason) or EXEMPTION_REASON_TEXT_REQUIRED (a reason that needs default_exemption_reason_text and has none).
  • First write: two concurrent requests that both create the configuration answer the loser with 409 TAX_CONFIG_CONFLICT; retrying it updates the one that won.
put/v1/companies/{company_id}/tax-configuration

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/companies/{company_id}/tax-configuration
  • Auth: HTTP bearer

Request body

default_exemption_reason'EXENTA_ART_20' | 'EXENTA_ART_21' | 'EXENTA_ART_22' | 'EXENTA_ART_24' | 'EXENTA_ART_25' | 'EXENTA_ART_26' | 'EXENTA_ART_140' | 'NO_SUJETA_ART_7_9' | 'NO_SUJETA_LOCALIZACION' | 'ISP_ART_84_2_A' | 'ISP_ART_84_2_B' | 'ISP_ART_84_2_C' | 'ISP_ART_84_2_D' | 'ISP_ART_84_2_E' | 'ISP_ART_84_2_F' | 'ISP_ART_84_2_G' | 'REGIMEN_ART_129' | 'REGIMEN_ART_135' | 'REGIMEN_ART_141' | 'REGIMEN_ART_154' | 'REGIMEN_ART_163_DECIES' | 'OTRO'

Tax exemption reason code per the Spanish VAT Law (Ley 37/1992, LIVA), with the VeriFactu code each one is reported as.

  • EXENTA_ART_20: exempt, art. 20 (domestic operations such as medical, educational, cultural and financial services, or housing rentals). E1.
  • EXENTA_ART_21: exempt, art. 21 (exports of goods). E2.
  • EXENTA_ART_22: exempt, art. 22 (operations treated as exports). E3.
  • EXENTA_ART_24: exempt, art. 24 (free zones, warehouses and customs regimes). E4.
  • EXENTA_ART_25: exempt, art. 25 (intra-community supplies of goods). E5.
  • EXENTA_ART_26: exempt, art. 26 (intra-community acquisitions of goods). It exempts the buyer's acquisition, not a supply the seller invoices, so an invoice line that carries it is rejected with EXEMPTION_NOT_FOR_ISSUED_INVOICE; a supply to another Member State is EXENTA_ART_25.
  • NO_SUJETA_ART_7_9: not subject under art. 7 (such as the transfer of a business as a going concern, art. 7.1º). N1.
  • NO_SUJETA_LOCALIZACION: not subject by the place-of-supply rules (intra-community or non-EU services, arts. 69 and 70). N2.
  • ISP_ART_84_2_A … ISP_ART_84_2_F: reverse charge (the invoice states «inversión del sujeto pasivo»), art. 84.Uno.2.º letters a) (supplier not established in Spain), b) (unwrought or semi-finished gold), c) (scrap, waste and recovery materials, plastic, paper, cardboard, glass and textile waste, and semi-finished non-ferrous metal products), d) (greenhouse gas emission allowances), e) (certain real estate supplies: in insolvency proceedings, with the exemption waived, or enforcing a security) and f) (construction or renovation works). S2.
  • ISP_ART_84_2_G: reverse charge of letter g) (silver, platinum, palladium, mobile phones, consoles, laptops and tablets). The law requires these supplies to be invoiced in a special series, so an invoice line that carries it is rejected with REVERSE_CHARGE_CASE_NOT_SUPPORTED.
  • EXENTA_ART_140: investment gold exemption, art. 140 bis (usually with regime_key 04). E6.
  • REGIMEN_ART_129 (agriculture, livestock and fishing, arts. 124 to 134 bis), REGIMEN_ART_135 (second-hand goods, art and antiques), REGIMEN_ART_141 (travel agencies), REGIMEN_ART_154 (equivalence surcharge) and REGIMEN_ART_163_DECIES (cash basis, arts. 163 decies to 163 sexiesdecies): operations of special regimes, which VeriFactu identifies by the regime key rather than by an exemption code. An invoice line that carries one is rejected with EXEMPTION_REGIME_NOT_SUPPORTED_IN_VERIFACTU; declare the regime with regime_key instead.
  • OTRO: any other provision. Requires the text in exemption_reason_text. E6.
default_exemption_reason_textstring nullable

Custom exemption text, mandatory when default_exemption_reason is OTRO.

Only EXENTA_ART_20 and OTRO can be declared as a default — the reasons a NIF can verify on its own. The rest depend on the recipient, the operation or the regime, so they are declared per invoice line; sending one returns 422. A 0% VAT/IPSI without a reason is also rejected with 422: in those taxes 0% is not a rate, it is the sentinel of an operation carrying no tax.

apply_equivalence_surchargeboolean

Whether the freelancer is under the equivalence surcharge regime.

Omit it to leave the current value untouched. On creation, omitting it means false.

default_equivalence_surcharge0 | 0.26 | 0.5 | 0.62 | 1 | 1.4 | 1.75 | 5.2

Equivalence surcharge percentage in decimal format, one of the values AEAT accepts. Pairs allowed (VAT rate ↔ surcharge): 21↔5.2, 21↔1.75 (tobacco products), 10↔1.4, 4↔0.5, and the temporary ones, only on operations of their period: 5↔0.5 up to 2022-12-31, 5↔0.62 from 2023-01-01 to 2024-09-30, and 7.5↔1 and 2↔0.26 from 2024-10-01 to 2024-12-31. A pair outside its period is rejected with 422 SURCHARGE_RATE_NOT_ACCEPTED_ON_DATE. GET /v1/tax-types publishes every pair with its valid_from / valid_until. The backend automatically normalizes equivalent formats (5.20 → 5.2).

apply_irpfboolean

Whether IRPF withholding should be applied.

Omit it to leave the current value untouched. On creation, omitting it means false: a withholding nobody declared is not applied.

default_irpf_rate0 | 1 | 2 | 2.8 | 6 | 7 | 7.6 | 9.5 | 15 | 19 | 24

Withholding (IRPF) percentage, as the IRPF regulation (Royal Decree 439/2007) sets it: 0 (no withholding), 1 (pig fattening and poultry, and some activities under objective estimation), 2 (other agricultural, livestock and forestry activities), 7 (professional activity in its first three years, and the other 7 % cases), 15 (professional activities, and intellectual property income), 19 (rent of urban property and other income of art. 75.2.b; also the general rate of the Corporate Income Tax withholding) and 24 (image rights). A company that pays Corporate Income Tax can only use 0, 19, 24 and 9.5: see WithholdingOptions.

Ceuta and Melilla: income with the Ceuta and Melilla deduction bears the base rate reduced as the law sets it. Under IRPF, 15 % and 7 % (professional activities) and 19 % (rent of urban property located there) are reduced by 60 %: 6, 2.8 and 7.6. Under Corporate Income Tax, 19 % on those rents is halved: 9.5, which only a company can use (IRPF_RATE_ONLY_FOR_CORPORATE_ISSUER otherwise). Whether the reduction applies is the issuer's choice: the NIF does not show it.

The value counts, not how it is written: 15.0 is 15 and 2.80 is 2.8.

irpf_exemptboolean

Whether the freelancer is exempt from IRPF withholding.

Omit it to leave the current value untouched. On creation, omitting it means false.

default_payment_method'NONE' | 'BANK_TRANSFER' | 'CARD' | 'CASH' | 'CHECK' | 'DIRECT_DEBIT' | 'BIZUM' | 'OTHER'

Payment method shown on invoices and recurring invoices.

  • NONE: no payment information is shown.
  • BANK_TRANSFER: bank transfer to the IBAN of the payment details; the only method that requires an IBAN.
  • CARD: card payment.
  • CASH: cash payment.
  • CHECK: payment by cheque.
  • DIRECT_DEBIT: direct debit from the customer's bank account.
  • BIZUM: payment through Bizum.
  • OTHER: any other method.
payment_term_daysinteger nullable

Default payment term in days (0-365). Omit it to leave the current value untouched; send null to clear it.

proforma_validity_daysinteger nullable

Default validity term in days for new proformas (0-365). Omit it to leave the current value untouched; send null to clear it (proformas stop getting a prefilled expiry date).

Example request

{
  "default_main_tax": {
    "type": "IVA",
    "percentage": 21,
    "regime_key": "01"
  },
  "default_exemption_reason": "EXENTA_ART_20",
  "default_equivalence_surcharge": 5.2,
  "default_irpf_rate": 15,
  "default_payment_method": "BANK_TRANSFER"
}

Response

Configuration updated successfully

successboolean required

Example response

{
  "success": true,
  "data": {
    "default_main_tax": {
      "type": "IVA",
      "percentage": 21,
      "regime_key": "01"
    },
    "default_exemption_reason": "EXENTA_ART_20",
    "default_equivalence_surcharge": 5.2,
    "default_irpf_rate": 15,
    "default_payment_method": "BANK_TRANSFER",
    "withholding_options": {
      "allowed_irpf_rates": [
        0,
        19,
        24
      ]
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.