PUT
Change a tax
Company space For: Manager, Accountant · Permission: taxes.update Conditions
  • Built-in taxes cannot be changed.
  • Only the amount that matches the tax’s amount_type can be sent (rate for a percentage tax, fixed_amount for a fixed one) and it cannot be cleared; the other amount is refused.
  • default_stockable_price_inclusion_policy is accepted only for item-scope taxes and default_order_calculation_base only for order-scope taxes; the other is refused.
  • code, amount_type and application_scope cannot be changed.
  • A tax cannot be deactivated while an order selects it (order scope), while a category or item assigns it (item scope), or while an assigned tax depends on it.
  • The change is refused when the resulting tax graph is invalid or when it would make a stored price impossible to calculate.
What else happens
  • Changes the tax for every company of the same fiscal profile; later calculations use the new values and stored prices are re-checked but not rewritten.
Part of Set up VAT and the other taxes.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

tax
string
required

Identifier of the tax (27-character KSUID string), within the current company's fiscal profile.

Query Parameters

response
enum<string>
default:none

Response mode. Default none; none answers 204 No Content.

Available options:
none,
resource
fields
string

Comma-separated JSON keys of the root resource (id is always rendered). Available: id, country_code, fiscal_status, kind, is_builtin, name, code, amount_type, rate, fixed_amount, default_stockable_price_inclusion_policy, default_order_calculation_base, application_scope, is_active, dependencies, created_at, updated_at.

include
string

Comma-separated include paths, each optionally followed by its fields in parentheses: units(id,sku),units.uomUnit(id,name). Max depth 6, max 40 paths. Available: .

Body

application/json
name
string | null

New name, up to 250 characters. Unchanged when omitted or null.

Maximum string length: 250
rate
number

New rate of a percentage tax, 0 to 999.999999 with up to 6 decimals. Refused for a fixed tax. When sent it cannot be empty.

Required range: 0 <= x <= 999.999999
fixed_amount
integer

New amount of a fixed tax, in minor units, at least 0. Refused for a percentage tax; cannot be cleared.

Required range: x >= 0
default_stockable_price_inclusion_policy
string

New default inclusion, inclusive or exclusive. Accepted only for item-scope taxes.

default_order_calculation_base
enum<string>

New order amount the tax is computed on (items_net_total, items_tax_total or items_gross_total). Accepted only for order-scope taxes.

Available options:
items_net_total,
items_tax_total,
items_gross_total
is_active
boolean | null

Activates or deactivates the tax. Deactivation is refused while the tax is in use.

Response

Resource (only with response=resource).

id

Identifier of the tax (27-character KSUID string).

country_code

Country of the fiscal profile the tax belongs to (the company's country).

fiscal_status

Fiscal status of the profile the tax belongs to.

kind

vat: the system VAT node of the profile. standard: any other tax.

is_builtin
boolean

True for taxes created by the system; they cannot be changed or deleted.

name

Name of the tax.

code

Unique code of the tax within its fiscal profile.

amount_type

percentage: the tax is a rate applied on a base. fixed: the tax is a fixed amount.

rate

Rate of a percentage tax, up to 6 decimals, sent as a decimal string; null for a fixed tax and for the VAT node, whose rates are VAT rates.

fixed_amount
integer | null

Amount of a fixed tax, in minor units (divide by 10 to the power currency_exponent); null for a percentage tax.

default_stockable_price_inclusion_policy

For item-scope taxes: whether prices include the tax by default (inclusive) or add it on top (exclusive). Null for order-scope taxes.

default_order_calculation_base

For order-scope taxes: the order amount the tax is computed on (items_net_total, items_tax_total or items_gross_total). Null for item-scope taxes.

application_scope

stockable: applied to item prices. order: applied to the whole order.

is_active
boolean

Whether the tax can still be used; an inactive tax is not applied to new assignments.

dependencies
any[]

Taxes this tax is calculated on top of: a list of tax_id and operator (add or substract). Present when the dependency links are loaded.

created_at

Date and time the record was created (ISO 8601, UTC).

updated_at

Date and time the record was last changed (ISO 8601, UTC).