Reservierungen

Eine Reservierung entsteht in zwei Schritten: Sie blockieren den Bestand, während der Gast bezahlt, und bestätigen den Hold dann zu einer Reservierung. Durch diese Teilung ist der Bestand in dem Moment reserviert, in dem sich ein Gast festlegt, und die Reservierung wird erst endgültig, wenn die Zahlung geklappt hat.

Der Lebenszyklus einer Reservierung

POST /holds legt eine vorläufige Reservierung an, die ein Zimmer 15 Minuten lang blockiert. POST /holds/{id}/confirm macht daraus eine bestätigte Reservierung und verbucht die Zahlung. Nicht bestätigte Holds laufen einfach ab und geben ihren Bestand frei.

POST /holds

Scope: reservations:write · unterstützt Idempotency-Key

Legt eine vorläufige Reservierung an, die einen Zimmertyp auf einem Ratenplan für den Zeitraum blockiert. Der Aufenthalt wird bepreist (Übernachtungen und anfallende Steuern) und auf ein neues Gastkonto gebucht. Der Hold zählt gegen die Verfügbarkeit, bis er bestätigt wird oder sein 15-Minuten-Fenster abläuft.

Body-Feld	Erforderlich	Hinweise
`room_type_id`	ja	Muss zu dieser Unterkunft gehören.
`rate_plan_id`	ja	Aktiver Plan für den Zimmertyp; seine Sichtbarkeitsregeln werden erneut geprüft.
`check_in`	ja	`YYYY-MM-DD`.
`check_out`	ja	`YYYY-MM-DD`, nach `check_in`; höchstens 30 Nächte.
`guest_id`	ja	Der Gast, für den der Hold gilt.
`adults`	ja	Ganzzahl 1–20; die Personenzahl muss in `max_occupancy` passen.
`children`	nein	Ganzzahl 0–20, Standard `0`.
`child_ages`	nein	Array von Kinderaltern (Ganzzahlen ≥ 0). Wenn vorhanden, ist das die maßgebliche Kinderzahl und steuert den Zusatzgast-Aufpreis nach Altersklassen.
`bed_config`	nein	Die vom Gast gewählte Bettvariante; muss eine sein, die der Zimmertyp anbietet. Wird für das Housekeeping auf der Reservierung vermerkt.
`add_ons`	nein	Array der vom Gast gewählten Zusatzleistungen (bis zu 10), jede wird beim Blockieren auf das Gastkonto bepreist und liegt damit in der belasteten Summe. Siehe die Felder unten.
`promo_code`	nein	Erforderlich, wenn der gewählte Ratenplan hinter einem Promo-Code liegt.

Jeder Eintrag in add_ons verweist auf einen vom Gast buchbaren Service:

Feld der Zusatzleistung	Erforderlich	Hinweise
`service_id`	ja	Der Service, der hinzugefügt wird.
`modifier_values`	nein	Objekt aus `{ modifier_key: value }` für die Eingabefelder des Service. Standard `{}`.
`quantity`	nein	Einheiten der Zusatzleistung (Ganzzahl 1–99). Standard `1`.

curl -X POST "$VRDN_BASE/holds" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1d2c9a-8b3e-4a17-9c2f-1e5b7d0a4c83" \
  -d '{
    "room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
    "rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02",
    "check_in": "2026-08-01",
    "check_out": "2026-08-04",
    "guest_id": "3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34",
    "adults": 2
  }'

{
  "reservation_id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27",
  "folio_id": "1a6c3e9f-4d2b-4e8a-b5c7-9f0e6d4a2c81",
  "hold_expires_at": "2026-06-19T08:45:00.000Z",
  "total": "1260.00",
  "currency": "USD",
  "status": "tentative"
}

Fehler	Wann
`409 no_availability`	Der Zimmertyp ist für den Zeitraum ausgebucht.
`404 rate_plan_not_found`	Der Plan ist inaktiv, oder seine Sichtbarkeitsregeln schließen diesen Gast oder Kontext aus.
`400 party_too_large`	`adults + children` übersteigt die `max_occupancy` des Zimmertyps.

POST /holds/{id}/confirm

Scope: reservations:write · unterstützt Idempotency-Key

