Company-owned taxes

9 October 2026 — Taxes now come in two kinds. The Factuarea catalog (global) is shared by every company and is read-only, and each company can create its own taxes (company), visible only to that company. Defaults are chosen per company, so choosing a default never changes what other companies see.

• Your own taxes — Create a tax creates a tax owned by the company of the API key. You can edit it with Update a tax, switch it with Toggle tax active state and remove it with Delete a tax.
• A new ownership field — every tax in the responses carries ownership: global (Factuarea catalog) or company (created by your company). List all taxes accepts ownership=global or ownership=company; omit it to list both. Any other value answers 422 with error.param set to ownership.
• Visibility — you see the global catalog and your own taxes. A tax owned by another company answers 404 tax_not_found, exactly like one that does not exist.
• Codes — a tax code must be unique among the global catalog and your own taxes (409 tax_code_already_exists otherwise). Other companies can use the same code.
• Defaults per company — Mark a tax as the default for its type and Set tax default for a document type work on any visible tax and only change the company of the API key. Without a document, set-default writes only in the compatible documents where that tax category (VAT, retention or surcharge) is switched on for your company. is_default and default_for_documents are always the effective defaults of your company, and default_for_documents is also accepted when you create or update a tax. recurring_invoice inherits the default of invoice.
• Usage check — Check whether a tax is in use counts only the documents, products, contacts and defaults of your company. used_by adds supplier_profiles (supplier profiles with the tax as their default) and recurring_invoices (recurring templates with a line that uses it, each counted once), documents company_tax_defaults, and total_count sums the nine counters. The MCP tool check_tax_in_use returns the same keys.
• Webhooks — the tax.metadata_changed, tax.validity_changed and tax.external_reference_changed events are delivered for the taxes owned by your company. Catalog taxes do not emit events.
• MCP — two new tools, update_tax (taxes:write) and delete_tax (taxes:delete, irreversible, so it accepts idempotency_key). search_taxes returns ownership and filters by it. The OAuth scope taxes.delete, which maps to taxes:delete, lets an OAuth client use delete_tax.

Error codes

• global_tax_read_only (403) — you tried to change, toggle or delete a tax of the Factuarea catalog. Create your own tax or set your company defaults instead.
• tax_not_defaultable_for_document (422) — the tax cannot be the default of that document: its type is other, its applies_to does not cover the document, or the document is recurring_invoice.
• tax_default_axis_disabled (422, business_rule_violation) — the tax category (VAT, retention or surcharge) is switched off for your company in the requested document, or in every document set-default would write to. Returned by create, update, set-default and set-default/{docType}. Switch the category on in the company settings or pick a document where it is on.

The first two codes replace custom_tax_creation_disabled and system_tax_default_modification_forbidden, which the API no longer returns. system_tax_immutable_field, system_tax_undeletable, tax_in_use and tax_inactive_cannot_be_default keep their meaning. See the error catalog.

All the operations already existed. Their scopes are unchanged.