Folios
A folio is the running bill for a reservation. It collects charges (room nights, taxes, services) and payments, and its balance is what the guest still owes. Each reservation has exactly one folio, addressed through the reservation id.
A folio can hold more than one currency: a USD room bill with an MVR restaurant line is normal. Amounts in different currencies are never added together. Every response reports balances, the per-currency actuals, and that is the figure to trust. The flat total_charges, total_payments and balance fields are a convenience valuation in the property's base currency.
GET /reservations/{id}/folioScope: folio:read
The full ledger: every line item, every payment, and the computed totals. {id} is the reservation id.
curl "$VRDN_BASE/reservations/7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27/folio" -H "Authorization: Bearer $VRDN_KEY"{
"folio_id": "1a6c3e9f-4d2b-4e8a-b5c7-9f0e6d4a2c81",
"reservation_id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27",
"status": "settled",
"currency": "USD",
"base_currency": "USD",
"balances": [
{ "currency": "USD", "charges": "1310.40", "payments": "1310.40", "balance": "0.00" }
],
"total_charges": "1310.40",
"total_payments": "1310.40",
"balance": "0.00",
"inclusive_tax_total": "0.00",
"line_items": [
{ "id": "8e3b5d1c-7a9f-4b2e-a6c4-0d8f2e5b7a93", "description": "Room charge - Night 1", "amount": "420.00", "quantity": 1, "unit_price": "420.00", "date": "2026-08-01", "category": "room", "revenue_type": "hotel", "is_inclusive": false, "tax_rate": null, "currency": "USD", "voided": false },
{ "id": "4f9a1c7e-2d6b-4a3f-8b9e-6c0d5f3a8e12", "description": "GST", "amount": "50.40", "quantity": 1, "unit_price": "50.40", "date": "2026-08-01", "category": "tax", "revenue_type": "hotel", "is_inclusive": false, "tax_rate": "12.0000", "currency": "USD", "voided": false }
],
"payments": [
{ "id": "b7d2f8a5-1e4c-4d9b-a3f6-8c1e0b6d4f25", "amount": "1310.40", "method": "card", "reference": "pay_abc123", "currency": "USD" }
]
}| Field | Type | Notes |
|---|---|---|
status | string | settled only when nothing is owed in any currency; open otherwise. |
currency | string | The folio's display currency (the reservation's currency). |
base_currency | string | The property's base currency, which the flat totals are valued in. |
balances | array | Per-currency actuals, display currency first. The ground truth on a multi-currency folio. |
balances[].balance | string | charges − payments within that one currency. |
total_charges | string | null | Non-inclusive, non-voided charges valued in base_currency. |
total_payments | string | null | Payments valued in base_currency. |
balance | string | null | total_charges − total_payments, in base_currency. |
inclusive_tax_total | string | Inclusive taxes, shown separately; not added to the balance. |
line_items[].quantity | integer | Units charged (nights / count). Defaults to 1. |
line_items[].unit_price | string | null | Per-unit price; amount = quantity × unit_price. null on legacy lines (treat as amount). |
line_items[].tax_rate | string | null | Tax lines only: the configured rate, e.g. "12.0000" for 12%. null otherwise. |
line_items[].voided | boolean | Whether the line was voided/reversed. |
How the balance is computed
Charges are append-only. A voided charge is recorded as a reversing entry rather than deleted, so the ledger is always auditable. The balance counts non-inclusive, non-voided charges minus all payments; inclusive taxes are reported in inclusive_tax_total but do not change the balance.
On a multi-currency folio, read balances. A folio is settled only when every currency nets to zero, so a USD debt is never cancelled out by an MVR credit.
The flat totals can be null
total_charges, total_payments and balance are valuations built from the exchange rate frozen onto each row when it was posted. If a row is in a currency the property has no configured rate for, it cannot be valued, and these three fields are null rather than a wrong number. balances is always present. Handle null before doing arithmetic on them.
POST /reservations/{id}/folio/chargesScope: folio:write · supports Idempotency-Key
Append a custom charge to a reservation's folio: a spa treatment, a restaurant order charged to the room, a minibar item. {id} is the reservation id.
Provide either a flat amount, or a unit_price (with optional quantity) and the total is computed as quantity × unit_price.
| Body field | Required | Notes |
|---|---|---|
description | yes | Up to 200 characters. |
amount | one of | Line total, decimal string with up to two places, e.g. "120.00". Provide this or unit_price. |
unit_price | one of | Per-unit price; line total = unit_price × quantity. Provide this or amount. |
quantity | no | Integer ≥ 1, used with unit_price. Defaults to 1. |
category | no | A short label (e.g. service, restaurant). Defaults to custom. |
currency | no | 3-letter ISO code. Defaults to the reservation's currency. The base-currency value is frozen at the property's current rate when the charge is posted, so later rate changes never alter this charge's reported value. |
curl -X POST "$VRDN_BASE/reservations/7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27/folio/charges" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: c4f8a2d1-7e9b-4c36-a1d8-3f6e0b9a2c75" \
-d '{ "description": "Minibar - Sparkling water", "unit_price": "4.00", "quantity": 3, "category": "service" }'{
"line_item_id": "6d4f8b2a-9c1e-4f7d-b8a3-2e5c9f0a1d74",
"folio_balance": "120.00",
"balances": [{ "currency": "USD", "balance": "120.00" }]
}The response returns the new line item id and the folio's updated balance. folio_balance is the base-currency valuation and is null when some row cannot be valued; balances carries the per-currency actuals. Send an Idempotency-Key so a retried request never posts the charge twice.
- Reservations: the reservation a folio belongs to.
- Folios: how folios work inside the Veridien dashboard.