Ziehen Sie die Zahlung in Ihrem eigenen Ablauf ein und bestätigen Sie den Hold dann mit einer payment_reference. Veridien prüft die Verfügbarkeit erneut (ohne den Hold selbst), setzt die Reservierung und ihre Unterbringung auf confirmed, verbucht die Zahlung auf dem Gastkonto und schreibt bei Aufenthalten in USD Treuepunkte auf den Zimmerumsatz gut.

Methode 1 beruht auf einer vertrauensbasierten Zusicherung: bitte lesen

Dieser Endpunkt beruht auf Vertrauen. Ihre payment_reference ist eine Zusicherung, dass Sie das Geld eingezogen haben: eine Behauptung, nie ein Nachweis. Veridien prüft nicht, ob die Zahlung tatsächlich geflossen ist: Ihr Hotel ist der Merchant of Record, und Ihnen gehören die Gelder, die Rückbuchungen und die Erstattungen. Deshalb gilt:

Senden Sie für jede Buchung eine echte, eindeutige Referenz. Verwenden Sie eine Zahlungs-ID nie erneut und verändern Sie sie nie über mehrere Reservierungen hinweg.
Jede Bestätigung wird als Zahlungszusicherung im Audit-Log erfasst (wer sie abgegeben hat, die Referenz, der Betrag).
Prüfungen beim Bestätigen weisen offensichtlich falsche Eingaben ab, sie können aber nicht belegen, dass tatsächlich Geld geflossen ist.

Wenn Veridien die Zahlung selbst prüfen soll (über Stripe gehostet, von der Plattform verifizierter Einzug), ist das die gehostete Buchungsmaschine (Methode 2), nicht diese API.

Body-Feld	Erforderlich	Hinweise
`payment_reference`	ja	Ihre Zahlungskennung: eine ungeprüfte Zusicherung, dass Sie die Zahlung eingezogen haben. Die Bestätigung ist auf diesen Wert idempotent.
`payment_currency`	nein	Optionale ISO-4217-Währung, die Sie belastet zu haben versichern. Wird abgelehnt, wenn sie von der Währung der Reservierung abweicht.
`payment_amount`	nein	Optionaler Betrag, den Sie eingezogen zu haben versichern. Wird abgelehnt, wenn er von der Summe des Gastkontos abweicht.

curl -X POST "$VRDN_BASE/holds/7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27/confirm" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9a2e7c10-4b3f-4d28-8c1f-2e6b8d0a5d94" \
  -d '{ "payment_reference": "pay_abc123", "payment_currency": "USD", "payment_amount": 1260.00 }'

{
  "reservation_id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27",
  "status": "confirmed",
  "check_in_date": "2026-08-01",
  "check_out_date": "2026-08-04",
  "currency": "USD",
  "folio_balance": "0.00",
  "already_confirmed": false
}

Fehler	Wann
`409 hold_expired`	Das 15-minütige Zahlungsfenster des Holds ist abgelaufen, bevor Sie bestätigt haben. Legen Sie einen neuen Hold an.
`409 no_availability`	Der Hold hat zwischen Blockieren und Bestätigen seinen Bestand verloren.
`409 not_confirmable`	Die Reservierung ist kein bestätigbarer vorläufiger Hold (z. B. bereits storniert).
`400 currency_mismatch`	`payment_currency` weicht von der Währung der Reservierung ab.
`400 amount_mismatch`	`payment_amount` weicht von der Summe des Gastkontos ab.

Doppelt idempotent

Eine bereits bestätigte Reservierung erneut zu bestätigen oder dieselbe payment_reference noch einmal zu senden, liefert das vorhandene bestätigte Ergebnis mit "already_confirmed": true, ohne zweite Zahlung und ohne zweite Reservierung (ein eindeutiger Index über (folio, reference) sichert das gegen Wettläufe ab). Zusammen mit einem Idempotency-Key lässt sich die Bestätigung gefahrlos wiederholen.

Treuepunkte werden in USD gerechnet

Treuepunkte entstehen auf Zimmerumsatz in USD. Ein Aufenthalt in einer anderen Währung sammelt nicht stillschweigend null Punkte; die übersprungene Gutschrift wird zur Abstimmung festgehalten, bis das Sammeln in mehreren Währungen ausgeliefert wird.

