Search Guest check

POST

/v1/object-types/hospitality.guest_check/search

const url = 'https://api.aerandil.com/v1/object-types/hospitality.guest_check/search';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"branch":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","cursor":"example","filters":[{"property":"number","type":"eq","value":"example"}],"limit":1,"order":"asc","property_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","scope":{"level":"tenant"},"sort_by":"created_at"}'
};

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

curl --request POST \
  --url https://api.aerandil.com/v1/object-types/hospitality.guest_check/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "branch": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "cursor": "example", "filters": [ { "property": "number", "type": "eq", "value": "example" } ], "limit": 1, "order": "asc", "property_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "scope": { "level": "tenant" }, "sort_by": "created_at" }'

Search for instances. Filters eq, contains, gte and lte AND-compose; or / not are additive follow-ups. Pages with an opaque cursor; the +1 fetch returns has_more without a second round-trip. Ordered by sort_by (default created_at) in order (default ascending), id breaking ties; rows with no value for a property key sort last.

The order/check entity: opened against a service table (or takeaway / room service) in a meal period on a business date, owned by a server, open until its payments (check_payment) cover what is due — the payment that brings balance_due to zero settles it and marks the table dirty (Simphony model). Carries its running totals, kept by every action that moves them: subtotal (live lines, modifier lines included, voided and comped out), tax_total, total_due (subtotal plus add-on tax), paid_total (tips excluded), tip_total and balance_due. Mutates only through the fnb actions.

Authorizations

aerandil_oauth
objects:read
aerandil_oauth
objects:hospitality.guest_check:read

Request Body^required

application/json

object

branch

Optional open-branch id. Search composes that branch’s copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.

string format: uuid

cursor

Opaque cursor from a prior response’s next_cursor. Pass back verbatim; do not introspect.

string

filters

Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by limit.

Array

One of:

object

property

required

Allowed value: number

type

required

Allowed value: eq

value

required

string

limit

Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).

integer

>= 1 <= 500

order

Direction of sort_by: asc (oldest / smallest first) or desc. A cursor is bound to the sort_by and order it was minted under; another pair is refused (422).

string

default: asc

Allowed values: asc desc

property_id

The house a desk stands in: keeps this property’s rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house’s — the meaning property_id has on the event tail.

string format: uuid

scope

One of: discriminator: level

object

level

required

string

Allowed value: tenant

Allowed values: tenant

sort_by

What the page is ordered by: the row’s created_at or updated_at, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).

string

default: created_at

Allowed values: created_at updated_at number status order_kind daypart business_date covers opened_at opened_by settled_at room promised_at delivery_status dispatched_at delivered_at cleared_at conveyance external_ref

Responses

200

Search results, ordered by (sort_by, id) in the requested order (ascending by default).

application/json

object

data

required

Array<object>

object

created_at

required

string format: date-time

required

string format: uuid

object_type

required

Allowed value: hospitality.guest_check

properties

required

object

balance_due

Guest check balance due

Total_due less paid_total — the payment that brings it to zero settles the check

object

amount

required

string format: decimal

currency

required

string format: iso-4217

business_date

Business date the check belongs to

The hotel date at open (the date the property has open, else its local calendar day) — what every line’s price and VAT resolve on, however late in the service it rings. Revenue still reports under the business day of the settle or the folio posting, as the ledger dates it.

string format: date

cleared_at

When the tray or trolley was collected

string format: date-time

conveyance

Tray or trolley

string

Allowed values: tray trolley

covers

Covers seated

integer

daypart

Meal period the check rings in

The meal period the check was opened in — the daypart an item_price row may be narrowed to (the bar’s lunch price) and a package’s meal allowance is matched on. Stamped from the outlet’s meal_periods when a live check names none. Absent = opened outside the outlet’s periods, or before it had any, which only matches rows with no daypart.

string

Allowed values: breakfast brunch lunch dinner late_night drinks dessert room_service all_day

delivered_at

When the order reached the room

string format: date-time

delivery_status

Where the in-room order is on its dispatch sheet

Taken → dispatched → delivered → cleared, each step only from the one before (dispatch_room_service, deliver_room_service, collect_tray). Independent of the check’s own open / settled: a tray is collected after the bill is signed.

string

Allowed values: taken dispatched delivered cleared

dispatched_at

When the order left the kitchen

string format: date-time

external_ref

Source-system key for replayed / connector-landed checks

string

number

required

Check number

string

opened_at

required

When the check opened

string format: date-time

opened_by

required

Principal::stable_id() of the opening principal

string

order_kind

required

How the order reaches the guest

string

Allowed values: dine_in takeaway room_service delivery

paid_total

Guest check paid total

What the check’s payments applied to it, tips excluded

object

amount

required

string format: decimal

currency

required

string format: iso-4217

promised_at

When the order was promised at the room

The time quoted to the guest: what open_check was given, else twenty minutes after opening for a breakfast order and thirty for any other. The board marks an order late once it passes undelivered.

string format: date-time

room

Room number of the stay the check is for

The stay’s room number when a check opened for an in-house stay (always, for room service), snapshotted for the runner and the board; the stay itself is the check_for_stay link.

string

runner_id

Who ran the order up

string format: uuid

server_id

Owning server

string format: uuid

settled_at

When the check settled

string format: date-time

status

required

Check lifecycle status

string

Allowed values: open settled

subtotal

Guest check subtotal

Gross of the live lines (modifier lines included; voided and comped out)

object

amount

required

string format: decimal

currency

required

string format: iso-4217

tax_total

Guest check tax total

Tax on the live lines, inclusive and add-on

object

amount

required

string format: decimal

currency

required

string format: iso-4217

tip_total

Guest check tip total

Tips taken with the check’s payments (a pass-through, not revenue)

object

amount

required

string format: decimal

currency

required

string format: iso-4217

total_due

Guest check total due

What the guest owes: subtotal plus add-on (non-inclusive) tax

object

amount

required

string format: decimal

currency

required

string format: iso-4217

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

has_more

required

boolean

next_cursor

Cursor for the next page; omitted when the result set is exhausted.

string

Example

{
  "data": [
    {
      "object_type": "hospitality.guest_check",
      "properties": {
        "conveyance": "tray",
        "daypart": "breakfast",
        "delivery_status": "taken",
        "order_kind": "dine_in",
        "status": "open"
      },
      "scope": {
        "level": "tenant"
      }
    }
  ]
}

422

Validation error — unknown property or filter type mismatch.

Search Guest check

Authorizations

Request Bodyrequired

Responses

200

Example

422

Request Body^required