Angebote und Promo-Codes

Die Katalog-Endpunkte beantworten die Frage „Was kann ich in jedem Zimmertyp buchen“. Diese hier beantworten „Welche Angebote gelten für diesen Aufenthalt“, und genau das braucht eine Buchungsmaschine zur Vermarktung: öffentliche Namen, Beschreibungen, Bilder, was ein Paket enthält und den Preis für die jeweilige Personenzahl.

Ein Ratenplan, ein Paket und eine Promotion sind alle dieselbe Art von Objekt. Sie unterscheiden sich durch kind und dadurch, wie sich ihr Preis von einem übergeordneten Plan ableitet. Deshalb wird ein Paket genau wie jede andere Rate verteilt und bepreist.

GET /rate-plans

Scope: availability:read

Jedes Angebot, das die Unterkunft für die Buchungsmaschine veröffentlicht hat, bepreist für den angefragten Aufenthalt und die angefragte Personenzahl.

Parameter	Erforderlich	Hinweise
`check_in`	ja	`YYYY-MM-DD`.
`check_out`	ja	`YYYY-MM-DD`, exklusiv.
`adults`	nein	Standard 2.
`children`	nein	Standard 0.
`room_type_id`	nein	Auf einen Zimmertyp einschränken.

curl "$VRDN_BASE/rate-plans?check_in=2026-08-01&check_out=2026-08-04&adults=2" \
  -H "Authorization: Bearer $VRDN_KEY"

{
  "check_in": "2026-08-01",
  "check_out": "2026-08-04",
  "data": [
    {
      "rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02",
      "room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
      "room_type_name": "Ocean Suite",
      "public_name": "Half Board Escape",
      "kind": "package",
      "description": "Breakfast and dinner included daily.",
      "image_url": "https://cdn.example.com/half-board.jpg",
      "inclusions": [
        { "label": "Breakfast", "frequency": "perGuestPerNight", "included_quantity": 1 },
        { "label": "Dinner", "frequency": "perGuestPerNight", "included_quantity": 1 }
      ],
      "min_los": 2,
      "max_los": null,
      "currency": "USD",
      "total": "1341.60",
      "room_subtotal": "1020.00",
      "taxes_total": "321.60",
      "base_occupancy": 2,
      "nightly_rates": [{ "date": "2026-08-01", "day_of_week": 6, "rate": "340.00", "source": "interval" }]
    }
  ]
}

Ein Angebot erscheint nur, wenn alles Folgende zutrifft. Was nicht zutrifft, fehlt in der Antwort einfach, es gibt keinen unvollständigen Eintrag und keinen Eintrag „nicht verfügbar“.

Der Plan ist aktiv, und die Unterkunft hat ihn für die Buchungsmaschine freigegeben.
Der Aufenthalt liegt im Buchungsfenster und im Aufenthaltsfenster des Angebots.
Die Aufenthaltsdauer erfüllt Mindest- und Höchstdauer des Angebots, und jede Nacht fällt auf einen erlaubten Wochentag.
Der Zimmertyp fasst die Personenzahl.
Der Plan liegt nicht hinter einem Promo-Code.

Angebote hinter einem Promo-Code erscheinen hier nie. Sie sind nur über eine erfolgreiche Code-Prüfung erreichbar, die unten beschrieben ist.

inclusions listet auf, was ein Paket bündelt, mit der Frequenz, in der jeder Posten anfällt: perStay, perNight, perGuest oder perGuestPerNight. Die Angaben sind beschreibend. Der Verkaufspreis eines Pakets ist das eine total; die Unterkunft verteilt diese Summe intern auf die Inklusivleistungen, damit jede Komponente steuerlich richtig behandelt wird, aber der Gast zahlt eine Zahl.

POST /promo-codes/validate

Scope: availability:read

Feld	Erforderlich	Hinweise
`code`	ja	Groß- und Kleinschreibung sowie umgebende Leerzeichen werden ignoriert.
`check_in`	ja	`YYYY-MM-DD`.
`check_out`	ja	`YYYY-MM-DD`, exklusiv.
`room_type_id`	nein	Wenn angegeben und das Angebot des Codes auf einem anderen Zimmertyp liegt, ist die Antwort das einheitliche `valid: false`.
`adults`	nein	Standard 2.
`children`	nein	Standard 0.
`child_ages`	nein	Standard `[]`. Ist die Liste nicht leer, ist ihre Länge die Kinderzahl und überschreibt `children`.

