Coverage and unknowns
The twelve countries a release covers, how much of each, and how a quote or resolve answer says what it can't price instead of guessing.
A release covers twelve countries, but not every town in them. Where the data stops, the calculator says so: the answer lists what it can't price in unknowns, and a quote with any unknown is partial. It never prices a charge it has no rate for.
The countries
| Country | Id | Currency | Levels that levy charges |
|---|---|---|---|
| Austria | at | EUR | region, municipality, association |
| Bulgaria | bg | EUR | municipality |
| Croatia | hr | EUR | region, municipality |
| Cyprus | cy | EUR | country |
| Czechia | cz | CZK | municipality |
| France | fr | EUR | country, region, municipality, association |
| Germany | de | EUR | municipality |
| Greece | gr | EUR | country |
| Italy | it | EUR | municipality |
| Portugal | pt | EUR | municipality |
| Romania | ro | RON | municipality |
| Spain | es | EUR | region |
The levels are where the country's law lets charges be levied, and so where the release has to look. In Spain the regions levy them; Barcelona's surcharge is levied under Catalan law. Cyprus's file has no charges: the release found none levied there.
A country's file comes with the licence for it. Tokens and HTTP delivery covers which files a token can fetch.
How much is covered
Each country's entry in the manifest carries coverage:
| Field | Meaning |
|---|---|
nightsShare | The share of the country's tourist nights spent in the places the release has researched, in basis points: 2893 is 28.93%. |
source | Where the nights figures come from. |
year | The year of those figures. |
It is a measure of how often a real stay lands somewhere the release knows, not of how many towns it lists. It changes from release to release, so read it from the manifest you have rather than from these docs.
Unknowns
Each unknown has a reason and an English text. Depending on the reason, it also names the charge and version, the room, or the level:
| Reason | Carries | What it means | What to do |
|---|---|---|---|
jurisdiction_not_researched | level | No jurisdiction at this level of the place's chain has been researched, so a charge levied there may be missing. | Nothing on your side: the release doesn't cover the place yet. |
type_unknown | charge, version | The rate depends on the property type and the place gives none. | Add type to the place. |
class_unknown | charge, version | The rate depends on the property class and the place gives none. | Add class to the place. |
zone_unresolved | charge, version | The rate depends on a zone or member area inside the place, and the place doesn't name it. | Name the zone's jurisdiction id as the place. |
unpriced_rule | charge, version | The release has found the rule but can't price it. text gives the reason and the rule in brief. | Price it by hand from the evidence, or leave it to the hotel. |
currency_mismatch | room, charge, version | A price-based charge is in another currency than the room price. The calculator never converts. | Send the price in the charge's currency. |
vat_unknown | room, charge, version | A price-based charge needs the accommodation VAT rate, and the release has none in force that night. | Send vatBps. |
resolve returns the same unknowns for a place and date, less the two about a room's price.
Treat a reason you don't recognise as an unknown too. The list can grow.
Partial or price required
| Status | Unknowns | What it means |
|---|---|---|
partial | At least one | Something that may apply couldn't be priced. The totals leave it out. |
price_required | None | Everything is known, but a charge needs the room price. Quote again with price on the room. |
complete | None | Every charge that applies is in the lines. |
Don't show a partial total as the tax due. Show the lines you have and say what is missing, from text or your own wording for each reason.
Examples
No type or class
The quickstart stay in Barcelona, with type and class left out. The surcharge is the same for every property, so it is priced; the tourist tax depends on both, so it isn't:
{
"status": "partial",
"lines": [
{
"room": 0,
"charge": "es.catalunya.municipal-surcharge",
"version": "2026-04-01",
"amountMinor": 3000
}
],
"unknowns": [
{
"charge": "es.catalunya.tourist-tax",
"version": "2026-04-01",
"reason": "type_unknown",
"text": "The rate depends on the property type, which the place doesn't give."
}
],
"totals": [{ "currency": "EUR", "addedMinor": 3000, "inPriceMinor": 0 }]
}The line is cut to its room, charge, version and amount.
A town the release doesn't list
Madrid by its LAU code, { lau: { country: "es", code: "28079", year: 2024 } }, one guest, three nights. The release has no Madrid and no Comunidad de Madrid, so the place is just Spain, nothing is priced, and the answer says a regional charge may be missing:
{
"status": "partial",
"place": { "jurisdictions": ["es"] },
"lines": [],
"unknowns": [
{
"level": "region",
"reason": "jurisdiction_not_researched",
"text": "No region in this place's chain has been researched, so a region levy may be missing."
}
],
"totals": []
}An empty lines with status partial is not "no tax". It means the release can't say.
Releases and signatures
Release ids, what a release holds, the signed manifest, checking its Ed25519 signature and file hashes, and running the conformance vectors.
Tokens and HTTP delivery
Fetch Octroi releases over HTTP with a bearer token: the newest release, its files, the signing key, caching, and every error code.