Gastkonten
Ein Gastkonto ist die laufende Rechnung zu einer Reservierung. Es sammelt Gebühren (Übernachtungen, Steuern, Services) und Zahlungen, und sein Saldo ist das, was der Gast noch schuldet. Jede Reservierung hat genau ein Gastkonto, adressiert über die Reservierungs-ID.
Ein Gastkonto kann mehr als eine Währung tragen: eine Zimmerrechnung in USD mit einer Restaurantzeile in MVR ist normal. Beträge in verschiedenen Währungen werden nie addiert. Jede Antwort meldet balances, die tatsächlichen Werte je Währung, und das ist die Zahl, der Sie trauen sollten. Die pauschalen Felder total_charges, total_payments und balance sind eine Komfortbewertung in der Basiswährung der Unterkunft.
GET /reservations/{id}/folioScope: folio:read
Das vollständige Journal: jede Position, jede Zahlung und die berechneten Summen. {id} ist die Reservierungs-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" }
]
}| Feld | Typ | Hinweise |
|---|---|---|
status | string | settled nur dann, wenn in keiner Währung etwas offen ist, sonst open. |
currency | string | Die Anzeigewährung des Gastkontos (die Währung der Reservierung). |
base_currency | string | Die Basiswährung der Unterkunft, in der die pauschalen Summen bewertet werden. |
balances | array | Tatsächliche Werte je Währung, Anzeigewährung zuerst. Die verlässliche Grundlage bei einem Gastkonto mit mehreren Währungen. |
balances[].balance | string | charges − payments innerhalb dieser einen Währung. |
total_charges | string | null | Nicht enthaltene, nicht stornierte Gebühren, bewertet in base_currency. |
total_payments | string | null | Zahlungen, bewertet in base_currency. |
balance | string | null | total_charges − total_payments, in base_currency. |
inclusive_tax_total | string | Enthaltene Steuern, getrennt ausgewiesen; sie verändern den Saldo nicht. |
line_items[].quantity | integer | Berechnete Einheiten (Nächte / Anzahl). Standard 1. |
line_items[].unit_price | string | null | Preis je Einheit; amount = quantity × unit_price. null bei Altzeilen (dann wie amount behandeln). |
line_items[].tax_rate | string | null | Nur bei Steuerzeilen: der konfigurierte Satz, z. B. "12.0000" für 12 %. Sonst null. |
line_items[].voided | boolean | Ob die Zeile storniert oder rückgebucht wurde. |
Wie der Saldo berechnet wird
Gebühren werden nur angehängt. Eine stornierte Gebühr wird als Gegenbuchung erfasst statt gelöscht, das Journal bleibt also jederzeit prüfbar. Der Saldo zählt nicht enthaltene, nicht stornierte Gebühren abzüglich aller Zahlungen; enthaltene Steuern werden in inclusive_tax_total ausgewiesen, ändern den Saldo aber nicht.
Lesen Sie bei einem Gastkonto mit mehreren Währungen balances. Ein Gastkonto ist erst beglichen, wenn jede Währung auf null aufgeht, eine Schuld in USD wird also nie durch ein Guthaben in MVR ausgeglichen.
Die pauschalen Summen können null sein
total_charges, total_payments und balance sind Bewertungen auf Basis des Wechselkurses, der beim Buchen auf jeder Zeile eingefroren wurde. Steht eine Zeile in einer Währung, für die die Unterkunft keinen Kurs hinterlegt hat, lässt sie sich nicht bewerten, und diese drei Felder sind null statt einer falschen Zahl. balances ist immer vorhanden. Behandeln Sie null, bevor Sie damit rechnen.
POST /reservations/{id}/folio/chargesScope: folio:write · unterstützt Idempotency-Key
Hängen Sie eine eigene Gebühr an das Gastkonto einer Reservierung: eine Spa-Behandlung, eine aufs Zimmer gebuchte Restaurantbestellung, einen Artikel aus der Minibar. {id} ist die Reservierungs-ID.
Geben Sie entweder einen pauschalen amount an oder einen unit_price (mit optionaler quantity), dann wird die Summe als quantity × unit_price berechnet.
| Body-Feld | Erforderlich | Hinweise |
|---|---|---|
description | ja | Bis zu 200 Zeichen. |
amount | eines von beiden | Zeilensumme, Dezimalzeichenkette mit bis zu zwei Nachkommastellen, z. B. "120.00". Geben Sie dieses Feld oder unit_price an. |
unit_price | eines von beiden | Preis je Einheit; Zeilensumme = unit_price × quantity. Geben Sie dieses Feld oder amount an. |
quantity | nein | Ganzzahl ≥ 1, zusammen mit unit_price verwendet. Standard 1. |
category | nein | Eine kurze Bezeichnung (z. B. service, restaurant). Standard custom. |
currency | nein | Dreistelliger ISO-Code. Standard ist die Währung der Reservierung. Der Wert in der Basiswährung wird beim Buchen der Gebühr zum aktuellen Kurs der Unterkunft eingefroren, spätere Kursänderungen ändern den ausgewiesenen Wert dieser Gebühr also nie. |
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" }]
}Die Antwort liefert die ID der neuen Position und den aktualisierten Saldo des Gastkontos. folio_balance ist die Bewertung in der Basiswährung und ist null, wenn sich eine Zeile nicht bewerten lässt; balances trägt die tatsächlichen Werte je Währung. Senden Sie einen Idempotency-Key, damit eine wiederholte Anfrage die Gebühr nie zweimal bucht.
- Reservierungen: die Reservierung, zu der ein Gastkonto gehört.
- Gastkonten: wie Gastkonten im Veridien-Dashboard funktionieren.