---
title: "Update a tax"
method: PATCH
path: "/companies/{company}/taxes/{tax}"
tags: ["Taxes"]
---

# Update a tax

`PATCH /companies/{company}/taxes/{tax}`

## Request

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

Partial update of a tax owned by your company. System taxes (is_system=true) respond 422 `system_tax_immutable_field` when a definition field changes; any other change to the global catalog (for example `is_active`) responds 403 `global_tax_read_only`. `default_for_documents` is accepted on any visible tax and writes your company's defaults only.

## Path parameters

- `company` string, uuid, required
- `tax` string, uuid, required

## Headers

- `Idempotency-Key` string
- `Factuarea-Version` string, date

## Request body

- UpdateTaxRequest
  - `name` string
  - `code` string
  - `rate` number
  - `applies_to` 'sale' | 'purchase' | 'both'
  - `country` string, nullable
  - `description` string, nullable
  - `is_active` boolean
  - `customer_visible_label` string, nullable: Custom label for this tax shown to the customer on documents (e.g. "IVA 21% incluido"). Up to 200 characters.
  - `external_reference` string, nullable
  - `valid_from` string, date, nullable
  - `valid_until` string, date, nullable: End date of the tax validity window (`YYYY-MM-DD`). Must be on or after `valid_from`.
  - `reverse_charge` boolean
  - `country_aeat_zone` 'peninsula' | 'canarias' | 'ceuta' | 'melilla' | 'null', nullable
  - `linked_surcharge_taxes_id` string, nullable: FK to the linked equivalence-surcharge tax; `null` unlinks it. UUID v7 value referencing the Factuarea catalog plus your company's own taxes.
  - `metadata` Metadata, nullable: A free map of up to 50 key→value pairs for storing arbitrary structured data (values are strings up to 500 characters). Unlike `custom_fields` — an ordered list of typed `{field, value}` pairs with display semantics, present on the six document resources — `metadata` is an unordered map for opaque integration data; a document may carry both. The master resources (Client, Supplier) have no `custom_fields`, so their `metadata` doubles as the custom-fields store. **Reserved keys (read-only).** When the system auto-issues an invoice from a payment correlation (Stripe/GoCardless/MONEI), it writes `stripe_subscription_id`, `stripe_invoice_id`, `billing_reason`, `period_start` and `period_end` into that invoice metadata automatically. Do not set or overwrite them by hand — the platform owns them and a manual value may be replaced when the correlation runs.
  - `default_for_documents` object: Sets this tax as the default per document type. Object with optional booleans: `invoice`, `quote`, `delivery_note`, `proforma`, `purchase_invoice`, `recurring_invoice`.
    - `invoice` boolean
    - `quote` boolean
    - `delivery_note` boolean
    - `proforma` boolean
    - `purchase_invoice` boolean
    - `recurring_invoice` boolean

## Response `200`

