Tax-inclusive pricing & cross-currency

Two presentation concerns that don't change the tax owed but do change how it's expressed: a gross price that already includes tax (EU consumer law), and a booking that's priced in one currency but settled in another. The engine handles both and always shows its work.

Tax-inclusive pricing

Under EU consumer law a displayed price to a consumer is usually gross — it already includes the VAT. When the price you have is the all-in figure, set price_includes_tax: true and the engine reverse-derives the tax-exclusive base from the gross amount, rather than adding tax on top.

Exclusive vs. inclusive

Exclusive: tax is added to your input. Inclusive: your input is the gross, and the engine backs out the base.

Either way, the response always populates both subtotal_excluding_tax and subtotal_including_tax on the tax_breakdown, so you can render gross or net without doing the arithmetic yourself — and the two always reconcile.

POST/v1/tax/calculate

A gross-priced German stay — the engine backs out the base; the response carries both the excluding and including subtotals.

Request body

{
  "jurisdiction_code": "DE",
  "stay_date": "2026-07-01",
  "nights": 2,
  "nightly_rate": 110,
  "currency": "EUR",
  "property_type": "hotel",
  "price_includes_tax": true
}

Tip

This pairs with invoicing: a consumer-facing gross price reverse-derives cleanly into the EN 16931 net + VAT figures the issued document needs. See The invoice lifecycle.

Cross-currency settlement

A booking is sometimes priced in one currency but settled in another — an OTA quotes the guest in USD but pays out to the host in EUR. The tax is computed in the booking currency; to also see it in the payout currency, set settlement_currency.

Field	Type	Description
currencyrequired	ISO 4217	The booking currency — what the inputs are denominated in and what tax is computed in.
settlement_currency	ISO 4217	Optional payout currency. When set, the response adds a settlement-currency projection.
amount_in_settlement_currency	number \| null	The total converted into the settlement currency (null when settlement_currency isn't requested).
settlement_fx_rate	number \| null	The FX rate used for the conversion, returned so the projection is fully transparent.

The tax calculation itself is unchanged — settlement is a presentation layer on top. The response carries amount_in_settlement_currency and settlement_fx_rate alongside the native-currency totals, so the converted figure is never opaque.

{
  "jurisdiction_code": "ES-CT-BCN",
  "stay_date": "2026-07-01",
  "nights": 3,
  "nightly_rate": 200,
  "currency": "USD",
  "settlement_currency": "EUR"
}

Detail

Currency precision follows the currency's minor units — JPY/KRW render with no decimals, KWD/BHD/OMR with three — matching what the issued UBL would carry.

Where to go next

Both flags are part of the broader multi-actor surface — see the full map in Scenario fields and Channels & merchant of record. To turn a calculation into an issued document, see Calculate tax (API) and The invoice lifecycle.