Buchungen

Buchung anlegen

posthttps://open-api.mynextdays.com/v1/reservations

Eine Buchung anlegen und die Nächte im selben Schritt belegen.

Der Ablauf ist atomar: entweder es entstehen Buchung UND Kalenderbelegung, oder nichts. Ist die letzte Einheit inzwischen weg, kommt ein 409.

Ohne unit_id wählt das System die erste freie Einheit. Bei einem Objekt mit einer Einheit ist das immer diese eine.

total_amount ist der Gesamtpreis des Aufenthalts, wie DU ihn berechnet hast. Diese API rechnet ihn nicht nach — sie kennt die Aufenthaltspreis-Berechnung in v1 nicht (siehe „Grenzen von v1"). Die Währung muss zur Währung des Objekts passen, sonst 422.

Schlägt der Aufruf fehl, ohne dass eine Buchung entstanden ist (409, 422), ist dein Idempotency-Key danach wieder frei: du kannst denselben Vorgang mit demselben Schlüssel erneut versuchen, sobald der Zeitraum wieder frei ist. Nur bei einem Serverfehler bleibt er belegt — dann ist unklar, ob die Buchung doch entstanden ist, und du siehst zuerst über GET /v1/reservations nach.

Header

Idempotency-Keystring

Pflicht. Ein eindeutiger Wert je Vorgang (z. B. eine UUID). Wiederhole ihn bei einem erneuten Versuch — die erste Antwort wird dann wortgleich zurückgegeben, statt eine zweite Buchung zu erzeugen.

Anfrage-Körperpflicht

adultsintegerStandard 1

booked_atdate-time

Nur beim Import aus einem Fremdsystem: der ECHTE Zeitpunkt, zu dem der Gast dort gebucht hat. Ohne Angabe bleibt das Feld leer — es wird NICHT mit der aktuellen Zeit gefüllt, denn unsere Uhr ist nicht der Zeitpunkt einer fremden Handlung.

channelstringStandard direct

Wie die Buchung zustande kam. Standard direct: eine über diese API eingetragene Buchung gilt als Direktbuchung des Betriebs. ota_other für den Import aus einem Fremdsystem. Die Kanäle der angebundenen Portale (booking, airbnb, vrbo, portal) sind hier NICHT wählbar — sie entstehen ausschließlich aus dem echten Portal-Eingang, sonst wären Kanal-Auswertungen wertlos.

Erlaubt:directwebsiteota_other

check_indatepflicht

check_outdatepflicht

Abreisetag (die Nacht davor ist die letzte).

childrenintegerStandard 0

currencystringpflicht

Währung des Betrags (ISO 4217). MUSS zur Währung des Objekts passen; sonst 422. Es gibt keinen Standardwert.

external_refstring

Eigene Buchungsnummer, damit du die Buchung wiederfindest.

guestGast

Gastdaten. Ohne id wird ein Gast angelegt bzw. über die E-Mail-Adresse wiedererkannt.

infantsintegerStandard 0

notestring

petsintegerStandard 0

property_idstringpflicht

rate_plan_idstring

statusstringStandard confirmed

confirmed belegt den Kalender verbindlich, pending ebenfalls — eine Buchung sperrt in beiden Fällen die Nächte. Der Unterschied liegt in der Zahlungserwartung.

Erlaubt:pendingconfirmed

total_amountnumber | stringpflicht

unit_idstring

Bestimmte Einheit belegen. Ohne Angabe wählt das System die erste freie.

Antworten

201Successful Response

booked_atdate-time

Wann der GAST gebucht hat — aus der Quelle des Portals. null, wenn das Portal den Zeitpunkt nicht liefert. Dann ist received_at das Einzige, was wir wissen; verwende NICHT received_at als Buchungszeitpunkt.

cancelled_atdate-time

cancelled_by_partystring

Wer storniert hat: guest | host | ota | system.

channelstringpflicht

Buchungskanal: direct (Betrieb selbst, auch über diese API), portal (myBestDays-Marktplatz), website (eigene Seite), booking, airbnb, vrbo, ota_other.

check_indatepflicht

check_outdatepflicht

external_refstring

Buchungsnummer beim Portal.

guestGastpflicht

countrystring

emailstring

first_namestring

idstring

languagestring

last_namestring

namestring

phonestring

guestsGuestspflicht

Aufschlüsselung: adults, children, infants, pets.

idstringpflicht

nightsintegerpflicht

notestring

ota_namestring

Name des Portals, wenn die Buchung von dort kommt.

paidBetragpflicht

Ein Betrag mit seiner Währung. Nie eine Zahl ohne Währung.

amountstringpflicht

currencystringpflicht

payment_statusstring

property_idstringpflicht

rate_plan_idstring

received_atdate-timepflicht

Wann die Buchung bei uns eingegangen ist (unsere Uhr).

statusstringpflicht

Erlaubt:pendingconfirmedcancelledcompletedrequesteddeclinedexpired

totalBetragpflicht

Ein Betrag mit seiner Währung. Nie eine Zahl ohne Währung.

amountstringpflicht

currencystringpflicht

unit_idstring

Belegte Einheit. null bei Altbestand ohne Zuweisung oder wenn die Einheit gelöscht wurde.

updated_atdate-timepflicht

409Der Zeitraum ist inzwischen belegt, gesperrt oder vom Verkauf ausgenommen. Es ist KEINE halbe Buchung entstanden.

422Währung passt nicht zum Objekt, oder Daten sind unmöglich.

Sprache

Zugang

Nur in diesem Browser, nur für „Ausprobieren“ — der Wert wird nicht gespeichert und nicht an uns geschickt.

Anfrage

curl -X POST 'https://open-api.mynextdays.com/v1/reservations' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f9a1c30-6b1e-4d2a-9f77-4e0c1b2d3a55' \
  -d '{
  "property_id": "…",
  "check_in": "2026-09-10",
  "check_out": "2026-09-10",
  "total_amount": 0,
  "currency": "…"
}'

Ohne Token antwortet der Aufruf mit 401 — das ist der erwartete Weg.

Beispiel

{
  "id": "…",
  "property_id": "…",
  "status": "pending",
  "channel": "…",
  "check_in": "2026-09-10",
  "check_out": "2026-09-10",
  "nights": 1,
  "guests": {},
  "total": {
    "amount": "…",
    "currency": "…"
  },
  "paid": {
    "amount": "…",
    "currency": "…"
  },
  "received_at": "2026-09-10T14:00:00Z",
  "updated_at": "2026-09-10T14:00:00Z",
  "guest": {
    "country": "…",
    "email": "…",
    "first_name": "…",
    "id": "…"
  }
}