folio tools · Foyer Connect

`folio.addLine`

writes

Add a charge line (room/extra/tax) to a stay's folio.

Input parameters

Field	Type	Required	Notes
`stayId`	string	yes
`date`	string	yes
`category`	enum	yes	One of: room_charge, breakfast, parking, late_checkout, early_checkin, manual
`description`	string	yes
`qty`	integer	no	Default: 1
`unitCents`	integer	yes
`vatRatePct`	string	no	Default: "7.00"

Output fields

Field	Type	Required	Notes
`id`	string	yes
`tenantId`	string	yes
`stayId`	string	yes
`date`	string	yes
`category`	string	yes
`description`	string	yes
`qty`	integer	yes
`unitCents`	integer	yes
`totalCents`	integer	yes
`vatRatePct`	string	yes	Decimal as string — numeric column, not an IEEE-754 double
`addedBy`	string	yes
`createdAt`	string	yes

`folio.addPayment`

writes

Record a payment against a stay's folio.

Input parameters

Field	Type	Required	Notes
`stayId`	string	yes
`amountCents`	integer	yes
`method`	enum	yes	One of: cash, card, bank_transfer, voucher, other
`note`	string	no

Output fields

Field	Type	Required	Notes
`id`	string	yes
`tenantId`	string	yes
`stayId`	string	yes
`amountCents`	integer	yes
`method`	enum	yes	One of: cash, card, bank_transfer, voucher, other
`note`	string · nullable	yes
`recordedAt`	string	yes
`recordedBy`	string · nullable	yes

`folio.close`

writes

Close the folio for a stay by setting folio_closed_at to now(). Should only be called when balanceCents = 0. Throws folio_not_found if the stay is invisible to the caller's tenant (RLS).

Input parameters

Field	Type	Required	Notes
`stayId`	string	yes

Output fields

Field	Type	Required	Notes
`folioClosed`	string · nullable	yes

`folio.closeFolio`

writesconfirm

Close a stay's folio. Irreversible once balanced — no further edits. Requires confirmation.

Input parameters

Field	Type	Required	Notes
`stayId`	string	yes

Output fields

Field	Type	Required	Notes
`folioClosed`	string · nullable	yes

`folio.line.update`

writes

Overwrite the quantity and unit price (cents) of an existing folio line. totalCents is recomputed as qty × unitCents. RLS: a line outside the caller's tenant is invisible — throws folio_line_not_found.

Input parameters

Field	Type	Required
`id`	string	yes
`qty`	integer	yes
`unitCents`	integer	yes

Output fields

Field	Type	Required
`id`	string	yes
`stayId`	string	yes
`date`	string	yes
`category`	string	yes
`description`	string	yes
`qty`	integer	yes
`unitCents`	integer	yes
`totalCents`	integer	yes
`vatRatePct`	string	yes
`addedBy`	string	yes
`createdAt`	string	yes

`folio.list`

read-only

List all folio charge lines for a stay, ordered by date then creation time. Returns room_charge (auto-seeded on check-in) and any operator-added extras. RLS: caller sees only lines belonging to their tenant. Read-only.

Input parameters

Field	Type	Required	Notes
`stayId`	string	yes

Output fields

Field	Type	Required
`lines`	array of object	yes
`lines.id`	string	yes
`lines.stayId`	string	yes
`lines.date`	string	yes
`lines.category`	string	yes
`lines.description`	string	yes
`lines.qty`	integer	yes
`lines.unitCents`	integer	yes
`lines.totalCents`	integer	yes
`lines.vatRatePct`	string	yes
`lines.addedBy`	string	yes
`lines.createdAt`	string	yes

`folio.listPayments`

read-only

Folio: list payments. Read-only query. See the input schema for argument details.

Input parameters

Field	Type	Required	Notes
`stayId`	string	yes

Output fields

Returns array of object. Fields of each element:

