Quote a stay

quote(release, request) prices one stay against a loaded release and returns a Quote. It is a pure function: same release, same request, same answer.

import { quote, TaxDataError } from "./calculator";

const answer = quote(release, {
  place: { jurisdiction: "de.berlin" },
  stay: { arrival: "2026-11-12", departure: "2026-11-14" },
  rooms: [
    {
      guests: [{ age: 41 }, { age: 38 }],
      price: { currency: "EUR", vat: "included", totalMinor: 32000 },
    },
  ],
});

All money, in the request and the answer, is in integer minor units of its currency: 32000 is €320.00. The manifest's currencies gives each currency's exponent.

The requestCopy Anchor Link

Top levelCopy Anchor Link

A roomCopy Anchor Link

A room priceCopy Anchor Link

The answerCopy Anchor Link

Top levelCopy Anchor Link

StatusCopy Anchor Link

partial wins over price_required: a quote with an unknown is partial even when it also needs a price.

LinesCopy Anchor Link

A line is one charge, under one law version, for one room. A stay that crosses the date a new version comes into force gets one line per version. Lines are ordered by room, then from the country down to the most local jurisdiction, then by charge id.

Line fieldsCopy Anchor Link

The nights add up to the line: amountMinor is the sum of the nights' amountMinor, and the same for VAT.

ExplanationCopy Anchor Link

explanation.code names the way the charge is levied: per_person_night, per_room_night, per_person_stay, per_room_stay, percent, percent_capped, banded, surcharge, or mixed when the line's nights fall under different rates. explanation.params holds the numbers behind it:

• nights: how many nights the line covers;
• liable: the most guests liable on any one night;
• amount: amountMinor written out with its currency, such as 20.40 EUR;
• exempt: present only when an exemption lowered the line, the ids of every exemption that did, comma-separated and sorted.

explanation.text puts the same in an English sentence, for logs and support screens. Build your own wording from code and params.

Claimable exemptionsCopy Anchor Link

Some exemptions depend on who the guest is, not only their age: a group the law names, such as medical_treatment. When no guest in the request claims such a group, the line lists it in claimable with its exemption id and group. When a guest claims it but the exemption also has an age range and the guest has no age, the entry carries needs: "age". Ask the guest, then quote again with groups (and the age) on that guest.

EvidenceCopy Anchor Link

Each id in evidence is an entry in the country's evidence list, in the same release:

The quickstart shows how to look them up.

Price-dependent chargesCopy Anchor Link

A percentage of the room price, or a charge banded by price, can't be priced without one. When the request gives no price for a room, each such charge is listed once per room instead of as a line:

{
  "room": 0,
  "charge": "de.berlin.city-tax",
  "version": "2025-01-01",
  "nights": ["2026-11-12", "2026-11-13"]
}

A surcharge on a price-dependent charge is price-dependent too.

TotalsCopy Anchor Link

totals has one entry per currency, ordered by currency:

The Berlin request above comes back complete, with one line of 2243 and VAT on the charge of 157:

{ "currency": "EUR", "addedMinor": 2400, "inPriceMinor": 0 }

The calculator never adds across currencies.

AssumptionsCopy Anchor Link

Each assumption has a code and an English text:

ErrorsCopy Anchor Link

A request the calculator can't take throws a TaxDataError, with a code and, when one field is at fault, a pointer to it (an RFC 6901 JSON pointer such as /place/jurisdiction).

try {
  quote(release, request);
} catch (error) {
  if (error instanceof TaxDataError) console.log(error.code, error.pointer);
  else throw error;
}

Error codesCopy Anchor Link