Taxes

List all taxes

List the taxes visible to your company: the global platform catalog (Spanish IVA, IRPF, recargo, etc.) plus the taxes your company created. Each tax carries ownership (global or company) and can be filtered by it. is_default and default_for_documents reflect your company's effective defaults, not other companies'.

get/companies/{company}/taxes

Request

Base URL: https://api.factuarea.com/v1
URL: https://api.factuarea.com/v1/companies/{company}/taxes
Auth: one of:
- HTTP bearer
- API key in header X-API-Key

Path parameters

companystring uuid required

Public identifier (UUID v7) of the company. Get it from GET /v1/me (data.scope[].id).

Query parameters

limitinteger

Number of objects to return, between 1 and 100 (default 25).

starting_afterstring uuid

Cursor for forward pagination: pass the id of the last object on the previous page (the next_cursor of the previous response).

ending_beforestring uuid

Cursor for backward pagination: pass the id of the first object on the current page.

typestring

Tax type: vat, retention, surcharge, other. Exact match on type.

type[in]string

Comma-separated list of values (CSV).

Tax type: vat, retention, surcharge, other. Comma-separated list. Any of the values matches.

is_activeboolean

Filter active / inactive taxes. Exact match on is_active.

is_defaultboolean

Filter taxes that are your company's effective default (the tax your company proposes by default for the document). Exact match on is_default.

applies_tostring

Scope: sales, purchases, both. Exact match on applies_to.

applies_to[in]string

Comma-separated list of values (CSV).

Scope: sales, purchases, both. Comma-separated list. Any of the values matches.

countrystring

ISO 3166-1 alpha-2 country code. Exact match on country.

codestring

Short tax code (exact match). Exact match on code.

searchstring

Escaped LIKE search over name and code (limit 80 chars). Exact match on search.

external_referencestring

Exact AEAT key: S1..S3, E1..E6, N1..N2. Exact match on external_reference.

external_reference[in]string

Comma-separated list of values (CSV).

Exact AEAT key: S1..S3, E1..E6, N1..N2. Comma-separated list. Any of the values matches.

is_systemboolean

Filter the protected canonical taxes of the Factuarea catalog (true) vs the rest (false). To tell the global catalog from your own taxes use ownership. Exact match on is_system.

ownershipstring

Whose taxes to list: global (the read-only Factuarea catalog) or company (your own). Omit it to list both. Any other value responds 422. Exact match on ownership.

country_aeat_zonestring

AEAT fiscal zone: peninsula, canarias, ceuta, melilla. Exact match on country_aeat_zone.

indirect_tax_regimestring

Indirect tax regime DERIVED from the AEAT zone: iva, igic, ipsi. Translated to the equivalent zone filter. Exact match on indirect_tax_regime.

Headers

Factuarea-Versionstring date

Example:2026-06-01

Pin the API version (YYYY-MM-DD, Stripe-style date versioning) for this request; omit to use the key's pinned version, or the latest if none. Unsupported version → 400 unsupported_api_version; malformed → 400 parameter_invalid_format. The effective version is echoed in the Factuarea-Version response header. See the Versioning guide.

Response

has_moreboolean required

Whether more pages are available after this one.

next_cursorstring nullable required

Opaque cursor for the next page, or null when has_more is false. The example below shows the shape used by most listings; others return a different one, so pass the value back verbatim instead of validating it.

Example response

{
  "data": [
    {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f",
      "object": "tax",
      "name": "IVA general 21%",
      "code": "IVA21",
      "rate": 21,
      "type": "vat",
      "applies_to": "both",
      "country": "ES",
      "is_default": true,
      "is_active": true,
      "is_system": true,
      "ownership": "global",
      "description": "IVA general aplicable en territorio peninsular y Baleares.",
      "default_for_documents": {
        "invoice": true,
        "quote": true,
        "delivery_note": true,
        "proforma": true,
        "purchase_invoice": true,
        "recurring_invoice": true
      },
      "customer_visible_label": "IVA 21%",
      "external_reference": "S1",
      "valid_from": "2012-09-01",
      "country_aeat_zone": "peninsula",
      "indirect_tax_regime": "iva",
      "linked_surcharge_taxes_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10",
      "metadata": {
        "erp_code": "IVA-GEN",
        "ledger_account": "477000"
      },
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c"
}

Changes

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