Field	Type	Required	Notes
`id`	string	yes
`tenantId`	string	yes
`stayId`	string	yes
`amountCents`	integer	yes
`method`	enum	yes	One of: cash, card, bank_transfer, voucher, other
`note`	string · nullable	yes
`recordedAt`	string	yes
`recordedBy`	string · nullable	yes

`folio.payment.add`

writes

Record a payment against a stay folio. Supported methods: cash, card, bank_transfer, voucher, other. amount_cents must be > 0. An optional free-text note can be attached. RLS: only payments within the caller's tenant are visible.

Input parameters

Field	Type	Required	Notes
`stayId`	string	yes
`amountCents`	integer	yes
`method`	enum	yes	One of: cash, card, bank_transfer, voucher, other
`note`	string	no
`recordedBy`	string	no

Output fields

Field	Type	Required
`id`	string	yes
`stayId`	string	yes
`amountCents`	integer	yes
`method`	string	yes
`note`	string · nullable	yes
`recordedAt`	string	yes
`recordedBy`	string · nullable	yes

`folio.payment.list`

read-only

List all payments recorded against a stay folio, ordered by recorded_at descending. RLS: only payments within the caller's tenant are returned. Read-only.

Input parameters

Field	Type	Required	Notes
`stayId`	string	yes

Output fields

Field	Type	Required
`payments`	array of object	yes
`payments.id`	string	yes
`payments.stayId`	string	yes
`payments.amountCents`	integer	yes
`payments.method`	string	yes
`payments.note`	string · nullable	yes
`payments.recordedAt`	string	yes
`payments.recordedBy`	string · nullable	yes

`folio.payment.remove`

writes

Delete a folio payment by id. RLS silence: if the payment belongs to another tenant it is invisible — returns { deleted: false } without an error.

Input parameters

Field	Type	Required	Notes
`id`	string	yes

Output fields

Field	Type	Required	Notes
`deleted`	boolean	yes

`folio.removeLine`

writesconfirm

Remove a charge line from a folio.

Input parameters

Field	Type	Required	Notes
`id`	string	yes

Output fields

Field	Type	Required	Notes
`deleted`	boolean	yes

`folio.removePayment`

writesconfirm

Remove a recorded payment from a folio.

Input parameters

Field	Type	Required	Notes
`id`	string	yes

Output fields

Field	Type	Required	Notes
`deleted`	boolean	yes

`folio.reset`

writes

Reset a stay's auto-seeded folio lines (room_charge + city_tax, addedBy='system') to their computed original state, discarding manual edits. Operator-added extras are kept. Regenerates via folio-init. RLS: the stay must belong to the caller's tenant.

Input parameters

Field	Type	Required	Notes
`stayId`	string	yes

Output fields

Field	Type	Required	Notes
`regenerated`	integer	yes

`folio.summary`

read-only

Return aggregated folio totals for a stay: subtotal (net of VAT), vatCents (total tax), totalCents (gross = subtotal + vat), and lineCount. VAT is back-calculated from each line's vatRatePct (totalCents already includes VAT). Read-only.

Input parameters

Field	Type	Required	Notes
`stayId`	string	yes

Output fields

Field	Type	Required
`subtotalCents`	integer	yes
`vatCents`	integer	yes
`totalCents`	integer	yes
`lineCount`	integer	yes

`folio.updateLine`

writes

Edit an existing folio charge line's description or amount.

Input parameters

Field	Type	Required
`id`	string	yes
`qty`	integer	yes
`unitCents`	integer	yes

Output fields

Field	Type	Required	Notes
`id`	string	yes
`tenantId`	string	yes
`stayId`	string	yes
`date`	string	yes
`category`	string	yes
`description`	string	yes
`qty`	integer	yes
`unitCents`	integer	yes
`totalCents`	integer	yes
`vatRatePct`	string	yes	Decimal as string — numeric column, not an IEEE-754 double
`addedBy`	string	yes
`createdAt`	string	yes