How a calculation works
Follow one request from input to itemized result, then try it live against your own session.
What you give it
A calculation needs to know two things: where the stay is and what the stay is. Location is either a jurisdiction code (IT-RM-ROM) or coordinates (lat/lng, which TaxLens reverse-geocodes to a jurisdiction). The stay is the date, number of nights, nightly rate, and currency — plus optional details (property type, star rating, guest counts, channel) that let more specific rules fire.
{
"jurisdiction_code": "IT-RM-ROM",
"stay_date": "2026-07-01",
"nights": 3,
"nightly_rate": 200,
"currency": "EUR",
"property_type": "hotel"
}What the engine does
Internally, TaxLens:
- resolves the jurisdiction and walks its ancestor chain (city → region → country);
- collects every active tax rate attached anywhere on that chain that matches the booking and the stay date;
- evaluates the rules bound to those rates — applying exemptions, overrides, caps, surcharges, and reductions;
- computes each surviving tax on its correct base and stacks the results.
What you get back
The response is an itemized breakdown: a tax_breakdown with one component per tax (its name, category, rate, base, amount, and the jurisdiction it came from), a total, an effective rate, and the full list of rules that were evaluated.
{
"jurisdiction": { "code": "IT-RM-ROM", "name": "Rome" },
"tax_breakdown": {
"components": [
{ "name": "Italy VAT", "category_code": "vat_reduced", "rate": 0.10,
"rate_type": "percentage",
"taxable_amount": 600, "tax_amount": 60.0, "jurisdiction_code": "IT" },
{ "name": "Rome tourist tax", "category_code": "tourism_flat_person_night",
"rate_type": "flat", "tax_amount": 18.0, "jurisdiction_code": "IT-RM-ROM" }
],
"total_tax": 78.0,
"effective_rate": 0.13
},
"total_with_tax": 678.0,
"rules_applied": [ /* … each rule + applied/exempted/skipped */ ]
}10% × €600 = €60.00. The Rome tourist tax is a separate, guest-borne flat amount per person per night that sits outside the VAT base — the per-night figure above is illustrative. Some other jurisdictions (Spain, Germany, the Netherlands) instead fold the tourist tax into the VAT base, so the engine composes them differently; see Layered & additive stacking.Try it live
This is the real engine, calling /v1/tax/calculate with your session. Pick a preset or edit the inputs — nothing is saved.
Pick a preset or enter a stay, then Calculate.
When you're ready to do this from code, head to Calculate tax (API). To turn a calculation into a booking and an invoice, see The invoice lifecycle.