Tax rules define the tax rates applied to charges based on jurisdiction, product category, and customer location. Kontorion evaluates tax rules at invoicing time and adds the appropriate tax line items to each invoice.
Key concepts:
- Jurisdiction - country and optional region the rule applies to
- Tax type -
vat,sales_tax,gst,hst, etc. - Inclusive vs. exclusive - whether the tax is included in the listed price or added on top
- Compound tax - whether this tax is calculated on the pre-tax amount or on the amount including other taxes
- Apply order - controls the sequence when multiple tax rules apply
List tax rules
Lists tax rules with cursor-based pagination and the unified field.op=value filter grammar.
query Parameters
limitPage size
cursorPagination cursor
jurisdiction_countryFilter by jurisdiction country (eq/in)
jurisdiction_regionFilter by jurisdiction region (eq/ne/in)
tax_typeFilter by tax type (eq/in)
statusFilter by status (eq/ne/in)
rateFilter by rate (eq/ne/gt/gte/lt/lte)
valid_fromFilter by valid_from (eq/gt/gte/lt/lte)
valid_toFilter by valid_to (eq/gt/gte/lt/lte)
created_atFilter by created_at (eq/gt/gte/lt/lte)
List tax rules › Responses
Paginated list wrapped in data envelope
applies_to_customer_typesOptional discriminators. Empty/nil means "applies to all" - wildcard semantics let EU VAT rules (which leave these unset) keep working while non-EU sales-tax rules can scope themselves to specific buyer types, product categories, or supply types.
applies_to_product_categoriesapplies_to_supply_typesapply_orderarchived_atcreated_atidinclusiveis_compoundjurisdiction_countryjurisdiction_regionorganization_idpublished_atpublished_byraterequires_continuous_coveragestatustax_typeupdated_atvalid_fromValidFrom / ValidTo are plain dates (no clock, no zone). Tax law boundaries land on calendar days in the relevant jurisdiction; attaching a time-of-day to "this rate applies from 2024-06-15" silently shifts the day in non-UTC zones (Unified Date/Time plan, Layer 10). Postgres column type is DATE.
valid_toversionCreate a tax rule
Creates a new tax rule for the organization
Create a tax rule › Request Body
applies_to_customer_typesapplies_to_product_categoriesapplies_to_supply_typesapply_orderinclusiveis_compoundjurisdiction_countryjurisdiction_regionraterequires_continuous_coveragetax_typevalid_fromvalid_toCreate a tax rule › Responses
Wrapped in data envelope
applies_to_customer_typesOptional discriminators. Empty/nil means "applies to all" - wildcard semantics let EU VAT rules (which leave these unset) keep working while non-EU sales-tax rules can scope themselves to specific buyer types, product categories, or supply types.
applies_to_product_categoriesapplies_to_supply_typesapply_orderarchived_atcreated_atidinclusiveis_compoundjurisdiction_countryjurisdiction_regionorganization_idpublished_atpublished_byraterequires_continuous_coveragestatustax_typeupdated_atvalid_fromValidFrom / ValidTo are plain dates (no clock, no zone). Tax law boundaries land on calendar days in the relevant jurisdiction; attaching a time-of-day to "this rate applies from 2024-06-15" silently shifts the day in non-UTC zones (Unified Date/Time plan, Layer 10). Postgres column type is DATE.
valid_toversionGet a tax rule by ID
Returns a single tax rule
path Parameters
idTax Rule UUID
Get a tax rule by ID › Responses
Wrapped in data envelope
applies_to_customer_typesOptional discriminators. Empty/nil means "applies to all" - wildcard semantics let EU VAT rules (which leave these unset) keep working while non-EU sales-tax rules can scope themselves to specific buyer types, product categories, or supply types.
applies_to_product_categoriesapplies_to_supply_typesapply_orderarchived_atcreated_atidinclusiveis_compoundjurisdiction_countryjurisdiction_regionorganization_idpublished_atpublished_byraterequires_continuous_coveragestatustax_typeupdated_atvalid_fromValidFrom / ValidTo are plain dates (no clock, no zone). Tax law boundaries land on calendar days in the relevant jurisdiction; attaching a time-of-day to "this rate applies from 2024-06-15" silently shifts the day in non-UTC zones (Unified Date/Time plan, Layer 10). Postgres column type is DATE.
valid_toversionUpdate a tax rule
Updates an existing tax rule
path Parameters
idTax Rule UUID
Update a tax rule › Request Body
applies_to_customer_typesnil means "no change". Empty slice means "clear filter / wildcard".
applies_to_product_categoriesapplies_to_supply_typesapply_ordereffective_atADR-0006 edit-as-publish controls.
inclusiveis_compoundjurisdiction_countryjurisdiction_regionraterequires_continuous_coveragesave_as_draftstatustax_typevalid_fromvalid_toUpdate a tax rule › Responses
Wrapped in data envelope
applies_to_customer_typesOptional discriminators. Empty/nil means "applies to all" - wildcard semantics let EU VAT rules (which leave these unset) keep working while non-EU sales-tax rules can scope themselves to specific buyer types, product categories, or supply types.
applies_to_product_categoriesapplies_to_supply_typesapply_orderarchived_atcreated_atidinclusiveis_compoundjurisdiction_countryjurisdiction_regionorganization_idpublished_atpublished_byraterequires_continuous_coveragestatustax_typeupdated_atvalid_fromValidFrom / ValidTo are plain dates (no clock, no zone). Tax law boundaries land on calendar days in the relevant jurisdiction; attaching a time-of-day to "this rate applies from 2024-06-15" silently shifts the day in non-UTC zones (Unified Date/Time plan, Layer 10). Postgres column type is DATE.
valid_toversionCopy a tax rule version as a new draft
Creates a new draft tax rule version seeded from the supplied source version. Use to iterate on rates or jurisdiction logic without disturbing the active version.
path Parameters
idSource tax rule version ID (UUID)
Copy a tax rule version as a new draft › Responses
Newly created draft version
applies_to_customer_typesOptional discriminators. Empty/nil means "applies to all" - wildcard semantics let EU VAT rules (which leave these unset) keep working while non-EU sales-tax rules can scope themselves to specific buyer types, product categories, or supply types.
applies_to_product_categoriesapplies_to_supply_typesapply_orderarchived_atcreated_atidinclusiveis_compoundjurisdiction_countryjurisdiction_regionorganization_idpublished_atpublished_byraterequires_continuous_coveragestatustax_typeupdated_atvalid_fromValidFrom / ValidTo are plain dates (no clock, no zone). Tax law boundaries land on calendar days in the relevant jurisdiction; attaching a time-of-day to "this rate applies from 2024-06-15" silently shifts the day in non-UTC zones (Unified Date/Time plan, Layer 10). Postgres column type is DATE.
valid_toversion