POST
Create a tax
Company space For: Manager, Accountant · Permission: taxes.create Conditions
  • The tax is created in the fiscal profile of the current company.
  • code must be unique within the profile (organization, country, fiscal status), including taxes that were removed.
  • amount_type percentage requires rate and refuses fixed_amount; fixed requires fixed_amount and refuses rate.
  • rate is between 0 and 999.999999 with at most 6 decimals; fixed_amount is a whole number of minor units, at least 0.
  • For application_scope stockable, default_stockable_price_inclusion_policy is required and default_order_calculation_base is refused; for order it is the other way round.
What else happens
  • Adds a custom tax (kind standard, not built-in) to the profile; it changes no stored price until it is assigned.
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.

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
required

Name of the tax, up to 250 characters.

Maximum string length: 250
code
string
required

Code of the tax, up to 50 characters, unique within the company's fiscal profile.

Maximum string length: 50
amount_type
enum<string>
required

percentage: the tax is a rate (rate required, fixed_amount refused). fixed: the tax is a fixed amount (fixed_amount required, rate refused).

Available options:
percentage,
fixed
default_order_calculation_base
enum<string>
required

Order amount the tax is computed on: items_net_total, items_tax_total or items_gross_total. Required when application_scope is order; not accepted for item-scope taxes.

Available options:
items_net_total,
items_tax_total,
items_gross_total
application_scope
enum<string>
required

stockable: the tax applies to item prices. order: it applies to the whole order. Cannot be changed later.

Available options:
stockable,
order
rate
number | null

Rate of a percentage tax, 0 to 999.999999 with up to 6 decimals. Required when amount_type is percentage; refused when it is fixed.

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

Amount of a fixed tax, a whole number in minor units, at least 0. Required when amount_type is fixed; refused when it is percentage.

Required range: x >= 0
default_stockable_price_inclusion_policy
string

inclusive or exclusive: whether item prices include this tax by default. Required when application_scope is stockable; not accepted for order-scope taxes.

is_active
boolean | null

Whether the tax is active. Defaults to true when omitted.

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).