Tax categories reference
Every calculation component carries a category code. The code tells you what kind of tax it is and how its amount was computed. These are the most common categories — the set grows as new statutory shapes are discovered.
How to read a category code
A category code names the kind of tax (VAT, occupancy, tourism, eco) and its basis — how the amount is derived. The basis suffixes are consistent:
_pct— a percentage of a base amount (usually the room, sometimes the room plus an included tax; see VAT base)._flat— a fixed amount; the basis is per night unless the code says_stay(for exampleentry_flat_stay). The engine derives the basis from the category's underlying definition, not the literal suffix._flat_night— a fixed amount per night._flat_person_night— a fixed amount per guest per night.tier_*/*_tier_*— the amount depends on a band (price band, star rating, or property class). See Tiered & per-person.
Detail
These codes are engine-internal. The dashboard humanizes them for display (for example
tourism_flat_person_night shows as "Tourism / person / night"). You'll see the raw code in the API response's category_code field and the friendly label in the UI.VAT / GST
| Field | Type | Description |
|---|---|---|
| vat_standard | percentage | Standard-rate VAT or GST on the room. The default consumption tax for most accommodation. Recoverable, invoice-grade. |
| vat_reduced | percentage | Reduced-rate VAT applied to accommodation in jurisdictions that give lodging a lower rate than the standard rate (common in the EU). |
| us_sales_pct | percentage | US state/local sales tax on the room, as a percentage. Stacks additively with separate occupancy layers (each US state HOT + city HOT is its own rate). |
| ca_sales_pct | percentage | Canadian GST/HST/PST/QST on the room, as a percentage. Authored per layer (federal GST/HST and provincial PST/QST stack), distinct from the Canadian municipal accommodation tax (occ_pct). |
Detail
There is no separate
vat_exempt category. VAT exemption (for example a bare furnished rental in France absent para-hôtelier services) is an exemption rule attached to a vat_standard / vat_reduced rate — it produces a zero-VAT component flagged as exempt, not omitted. The rate row's category stays vat_standard / vat_reduced; the rule, not a distinct code, carries the exemption.Occupancy taxes
| Field | Type | Description |
|---|---|---|
| occ_pct | percentage | Occupancy tax as a percentage of the room price — US hotel/lodging occupancy taxes, Canadian MAT, and equivalents. |
| occ_flat_night | flat / night | Occupancy tax as a fixed amount per room-night. |
| occ_flat_person_night | flat / person / night | Occupancy tax as a fixed amount per guest per night. Multiplies by chargeable guests (see adults below). |
Tourist / city taxes
| Field | Type | Description |
|---|---|---|
| tourism_pct | percentage | Tourist / city tax as a percentage of the room price. |
| tourism_flat_night | flat / night | Tourist / city tax as a fixed amount per night. |
| tourism_flat_person_night | flat / person / night | The classic per-guest-per-night tourist tax — European taxe de séjour, imposta di soggiorno, and the like. |
| municipal_pct | percentage | Municipal lodging levy as a percentage (city-level, distinct from a regional tourist tax). |
| municipal_flat | flat / night | Municipal lodging levy as a fixed amount per room-night. Despite the bare _flat suffix, the basis is per night — the engine multiplies by nights. |
| entry_flat_stay | flat / stay | A flat entry/visitor charge applied once per stay. Note: one-time border levies paid on entering a region are out of scope and never fire on a per-night room calc — see Limitations. |
| entry_flat_person_stay | flat / person / stay | A flat entry/visitor accommodation charge per person per stay. Note: one-time border levies paid on entering a region are out of scope — see Limitations. |
Eco, climate & sustainability levies
| Field | Type | Description |
|---|---|---|
| eco_flat_person_night | flat / person / night | Environmental levy per guest per night. |
| eco_pct | percentage | Environmental / ecological levy as a percentage of the room price. |
| climate_tier_star | tiered (by stars) | Climate levy banded by the property's star rating. |
| green_flat_night | flat / night | Green/environmental fee per night. |
| sustainability_flat_night | flat / night | Sustainability charge per night. |
Fees & commission
| Field | Type | Description |
|---|---|---|
| service_pct | percentage | A service charge expressed as a percentage of the room price. |
| resort_fee_tax | percentage / flat | Tax assessed specifically on a resort fee line item (where the jurisdiction taxes it separately). |
| cleaning_fee_tax | percentage / flat | Tax assessed on a cleaning fee line item. |
| service_fee_tax | percentage / flat | Tax assessed on a service fee line item. |
| commission_tax | percentage | VAT on the OTA / intermediary commission line. Carries the EU cross-border reverse-charge treatment (category AE) when applicable — never the room. |
Tiered categories
| Field | Type | Description |
|---|---|---|
| tier_price | tiered (by price) | Amount depends on which price band the nightly rate falls into (e.g. Japanese city taxes). |
| tier_star | tiered (by stars) | Amount depends on the property's star rating. A booking with no star rating routes to a conservative floor band. |
Note
Some categories combine a basis with a tier (for example
climate_tier_star). The tier suffix tells you what the band keys on; the engine resolves the band per booking. Distinct from the category code is the rate-level tier_type discriminator — property_class (the dominant live shape), single_amount, threshold, or marginal_rate — which selects the banding logic; the actual per-tier fields are value, rate, min, max, star_rating, and property_class. See Tiered & per-person taxes for the matching rules.The list grows
New category codes are added as new statutory shapes are discovered. Any code not in the override map above is shown title-cased from its snake_case form — so an unfamiliar code is still readable. If you build automation against category_code, key off the basis suffix (_pct, _flat_person_night, …) rather than enumerating a fixed set. To see what's relevant for invoicing, see VAT-only invoicing — only VAT-class categories are recoverable tax on the e-invoice.