--- title: "Get user tax configuration" method: GET path: "/v1/configuration/taxes" tags: ["ConfigurationTax"] deprecated: true --- # Get user tax configuration `GET /v1/configuration/taxes` ## Request - Base URL: `https://app.beel.es/api` - URL: `https://app.beel.es/api/v1/configuration/taxes` - Auth: HTTP bearer > **Deprecated.** **Deprecated.** Use `GET /v1/companies/{company_id}/tax-configuration`, which behaves identically. Retrieves the tax configuration of the company in focus: the default main tax (`IVA`, `IGIC`, `IPSI` or `OTHER`) with its percentage and regime key, the default exemption reason, the IRPF and equivalence surcharge settings, and the default payment method and payment term. **Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch. ## Response `200` Configuration retrieved successfully - object: The envelope every successful JSON response of the BeeL. API is wrapped in. There are no bare resources in v1 and none are planned: the payload always hangs off `data`. - A **single resource** is an object in `data`. - A **collection** hangs off a named key inside `data`, together with its `pagination`, also inside `data` — `data: {invoices: [...], pagination: {...}}`. - A collection carries `pagination` unless its operation declares itself a **closed catalogue**: a fixed, bounded list with nothing to page through. The declaration is explicit in the operation; a missing `pagination` is never something to infer. - `GET /v1/accounts` pages by cursor (`data: {accounts: [...], next_cursor}`). It is a documented variant of pagination, not another envelope. Putting the array straight into `data` with `pagination` as its sibling is the shape a v2 would adopt; v1 is not being flipped to it. - `success` boolean, required - `data` object, required: The payload. An object for a single resource; an object holding the named collection (and its `pagination`) for a listing. Never a bare array at this level in v1. - `default_main_tax` object, required: Convenience **prefill**, not a default the API applies. Includes tax regime type (IVA/IGIC/IPSI/OTHER), percentage and regime key. It seeds the tax fields of a line where a human (or BeeL itself) is composing one: the dashboard invoice editor, onboarding, and the drafts BeeL generates from payment events. The value is written into the line at that moment and is visible and editable from then on. **Never applied to invoice lines created via the API**: omitting `main_tax` on a `NORMAL` line is a validation error (`422 LINE_MAIN_TAX_REQUIRED`), never a silent fallback to this value. Which tax a line bears is a fiscal decision of the issuer, so the API refuses to guess it — the same line body must produce the same invoice regardless of how the account happens to be configured today. (`SUPLIDO` lines carry no main tax at all, so nothing is prefilled there either.) Common examples: - Standard VAT: { type: "IVA", percentage: 21, regime_key: "01" } - Special Reduced IGIC: { type: "IGIC", percentage: 7, regime_key: "01" } - Standard IPSI: { type: "IPSI", percentage: 10, regime_key: "01" } - `type` 'IVA' | 'IGIC' | 'IPSI' | 'OTHER', required: Tax type by territory: - IVA: Iberian Peninsula and Balearic Islands (4%, 10%, 21%; 2%, 5% and 7.5% only on operations of their period) - IGIC: Canary Islands (0%, 3%, 5%, 7%, 9.5%, 15%, 20%) - IPSI: Ceuta and Melilla (0.5%, 1%, 2%, 4%, 8%, 10%) - OTHER: Configurable 0%-100% Under IVA and IPSI, 0% is not one of these rates: it is the exemption/non-subject sentinel and always travels with an `exemption_reason`. IGIC's 0% is a real rate. See `TaxInfo` for the full rules. - `percentage` number, required: Tax percentage - `regime_key` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' | '10' | '11' | '14' | '15' | '17' | '18' | '19' | '20': Regime key according to VeriFactu regulations. Omitted, `01` (general regime) applies: - 01: General regime operation - 02: Export (IVA and IGIC; not IPSI, whose AEAT list is `01, 08, 11, 18, 19, 20`) - 03: Used goods, art, antiques (not accepted, see below) - 04: Investment gold - 05: Travel agencies - 06: Group of entities (not accepted, see below) - 07: Cash basis - 08: Operation subject to another indirect tax — IPSI or IGIC on an IVA line, IPSI or IVA on an IGIC line. It is **not** the general regime of IGIC, which is `01`. - 09: Mediating agencies - 10: Third-party collections - 11: Local rental - 14: VAT pending in certifications (not accepted, see below) - 15: VAT pending successive tract - 17: OSS and IOSS - 18: Equivalence surcharge - 19: REAGYP - 20: Simplified regime **What AEAT requires with each key** (Validaciones VERI*FACTU 3.1.3.15.6), checked on IVA and IGIC lines before the invoice is numbered. Otherwise the request is rejected with `422` and the code in brackets: - `04`: only reverse charge (an `ISP_ART_84_2_*` reason) or an exemption (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `08`: only `exemption_reason: NO_SUJETA_LOCALIZACION`, at 0 % (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `10`: only `exemption_reason: NO_SUJETA_ART_7_9`, on a `STANDARD` invoice whose recipient has a `nif` (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`, `REGIME_KEY_REQUIRES_STANDARD_INVOICE`, `REGIME_KEY_REQUIRES_RECIPIENT_NIF`). - `11` (IVA): a subject line only at 21 %, and no reverse charge (`REGIME_KEY_REQUIRES_VAT_RATE`, `REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `06` and `14` are not accepted (`REGIME_KEY_NOT_SUPPORTED`): AEAT requires with them data the invoice does not carry (a cost-based taxable base; an operation date after the issue date and a public-administration recipient). - `03` (used goods) is not accepted (`REGIME_KEY_NOT_SUPPORTED`): under it the invoice must not show the tax separately (RD 1619/2012, art. 16.2.c), and it always does. The corrective of an invoice that already carried `03` keeps it. - `05` (travel agencies) and `07` (cash basis) are accepted, and the invoice PDF carries the mention of their regime (RD 1619/2012, art. 6.1 n and p). `07`: no reverse charge, no non-subject reason and, of the exemptions, only art. 20 or `OTRO` (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). `GET /v1/tax-types` only offers the keys that are accepted. **One exception to "a key you send is the key you get":** when the line ends up carrying an equivalence surcharge — whether you sent `equivalence_surcharge_rate` or it was inherited from the company's tax configuration — a `01` is rewritten to `18`, because a surcharge under the general regime is fiscally incoherent. Send `equivalence_surcharge_rate: 0` explicitly to keep `01`. See `equivalence_surcharge_rate` in the invoice line for the full rules. - `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_text` string, nullable: Custom exemption text. Only used when `default_exemption_reason` is `OTRO`, where it is mandatory — same rule as in the invoice line. - `apply_equivalence_surcharge` boolean, required: Whether the freelancer is under the equivalence surcharge regime. **Business rule**: If `true`, the `default_equivalence_surcharge` field is REQUIRED. - `default_equivalence_surcharge` number: Default equivalence surcharge, as the configuration holds it. It is what is stored, not what a request accepts (see `EquivalenceSurchargePercentage`): a configuration saved with the `0.625` surcharge of VAT at 5 %, before it was corrected to 0.62, is returned as `0.625` until it is updated. **Business rule**: REQUIRED if `apply_equivalence_surcharge` is `true`. - `apply_irpf` boolean, required: Whether IRPF withholding should be applied to invoices. Defaults to `false`: no withholding is applied until the user declares one (a rate nobody declared is never invented). **Business rule**: If `true` and `irpf_exempt` is `false`, the `default_irpf_rate` field is REQUIRED. - `default_irpf_rate` number: Default IRPF for new invoices, as the configuration holds it. It is what is stored, not what a request accepts (see `IrpfPercentage`): a configuration saved with a rate the table no longer has is returned as it is until it is updated. **Business rule**: REQUIRED if `apply_irpf` is `true` and `irpf_exempt` is `false`. - `irpf_exempt` boolean: Whether the freelancer is exempt from IRPF withholding (e.g., business start). **Note**: When `true`, any provided `default_irpf_rate` is saved but not applied to invoices. This allows pre-configuring the rate for when the exemption ends. - `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_days` integer, nullable: Default payment term in days (0-365). Null means no default term. - `proforma_validity_days` integer, nullable: Default validity term in days for new proformas (0-365). Null means no default: proformas are created without an expiry date. UI-only default: the dashboard uses it to prefill `valid_until` when creating a proforma (issue date + N days, editable). It is never applied server-side, so the public API contract of `valid_until` does not change. - `withholding_options` WithholdingOptions: Withholding rates a company can bear, deduced from the first letter of its NIF. Only individuals pay IRPF (Law 35/2006, art. 8), so no entity bears the rates of individuals (1, 2, 7, 15, and 6, 2.8 and 7.6 in Ceuta and Melilla); any rate an entity cannot bear, on its invoices, products, default configuration or recurring templates, is rejected with `IRPF_RATE_NOT_FOR_CORPORATE_ISSUER`. - **Legal person that pays Corporate Income Tax** (NIF starting with `A`, `B`, `C`, `D`, `F`, `G`, `Q`, `R` or `U`) and **permanent establishment of a non-resident entity** (`W`, which bears the Corporate Income Tax withholding regime, Royal Legislative Decree 5/2004, art. 23.1): only `0`, `19` and `24`. Its income bears withholding only when it is one of those listed in the Corporate Income Tax regulation (Royal Decree 634/2015, art. 60: rents of urban property, image rights, director fees, capital income…), at 19 % or, for image rights, 24 % (art. 66); 19 % is halved to 9.5 for rents of urban property in Ceuta and Melilla. An exempt entity bears none on its exempt income. The suggestion is `0`: a provision of services is not in that list. - **Non-resident entity** (`N`): `0`, `19` and `24`, the Non-Residents Income Tax withholding (Royal Legislative Decree 5/2004, arts. 25.1 a) and 31): 24 %, 19 % if it resides in the European Union or the European Economic Area, 0 if the income is exempt or a tax treaty says so. It depends on facts the NIF does not show: no suggestion. - **State, Autonomous Community or local entity** (`S`, `P`): fully exempt, its income bears no withholding (Law 27/2014, art. 9.1; Royal Decree 634/2015, art. 61): only `0`. - **Individual, or entity whose income is attributed to its members** (`E`): every rate of the IRPF regulation, including the Ceuta and Melilla reduced rates (6, 2.8, 7.6), but not the Corporate Income Tax 9.5. Which one applies depends on the activity and its years, which the NIF does not show, so there is no suggestion. - **Any other NIF** (`H`, `J`, `V`): not restricted, no suggestion. - `allowed_irpf_rates` IrpfPercentage[], required: The rates this company can use, in ascending order. - `suggested_irpf_rate` number, nullable, required: One of `allowed_irpf_rates`. The rate to preselect for this company, or `null` when it depends on facts the NIF does not show and the user has to choose. - `meta` ResponseMeta - `timestamp` string, date-time - `request_id` string ## Other responses - `401`: Missing or invalid authentication. Like every other error, `message`/`detail` is localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English when the header is missing or asks for none of those. - `403`: Authenticated but not allowed. Fourteen causes shared by every operation, told apart by `error.code`; an operation that adds a cause of its own names it in its `403`. You can branch on them exhaustively. - `INSUFFICIENT_SCOPE` — the credential lacks a scope the operation requires; `error.details.missing_scopes` names them as a single comma-separated string (for example `"invoices:write,customers:read"`), not as an array; `required_scopes` has the same shape and lists every scope the operation needs. Retrying will not help: mint a key that holds them. - `COMPANY_READ_ONLY` — the scope is there, but your access level over that NIF only lets you read it. - `ACCOUNT_MANAGEMENT_FORBIDDEN` — the scope is there, but your role over the account, or the management relationship you hold over it, does not cover this operation. - `ACCOUNT_NOT_ACCESSIBLE` — the account is not yours to reach, which is also the answer when it does not exist, so existence is never disclosed. - `ACTIVE_COMPANY_NOT_ACCESSIBLE` — the same, for a NIF: the company in the path, or the one named by `BeeL-Active-Company`, is not one this credential may reach — and again, this is also the answer when it does not exist. - `COMPANY_ACCESS_REVOKED` — your access to the NIF was withdrawn while the request was already in flight, so the write was rejected and nothing was recorded. Retrying will not help until the access is granted again. - `LIVE_CREDENTIAL_REQUIRED` — the operation changes the real account and the call came from a test API key (`beel_sk_test_…`). Use your live key or the dashboard. - `FEATURE_NOT_AVAILABLE` — your subscription does not include the entitlement the operation needs; `error.details.feature_code` names it. This gate runs **before** the scope gate, so for such an operation you never see `INSUFFICIENT_SCOPE` first. - `NO_ACTIVE_ACCOUNT` — the credential does not resolve to an account, so no scope can be evaluated against one. Fail-closed, not a permission that can be granted to you. - `OPERATION_REQUIRES_SESSION` — the operation is available only from the web session; no API key and no OAuth2 token can perform it, whatever scopes it holds. - `OPERATION_REQUIRES_API_KEY` — the reverse: the operation needs a scope that only an API key can hold (such as `accounts:write`), so a dashboard session never satisfies it. - `API_KEY_LIVE_NOT_AVAILABLE` — the call came with a live API key (`beel_sk_live_…`) and the account has no Live mode yet. It is never degraded to Test: use your test key, or activate Live first. - `ACCOUNT_REQUIRES_FOCUS_SWITCH` — dashboard session only: you are a member of the account in the path, but it is not the account in focus. Switch focus to it and retry. - `REQUEST_BLOCKED` — the edge security filter stopped the request before the API saw its body, usually because a text field carries something that looks like markup or a script (HTML tags, `