Skip to content
aerandil.com
GitHub

Read Guest check

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

Read an existing instance.

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

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

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

Query Parameters

Section titled “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

Section titled “Responses”

200

Section titled “200”

Object found.

Media typeapplication/json
object
created_at
required
string format: date-time
id
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
Example
{
  "object_type": "hospitality.guest_check",
  "properties": {
    "conveyance": "tray",
    "daypart": "breakfast",
    "delivery_status": "taken",
    "order_kind": "dine_in",
    "status": "open"
  },
  "scope": {
    "level": "tenant"
  }
}

Headers

Section titled “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

Section titled “404”

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