Ratenverwaltung

Die Katalog- und Angebots-Endpunkte sind schreibgeschützt. Diese Endpunkte lassen eine Integration den Ratenaufbau verwalten: Ratenpläne anlegen, Saisonpreise darüberlegen, Inklusivleistungen und Guthaben bündeln und Promotions mit Codes fahren. So steuert ein Hotel seine Veridien-Preise von der eigenen Website oder aus dem Back Office.

Jeder Endpunkt hier verlangt den Scope rates:write, außer den lesenden Verwaltungsaufrufen (GET), die rates:read verlangen.

Eine Promotion ist ein Ratenplan

Eine Promotion ist ein Ratenplan mit kind: "promotion" und einer Ableitung von einem Basisplan. Es gibt keinen eigenen Promotion-Endpunkt: Sie legen eine über dieselben /rate-plans-Endpunkte an und bearbeiten sie dort, indem Sie kind, derived_from_id, derivation_type und derivation_value setzen.

Idempotenz

Jeder Schreibvorgang hier ist eine ändernde Anfrage. Senden Sie einen Idempotency-Key-Header, damit Wiederholungen sicher sind, wie unter Konventionen beschrieben.

POST /rate-plans

Feld	Erforderlich	Hinweise
`room_type_id`	ja	Der Zimmertyp, den dieser Plan bepreist.
`name`	ja	Interner Name (1 bis 100 Zeichen).
`base_price`	ja	Nachtpreis als Dezimalzeichenkette, zum Beispiel `"120.00"`.
`currency`	nein	Muss die Basiswährung der Unterkunft oder eine konfigurierte Währung sein. Standard ist die Basiswährung.
`public_name`	nein	Name für den Gast.
`description`	nein	Kurztext für den Gast.
`image_url`	nein	Absolute URL.
`extra_guest_charge`	nein	Aufpreis pro Nacht und Gast über der Basisbelegung. Standard `"0.00"`.
`single_guest_discount`	nein	Standard `"0.00"`.
`single_guest_discount_type`	nein	`fixed` oder `percent`. Standard `fixed`.
`min_los` / `max_los`	nein	Grenzen der Aufenthaltsdauer in Nächten.
`booking_window_start` / `_end`	nein	Wann der Plan gebucht werden darf (`YYYY-MM-DD`).
`stay_window_start` / `_end`	nein	Wann der Plan bewohnt werden darf.
`active_for_booking_engine`	nein	Standard `false`.
`active_for_channels`	nein	Standard `false`.
`kind`	nein	`standard` (Standard) oder `promotion`.
`derived_from_id`	nein	Bei einer Promotion: der Basisplan, von dem sie abgeleitet ist.
`derivation_type`	nein	`percent`, `fixed` oder `perPerson`. Zusammen mit `derived_from_id` erforderlich.
`derivation_value`	nein	Dezimalzeichenkette mit Vorzeichen. Negativ ist ein Rabatt, zum Beispiel `"-20.00"`. Zusammen mit `derived_from_id` erforderlich.

curl -X POST "$VRDN_BASE/rate-plans" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
    "name": "Bed & Breakfast",
    "base_price": "120.00",
    "public_name": "Bed & Breakfast",
    "description": "A full breakfast for two each morning.",
    "active_for_booking_engine": true
  }'

{ "rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02" }

Setzen Sie kind, den übergeordneten Plan und eine negative Ableitung. Legen Sie sie hinter einen Code, indem Sie einen anlegen (siehe unten) und requires_promo_code: true setzen.

curl -X POST "$VRDN_BASE/rate-plans" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
    "name": "Advance Purchase, save 20%",
    "base_price": "120.00",
    "kind": "promotion",
    "derived_from_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02",
    "derivation_type": "percent",
    "derivation_value": "-20.00",
    "active_for_booking_engine": true
  }'

Ein abgeleiteter Plan braucht sowohl derivation_type als auch derivation_value, sonst wird die Anfrage abgelehnt. Sein Preis ist immer der aktuelle Preis des übergeordneten Plans mit angewandter Ableitung, er folgt dessen Saisonpreisen also automatisch.

PATCH /rate-plans/{id}

Senden Sie nur die Felder, die Sie ändern wollen. Akzeptiert dieselben Felder wie beim Anlegen (außer room_type_id), dazu is_active.

{ "rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02", "updated": true }

DELETE /rate-plans/{id}

Der Standard-Ratenplan lässt sich nicht löschen (403). Reservierungen, die bereits auf einem gelöschten Plan gebucht wurden, behalten den Preis, der ihnen genannt wurde.

{ "rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02", "deleted": true }

Intervalle legen datumsabhängige Preise und Aufenthaltsregeln über den Basispreis eines Plans. Intervalle auf demselben Plan dürfen sich nicht überlappen, ein überlappender Zeitraum liefert 409.

GET /rate-plans/{id}/intervals

Verlangt rates:read.

POST /rate-plans/{id}/intervals