- object
  - `data` Tax, required: A tax rate configuration. Catalog partially global (`is_system=true` for system taxes, without `company_id`) and partially custom per company.
    - `id` string, required
    - `object` 'tax', required
    - `name` string, required: Human-readable name of the tax (e.g. "IVA 21%").
    - `code` string, required: Short tax code (e.g. "IVA21").
    - `rate` number, float, required: Applied tax rate, e.g. `21` for 21% VAT.
    - `type` 'vat' | 'retention' | 'surcharge' | 'other', required: Tax category: `vat` (VAT), `retention` (IRPF withholding), `surcharge` (equivalence surcharge), `other`.
    - `applies_to` 'sales' | 'purchases' | 'both', required: Scope where it applies: `sales` (sales only), `purchases` (purchases only), `both` (both).
    - `country` string, nullable, required: ISO 3166-1 alpha-2 country code (e.g. `ES`).
    - `is_default` boolean, required: true if this is the default tax for its `type` (independent of the `default_for_documents` map).
    - `is_active` boolean, required: Indicates whether the tax is enabled for use on new documents.
    - `is_system` boolean, required: true if the tax is from the global system catalog (not editable, without `company_id`).
    - `ownership` 'global' | 'company', required: Who owns the tax: `global` (Factuarea catalog, read-only for companies) or `company` (a tax created by your company, which only your company sees and can edit or delete).
    - `description` string, nullable, required: Free-text description of the tax.
    - `default_for_documents` object, required: Map `DocumentType -> bool` indicating for which document types this tax is default. Replaces the 5 legacy booleans `is_default_invoice/quote/delivery_note/proforma/purchase_invoice`.
      - `invoice` boolean, required
      - `quote` boolean, required
      - `delivery_note` boolean, required
      - `proforma` boolean, required
      - `purchase_invoice` boolean, required
      - `recurring_invoice` boolean, required
    - `customer_visible_label` string, nullable, required: Tax label shown to the end customer on documents (PDF, public link, email).
    - `external_reference` 'S1' | 'S2' | 'S3' | 'E1' | 'E2' | 'E3' | 'E4' | 'E5' | 'E6' | 'N1' | 'N2' | 'null', nullable, required: AEAT-SII / VeriFactu key (closed catalog: S1..S3 subject, E1..E6 exempt, N1..N2 not subject).
    - `valid_from` string, date, nullable, required: Legal effective start date of the rate (BOE). Format `YYYY-MM-DD`.
    - `valid_until` string, date, nullable, required: Legal effective end date of the rate. Invariant: `valid_until >= valid_from` when both are non-null.
    - `reverse_charge` boolean, required: Reverse charge (Art. 84.Uno.2º LIVA). Default `false`.
    - `country_aeat_zone` 'peninsula' | 'canarias' | 'ceuta' | 'melilla' | 'null', nullable, required: AEAT tax zone: `peninsula` (including the Balearic Islands), `canarias` (IGIC), `ceuta` (IPSI) or `melilla` (IPSI).
    - `indirect_tax_regime` 'iva' | 'igic' | 'ipsi' | 'null', nullable, required: Indirect tax regime DERIVED from the AEAT zone, read-only: `iva` (Península), `igic` (Canarias), `ipsi` (Ceuta/Melilla). Only set for `type=vat`; `null` otherwise.
    - `linked_surcharge_taxes_id` string, nullable, required: Identity (UUID v7) of the linked equivalence-surcharge tax. Foreign key to the global `taxes` table (key suffix `_taxes_id` per the UUID policy). `null` when there is no link.
    - `metadata` Metadata, nullable, required: A free map of up to 50 key→value pairs for storing arbitrary structured data (values are strings up to 500 characters). Unlike `custom_fields` — an ordered list of typed `{field, value}` pairs with display semantics, present on the six document resources — `metadata` is an unordered map for opaque integration data; a document may carry both. The master resources (Client, Supplier) have no `custom_fields`, so their `metadata` doubles as the custom-fields store. **Reserved keys (read-only).** When the system auto-issues an invoice from a payment correlation (Stripe/GoCardless/MONEI), it writes `stripe_subscription_id`, `stripe_invoice_id`, `billing_reason`, `period_start` and `period_end` into that invoice metadata automatically. Do not set or overwrite them by hand — the platform owns them and a manual value may be replaced when the correlation runs.
    - `created_at` string, date-time, nullable, required
    - `updated_at` string, date-time, nullable, required

## Other responses

- `400`: `parameter_unknown` with `subcode` `retired_active_profile_header`: the retired `X-Active-Profile` header was sent; the company goes in the path. `parameter_invalid_format` on `Factuarea-Version`: the header is not a `YYYY-MM-DD` date. `unsupported_api_version`: the `Factuarea-Version` date is not a supported version.
- `401`: Missing or invalid API key.
- `403`: The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).
- `404`: The requested resource does not exist or belongs to another company.
- `409`: The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `tax_code_already_exists`: the `code` is already used by a tax of the Factuarea catalog or by another tax of the company. Other companies may reuse it.
- `422`: Validation failed. The `error.param` field identifies which input is invalid.
- `429`: Rate limit exceeded. Retry after the duration in `Retry-After`.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/factuarea/apis/factuarea-public-api.md) · [All operations](https://skmtc.dev/factuarea/apis/factuarea-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/factuarea/apis/factuarea-public-api/revisions/718e77934422?raw)