GET /reservations

Scope: reservations:read

Die Reservierungen der Unterkunft, sortiert nach Anreisedatum, früheste zuerst, jeweils mit dem offenen Saldo ihres Gastkontos.

Query-Parameter	Hinweise
`guest_id`	Auf einen Gast filtern.
`status`	Nach Status filtern: `tentative`, `confirmed`, `checked_in`, `checked_out`, `cancelled`, `no_show`.
`limit`	Seitengröße, Standard `25`, Maximum `100`.
`offset`	Zu überspringende Datensätze.

curl "$VRDN_BASE/reservations?guest_id=3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34&limit=10" -H "Authorization: Bearer $VRDN_KEY"

{
  "has_more": false,
  "data": [
    {
      "id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27",
      "status": "confirmed",
      "guest_id": "3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34",
      "check_in_date": "2026-08-01",
      "check_out_date": "2026-08-04",
      "room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
      "room_type_name": "Deluxe Ocean Villa",
      "nightly_rate": "420.00",
      "currency": "USD",
      "folio_balance": "0.00",
      "balances": []
    }
  ]
}

Wie Sie durch die Ergebnisse blättern, steht unter Konventionen.

GET /reservations/{id}

Scope: reservations:read

Eine einzelne Reservierung mit ihren Unterbringungen (den Abschnitten des Aufenthalts je Zimmer) und dem Saldo des Gastkontos.

curl "$VRDN_BASE/reservations/7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27" -H "Authorization: Bearer $VRDN_KEY"

{
  "id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27",
  "status": "confirmed",
  "guest_id": "3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34",
  "check_in_date": "2026-08-01",
  "check_out_date": "2026-08-04",
  "room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
  "room_type_name": "Deluxe Ocean Villa",
  "nightly_rate": "420.00",
  "currency": "USD",
  "adults": 2,
  "children": 0,
  "number_of_guests": 2,
  "booking_source": "direct_web",
  "special_notes": null,
  "folio_id": "1a6c3e9f-4d2b-4e8a-b5c7-9f0e6d4a2c81",
  "folio_balance": "0.00",
  "balances": [{ "currency": "USD", "charges": "1310.40", "payments": "1310.40", "balance": "0.00" }],
  "accommodations": [
    {
      "id": "2b9e6f4d-8a3c-4e1b-9d5f-7a0c4e8b2d63",
      "room_id": null,
      "room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
      "check_in_date": "2026-08-01",
      "check_out_date": "2026-08-04",
      "status": "confirmed",
      "nightly_rate": "420.00"
    }
  ]
}

POST /reservations/{id}/cancel

Scope: reservations:write

Storniert eine Reservierung im Status tentative oder confirmed und gibt ihren Bestand frei. Reservierungen, die bereits eingecheckt, ausgecheckt oder storniert sind, lassen sich nicht über die API stornieren (409 not_cancellable). Das Gastkonto und etwaige Rechnungen werden storniert (zur Prüfbarkeit aufbewahrt), und wenn die Reservierung bezahlt war, wird vor der Freigabe des Bestands eine Erstattung nach Ihren Bedingungen ausgelöst.

Body-Feld	Erforderlich	Hinweise
`reason`	nein	Wird als Stornogrund gespeichert.

curl -X POST "$VRDN_BASE/reservations/7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27/cancel" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Guest changed plans" }'

{ "reservation_id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27", "status": "cancelled", "refund_minor": 0, "refund_provider": null }

Feld	Typ	Hinweise
`refund_minor`	integer	Erstatteter Betrag in kleinsten Einheiten (Cent). `0`, wenn die Reservierung unbezahlt war oder die Bedingungen nichts erstatten.
`refund_provider`	string \| null	Der Anbieter, der die Erstattung ausgeführt hat, oder `null`, wenn keine Erstattung erfolgt ist.

Gastkonten: die Rechnung lesen und Gebühren buchen.
Gäste und Treueprogramm: der Gast, zu dem eine Reservierung gehört.

Bestand blockieren

Einen Hold bestätigen

Reservierungen auflisten

Eine Reservierung abrufen

Eine Reservierung stornieren

Verwandte Seiten

Auf dieser Seite