List the tax types allowed in Spain

Returns the tax regimes and percentages that BeeL accepts on an invoice. Use it to validate a rate before sending it, or to build your own picker instead of hard-coding the percentages.

Contents: VAT (mainland), IGIC (Canary Islands), IPSI (Ceuta and Melilla), the withholding (IRPF) percentages, the equivalence surcharge that corresponds to each VAT rate, and the exemption reasons with the classification each one implies.
Scope: the catalogue is the same for every credential and does not depend on any account or on any NIF, so the operation takes no identifier and works before the first NIF exists.

VAT rates and the zero case

VAT lists 2, 4, 5, 7.5, 10 and 21, and deliberately not 0: under VAT (and IPSI) a 0 % is not a rate but the exemption/non-subject sentinel, and on its own it says nothing. A 0 % line is only valid together with an exemption_reason, which this same response publishes under exemption_reasons.
IGIC does list 0: there it is the real "Tipo Cero" and needs no reason.
Temporary VAT rates carry their period: 5 % (2022-07-01 to 2024-09-30), and 2 % and 7.5 % (2024-10-01 to 2024-12-31) are listed with valid_from / valid_until. They no longer apply to new operations but stay listed, because correctives and late filings for those periods still need them; an invoice whose operation date falls outside the period is rejected with 422 VAT_RATE_NOT_ACCEPTED_ON_DATE. Every other rate has both null.
Equivalence surcharges are listed per VAT ↔ surcharge pair, each with its period.

Authorization

AuthorizationBearer <token>

Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key short of the scope an operation needs is answered 403. The scope an operation requires is shown next to its title, and the full catalogue lives in the Scopes reference.

Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.

In: header

Response Body

application/json

curl -X GET "https://app.beel.es/api/v1/tax-types"

curl -X GET "https://app.beel.es/api/v1/tax-types"

{
  "success": true,
  "data": {
    "tax_regimes": [
      {
        "code": "IVA",
        "name": "IVA",
        "description": "Value Added Tax",
        "tax_rates": [
          {
            "percentage": 21,
            "description": "IVA (21%)",
            "active": true,
            "associated_equivalence_surcharge": 5.2,
            "valid_from": null,
            "valid_until": null
          }
        ],
        "applies_equivalence_surcharge": true,
        "regime_keys": [
          {
            "code": "01",
            "description": "General regime operation"
          }
        ]
      }
    ],
    "irpf_types": [
      {
        "percentage": 15,
        "description": "IRPF Profesional (15%)",
        "active": true
      }
    ],
    "equivalence_surcharges": [
      {
        "percentage": 5.2,
        "associated_vat": 21,
        "description": "RE 5.2% (IVA 21%)",
        "active": true,
        "valid_from": null,
        "valid_until": null
      }
    ],
    "exemption_reasons": [
      {
        "code": "EXENTA_ART_20",
        "label": "invoice.exemption.EXENTA_ART_20",
        "description": "invoice.exemption.EXENTA_ART_20",
        "category": "OPERACIONES EXENTAS",
        "classification_type": "EXENTA",
        "available_as_default": false,
        "available_on_invoice_line": true
      }
    ]
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The parameter 'invoice_id' has an invalid type. Expected: UUID.",
    "details": {
      "field": "invoice_id",
      "invalid_value": "deliveries",
      "expected_format": "UUID"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again in 60 seconds."
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Unsupported media type: text/plain. Supported: application/json"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

List the tax types allowed in Spain

VAT rates and the zero case

Authorization

Response Body

200application/json

400application/json

401application/json

403application/json

429application/json

500application/json

defaultapplication/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json