Read Tax rule

GET

/v1/object-types/hospitality.tax_rule/objects/{id}

const url = 'https://api.aerandil.com/v1/object-types/hospitality.tax_rule/objects/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.aerandil.com/v1/object-types/hospitality.tax_rule/objects/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

Read an existing instance.

One property-authored tax rule: jurisdiction, what it applies to (a USALI bucket, one retained-payment system_charge_kind, or an F&B tax_class — exactly one), percent / flat-per-night / per-person basis, inclusive/exclusive posture, an optional long-stay reduced value, and an effective-date window. The night audit derives each room posting’s tax_application lines from the rooms rules active on the audited business date; a forfeited deposit, cancellation fee or no-show charge is taxed only by a rule targeting its kind. Rules sharing a code and a target form a non-overlapping succession timeline (a rate change end-dates the predecessor and mints the successor).

Authorizations

aerandil_oauth
objects:read
aerandil_oauth
objects:hospitality.tax_rule:read

Parameters

Path Parameters

required

string format: uuid

Object id (UUID v7, server-generated at create time).

Query Parameters

branch

string format: uuid

Read through an open branch’s copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with as_of (422). The branch must exist under the caller’s tenant.

Responses

200

Object found.

application/json

object

created_at

required

string format: date-time

required

string format: uuid

object_type

required

Allowed value: hospitality.tax_rule

properties

required

object

adults_only

`per_person_per_night` only: count adults and not children (absent = everyone in the room)

boolean

basis

required

How the tax computes

string

Allowed values: percent flat_per_night per_person_per_night

bucket

USALI bucket whose charges this rule taxes. Absent on a rule that targets a retained-payment kind instead

string

Allowed values: rooms food_beverage health_club_spa golf parking minibar other_operated minor_operated miscellaneous_income it_services retail

code

required

Tax code — the rule's identity within the property; rules sharing a code form one succession timeline

string

description

Operator-facing description

string

effective_from

required

First business date the rule applies (inclusive)

string format: date

effective_to

Last business date the rule applies (inclusive); absent = open-ended

string format: date

flat_amount

Tax rule flat amount

Amount per room night (flat_per_night) or per guest per night (per_person_per_night). Required on those bases, forbidden on percent rules

object

amount

required

string format: decimal

currency

required

string format: iso-4217

required

Tax rule id

string

inclusive

required

Whether the tax lives inside the posted amount (VAT carve-out) or on top of it (US-style add-on)

boolean

jurisdiction

required

Taxing jurisdiction (e.g. `US-NY-NYC`, `DE`)

string

rate

Rate for `percent` rules (decimal in [0, 1]; 0.10 = 10%). Required on percent rules, forbidden on flat rules

string format: decimal

reduced_after_nights

`percent` rooms rules only: from the night after this many nights of a continuous stay, the rule taxes only `reduced_value_share` of the night's value (the UK 28-day rule)

integer

reduced_value_share

The share of a long-stay night's value the rule still taxes (decimal in (0, 1]; 0.20 = the UK's 20% facilities minimum)

string format: decimal

system_charge_kind

The retained payment this rule taxes (forfeited deposit, cancellation fee, no-show fee, no-show revenue) — what the house keeps for a stay that did not happen. Nothing taxes one of these unless a rule targets its kind. Percent and inclusive only

string

Allowed values: forfeited_deposit cancellation_fee no_show_fee no_show_revenue

tax_class

The F&B tax class this rule taxes (an `item_class.tax_class` code — Standard, Cold food, Children's meal). Percent only. A check line takes every rule in force for its class on the check's business date

string

provenance

Per-property source attribution and pins. An entry under properties means the property’s current value came from that source (on the source’s own clock, source_updated_at); an entry under pins is a human override protecting the property from sourced writes.

object

pins

object

key

additional properties

object

pinned_at

string format: date-time

pinned_by

object

reason

required

string

properties

object

key

additional properties

object

external_id

string

recorded_at

required

string format: date-time

source

required

string

source_updated_at

string format: date-time

stream

string

scope

required

One of: discriminator: level

object

level

required

string

Allowed value: tenant

Allowed values: tenant

tenant_id

required

string format: uuid

updated_at

required

string format: date-time

version

required

integer

>= 1

Example

{
  "object_type": "hospitality.tax_rule",
  "properties": {
    "basis": "percent",
    "bucket": "rooms",
    "system_charge_kind": "forfeited_deposit"
  },
  "scope": {
    "level": "tenant"
  }
}

Headers

ETag

string

/^"\d+"$/

Quoted strong validator (RFC 7232 §2.3) carrying the object’s monotonic version. Informational on the read path — object mutation goes through typed actions on /v1/actions/{action}/apply, not raw CRUD.

404

No object with that id (or soft-deleted).