Tiered & per-person rates

A tiered rate's amount depends on a band — most often the hotel star rating or property class, sometimes the nightly price. A 5★ hotel pays more per person per night than a 2★ one. Tiers are stored on the rate itself; the engine picks the band the booking falls into.

The rate carries a tier_type discriminator that selects the banding logic — one of:

Within a tier_type, each individual tier is a small object. The fields the engine reads are value (the flat amount) or rate (the percentage), min / max for the band bounds, and star_rating / property_class for the band key.

Tiering by star rating is the Barcelona pattern: the regional Catalan tax and the municipal recargo both step by hotel class, so a 5★ stay draws the top band of each. Pass star_rating (or property_classification) so the engine can land on the right tier.

A large class of tourist taxes is a flat cash amount charged per guest per night. The category codes carry the basis right in the name — tourism_flat_person_night, occ_flat_person_night, eco_flat_person_night. The engine multiplies the per-unit amount by the chargeable guests and the number of nights.

amount  =  per_unit  ×  chargeable_guests  ×  nights

e.g. €4.50  ×  2 guests  ×  3 nights  =  €27.00

Many per-person taxes exempt children. By default the engine charges every occupant: it multiplies by number_of_guests. To exclude minors, pass adults — the chargeable count becomes adults when set, falling back to number_of_guests when it isn't.

So a family of four (two adults, two children under the local exemption age) booking a per-person tourist tax should send number_of_guests: 4 and adults: 2 — the tax then lands on two people, not four.

{
  "jurisdiction_code": "ES-CT-BCN",
  "stay_date": "2026-07-01",
  "nights": 3,
  "nightly_rate": 200,
  "currency": "EUR",
  "property_type": "hotel",
  "star_rating": 5,
  "number_of_guests": 4,
  "adults": 2
}

When you know each occupant, send the guests[] array instead of (or alongside) the counts. Each guest is evaluated in its own sub-context and charged at its own resulting rate — by age band, residency, disability percentage, or guest type — and the per-person amounts are summed across the party. An individually-exempt guest (a child under the exemption age, a certified-disabled guest, a resident) simply contributes zero and drops out of the total, rather than being approximated by a count.

The category vocabulary (which codes are per-person, per-night, tiered) is in Tax categories. When a per-person tourist tax folds into the VAT base, see VAT base composition. And exemptions or caps on a tiered tax are Rules.