Die Personenzahl wird gegen die maximale Belegung des Zimmertyps geprüft, eine zu niedrig angegebene Personenzahl kann hier also durchgehen und dann bei POST /holds scheitern.

Ein Code schaltet einen Ratenplan frei. Er gewährt keinen eigenen Rabatt: Die Ersparnis steckt bereits in dem Plan, den der Code sichtbar macht. Der Preis, den Sie zurückbekommen, ist also der Preis, da bleibt nichts mehr zu rechnen.

curl -X POST "$VRDN_BASE/promo-codes/validate" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER26",
    "check_in": "2026-08-01",
    "check_out": "2026-08-04",
    "adults": 2
  }'

Ein Code, der greift, liefert das Angebot zurück, das er freischaltet, in derselben Struktur wie ein Eintrag aus /rate-plans.

{
  "valid": true,
  "code": "SUMMER26",
  "rate_plan": {
    "rate_plan_id": "e2a9d7c4-3f6b-4c1e-9a8d-7b5f0c2e4a19",
    "room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
    "room_type_name": "Ocean Suite",
    "public_name": "Early Bird",
    "kind": "promotion",
    "description": "Book 60 days ahead and save.",
    "image_url": "https://cdn.example.com/early-bird.jpg",
    "inclusions": [],
    "min_los": 3,
    "max_los": null,
    "currency": "USD",
    "total": "1140.36",
    "room_subtotal": "867.00",
    "taxes_total": "273.36",
    "nightly_rates": [{ "date": "2026-08-01", "day_of_week": 6, "rate": "289.00", "source": "interval" }]
  }
}

Ein Code, der nicht greift, liefert eine einzige Antwort, ganz gleich aus welchem Grund.

{
  "valid": false,
  "reason": "That code is not valid for these dates."
}

Die Fehlerantwort ist bewusst identisch für einen Code, den es nicht gibt, einen abgelaufenen, einen vollständig eingelösten und einen, dessen Angebot den angefragten Zeitraum nicht abdeckt. Sie zu unterscheiden würde einem Aufrufer verraten, welche Codes echt sind, deshalb wird die genaue Ursache nie preisgegeben.

Der Abgleich ignoriert Groß- und Kleinschreibung sowie umgebende Leerzeichen, summer26 und SUMMER26 sind also derselbe Code.

Die Code-Prüfung hat ein engeres Limit als der Rest der API, zusätzlich zu den Limits pro Schlüssel und pro IP, die unter Authentifizierung beschrieben sind. Wiederholte Fehlschläge liefern 429. Prüfen Sie einen Code, wenn der Gast ihn abschickt, nicht bei jedem Tastendruck.

Übergeben Sie den Code beim Buchungsaufruf. Der Server löst ihn von Grund auf neu auf und bepreist den Aufenthalt erneut.

curl -X POST "$VRDN_BASE/holds" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "guest_id": "c4e7b9d2-6a1f-4e3c-9b8d-2f5a7c0e1d46",
    "room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
    "rate_plan_id": "e2a9d7c4-3f6b-4c1e-9a8d-7b5f0c2e4a19",
    "check_in": "2026-08-01",
    "check_out": "2026-08-04",
    "adults": 2,
    "promo_code": "SUMMER26"
  }'

Zwei Folgen, die Sie einplanen sollten:

Eine Prüfantwort ist unverbindlich. Sie gibt den Moment wieder, in dem sie ausgestellt wurde. Läuft der Code ab, wird er deaktiviert oder erreicht er sein Einlösungslimit, bevor der Gast die Zahlung abschließt, scheitert die Buchung, statt das frühere Angebot zu halten. Fangen Sie diesen Fehlschlag in Ihrem Checkout ab.
Senden Sie nie einen Preis. Der Server bepreist jede Buchung selbst und ignoriert jeden Betrag, den ein Client mitliefert. Ein Angebotspreis dient nur der Anzeige.

Eine Einlösung zählt, wenn eine Reservierung bestätigt wird, nicht wenn ein Code geprüft wird, und sie wird wieder freigegeben, wenn die Reservierung storniert wird. Ein Code, der auf eine feste Zahl an Einlösungen begrenzt ist, kann durch gleichzeitige Buchungen nicht überzeichnet werden.

Öffentliche Angebote auflisten

Inklusivleistungen

Einen Promo-Code prüfen

Rate Limits

Mit einem Code buchen

Auf dieser Seite