Feld	Erforderlich	Hinweise
`name`	ja	Zum Beispiel „Hochsaison“.
`start_date` / `end_date`	ja	`YYYY-MM-DD`. Der Start muss vor dem Ende liegen.
`price_mon` … `price_sun`	nein	Preis je Wochentag. Ein leer gelassener Tag fällt auf den Basispreis zurück.
`min_stay` / `max_stay`	nein	Regeln zur Aufenthaltsdauer für diesen Zeitraum.
`closed_to_arrival` / `closed_to_departure` / `stop_sell`	nein	Verfügbarkeits-Flags. Standard `false`.
`extra_guest_charge` / `single_guest_discount`	nein	Überschreibungen je Saison. Standard `"0.00"`.

curl -X POST "$VRDN_BASE/rate-plans/5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02/intervals" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Season",
    "start_date": "2026-12-01",
    "end_date": "2027-03-31",
    "price_mon": "180.00", "price_fri": "210.00",
    "min_stay": 3
  }'

{ "interval_id": "d8a4c2f6-5e9b-4d7a-8f1c-3b6e0a9d5c28" }

PATCH /intervals/{id}
DELETE /intervals/{id}

PATCH akzeptiert jedes Intervallfeld und prüft die Regel gegen Überlappungen erneut.

Eine Inklusivleistung ist entweder ein Perk (ein fest enthaltener Posten) oder ein Guthaben (ein verwendbares Budget für eine Kategorie, etwa ein Spa-Guthaben). Inklusivleistungen werden als ganze Liste gesetzt: Ein POST ersetzt den kompletten Satz an Inklusivleistungen des Plans.

GET /rate-plans/{id}/inclusions

Verlangt rates:read.

POST /rate-plans/{id}/inclusions

Feld	Erforderlich	Hinweise
`label`	ja	Bezeichnung für den Gast, zum Beispiel „Spa-Guthaben“.
`allocated_amount`	ja	Wert als Dezimalzeichenkette. `"0.00"` für einen kostenlosen Perk.
`frequency`	ja	`perStay`, `perNight`, `perGuest` oder `perGuestPerNight`.
`inclusion_kind`	nein	`perk` (Standard) oder `credit`.
`revenue_category`	ja	`room`, `fnb`, `spa`, `excursions`, `activities` oder `other`. Bei einem Guthaben ist das die Kategorie, für die es gilt.
`service_item_id`	nein	Verknüpfung zu einem Serviceartikel aus dem Katalog.
`currency`	nein	Standard ist die Währung des Plans.
`included_quantity`	nein	Standard 1.

curl -X POST "$VRDN_BASE/rate-plans/5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02/inclusions" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inclusions": [
      { "label": "Daily breakfast for two", "allocated_amount": "20.00", "frequency": "perGuestPerNight", "revenue_category": "fnb" },
      { "label": "Spa credit", "allocated_amount": "150.00", "frequency": "perStay", "inclusion_kind": "credit", "revenue_category": "spa" }
    ]
  }'

{ "rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02", "count": 2 }

Ein Code schaltet eine Promotion frei. Der Rabatt steckt in der Promotion, ein Code trägt also nie eine eigene Ersparnis. Hängen Sie Codes an den Plan, den sie freischalten.

GET /rate-plans/{id}/promo-codes

Verlangt rates:read.

POST /rate-plans/{id}/promo-codes

Feld	Erforderlich	Hinweise
`code`	ja	3 bis 40 Zeichen. Wird in Großbuchstaben gespeichert und abgeglichen.
`valid_from` / `valid_to`	nein	Zeitfenster als `YYYY-MM-DD`.
`max_redemptions`	nein	Obergrenze für die Gesamtzahl der Einlösungen. Weglassen für unbegrenzt.
`max_per_guest`	nein	Obergrenze je Gast.

curl -X POST "$VRDN_BASE/rate-plans/e2a9d7c4-3f6b-4c1e-9a8d-7b5f0c2e4a19/promo-codes" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "EARLYBIRD25", "max_redemptions": 100 }'

{ "promo_code_id": "a5e2c8f1-7d4b-4a6e-b9c3-0f8d2a5e7c41", "code": "EARLYBIRD25" }

PATCH /promo-codes/{id}
DELETE /promo-codes/{id}

PATCH akzeptiert valid_from, valid_to, max_redemptions, max_per_guest und is_active. Die Codezeichenkette selbst lässt sich nicht ändern, weil Buchungen den Code einfrieren, mit dem sie getätigt wurden. Löschen Sie ihn und legen Sie stattdessen einen neuen an. Einen Code zu löschen, wirkt sich nicht auf Reservierungen aus, die bereits damit gebucht wurden.

Einen Ratenplan anlegen

Eine Promotion anlegen

Einen Ratenplan aktualisieren

Einen Ratenplan löschen

Saisonintervalle

Intervalle auflisten

Ein Intervall anlegen

Ein Intervall aktualisieren und löschen

Inklusivleistungen und Guthaben

Inklusivleistungen auflisten

Inklusivleistungen ersetzen

Promo-Codes

Codes auflisten

Einen Code anlegen

Einen Code aktualisieren und löschen

Auf dieser Seite