Reservations

Eine Reservation ist ein temporärer Platzhalter auf einem Ticket-Quota - die Plätze, die dein/deine Käufer:in gerade im Checkout-Prozess hat, sollen niemand anderes mehr buchen können, aber wenn der Checkout abgebrochen wird, müssen sie zurück in den Pool. Genau dafür ist die Reservation da.

Reservations gibt es für Tickets (/api/v4/tickets/reservations) und für Events (/api/v4/events/reservations). Bei Tours wird der Verfügbarkeitskonflikt direkt im Order-Create resp. in der Anfrage-Bearbeitung aufgelöst - dort gibt es keine eigene Reservations-Route.

Diese Seite klärt Lebenszyklus, Refresh-Mechanik und Edge Cases. Die konkreten curl-Beispiele stehen auf der Tickets-Seite bei "Eine Reservation erstellen".

Vollständige Endpoint- und Schema-Referenz: Swagger.

Mental-Modell

Eine Reservation hängt an einem Ticket plus Datum/Uhrzeit plus Menge:

TicketReservation
 ├── ticket_id .... welches Ticket
 ├── start_at ..... wann (Datum bei normal, Datum+Slot bei time_slot)
 ├── quantity ..... wie viele Plätze
 ├── token ........ String, identifiziert die Reservation in PUT/DELETE/Order
 └── valid_until .. Ablaufzeitpunkt

Solange valid_until in der Zukunft liegt, sind die Plätze blockiert und tauchen in capacity / capacities als belegt auf. Sobald valid_until durch ist, sind sie automatisch wieder verfügbar - ohne dass DELETE aufgerufen werden muss.

Lifecycle

                    POST /reservations
                          │
                          ▼
                    ┌──────────────┐
                    │   gültig     │  ◀──── PUT /reservations/:token
                    │              │        verlängert valid_until
                    │              │
                    └──────┬───────┘
                           │
              ┌────────────┴────────────┐
              ▼                         ▼
    DELETE /reservations/:token    valid_until erreicht
              │                         │
              ▼                         ▼
       ┌─────────────┐          ┌─────────────┐
       │  freigegeben │          │  abgelaufen  │
       │ (sofort)    │          │  (passiv)   │
       └─────────────┘          └─────────────┘
              │                         │
              └────────────┬────────────┘
                           ▼
              Plätze wieder im verfügbaren Pool

Endpoints

Endpoint	Aktion
`POST /api/v4/tickets/reservations`	Reservation erstellen, gibt `token` zurück
`PUT /api/v4/tickets/reservations/:token`	Quantity ändern und gleichzeitig `valid_until` verlängern
`DELETE /api/v4/tickets/reservations/:token`	Reservation freigeben, Plätze sofort verfügbar

Beachtet: die Endpoints sind unter /tickets/reservations (für Ticket-Reservations) bzw. /events/reservations (für Event-Reservations), nicht unter /reservations direkt. Reservations existieren als Sub-Resource der jeweiligen Resource.

Lebensdauer und Refresh

Default-Laufzeit: 5 Minuten ab created_at. Reicht typischerweise für einen schlanken Checkout (Personenzahl bestätigen, Kontaktdaten, Zahlung).
Refresh über PUT: jeder PUT setzt valid_until auf "jetzt + 5 Minuten" zurück. Das geht beliebig oft - aber:
Harte Obergrenze: zwischen created_at und valid_until dürfen nie mehr als 60 Minuten liegen. Eine Reservation kann sich also über mehrere PUTs hinweg insgesamt höchstens eine Stunde Lebenszeit aufbauen. Längere Checkout-Flüsse sollten erkennen, wann sie sich der Grenze nähern, und die Reservation entweder freigeben oder die Buchung abschließen.

API-User mit speziellen Permissions können valid_until beim Create explizit setzen (innerhalb der 60-Minuten-Obergrenze). Public-Token und Shop-Token nicht - sie bekommen immer den 5-Minuten-Default.

Was passiert bei Ablauf

Ein abgelaufener Token wird beim Versuch, ihn zu refreshen oder in einer Order zu verwenden, mit einem Validierungsfehler quittiert ("reservation not valid anymore"). Es gibt kein automatisches Wiederbeleben - bei Ablauf musst du eine neue Reservation anlegen, was bedeuten kann, dass die Plätze inzwischen weg sind.

Wichtig: ein abgelaufener Token muss nicht gelöscht werden. Der Server räumt sie selbst weg.

Reservation in der Order

Wenn die Reservation noch gültig ist und eine Order angelegt wird, übergibst du den Token im Order-Item:

{
  "order": {
    "items": [
      { "ticket_id": 247, "quantity": 2, "reservation_token": "RESERVATION_TOKEN" }
    ]
  }
}

Der Server zieht dann die Plätze aus genau dieser Reservation - nicht aus dem freien Pool. Wenn die Reservation in der Zwischenzeit abgelaufen ist, kommt der Order-Create mit Konflikt zurück.

Sobald die Order finalisiert ist, ist die Reservation aufgebraucht. DELETE kannst du dich sparen.

Stolperdrahte

Reservation-Token ist die ID. Für PUT und DELETE der Token-String aus dem Create-Response, nicht die numerische id.
Mehr Reservations = mehr Last für die Verfügbarkeitsanzeige. Jede gültige Reservation reduziert die für andere Kund:innen sichtbare Capacity. Bei Abbruch im Checkout aktiv DELETE callen, sonst halten die Plätze unnötig 5 Minuten lang.
Refresh ist gleichzeitig Quantity-Update. Ein PUT ohne Body refresht nicht - es verlangt das quantity-Feld, gleichzeitig wird die Lebensdauer verlängert. Wenn du nur die Lebenszeit verlängern wollen, senden das aktuelle Quantity ein zweites Mal.
Es gibt kein Lookup. du kannst eine Reservation nicht über die API abfragen ("ist dieser Token noch gültig?"). du merkst es erst beim PUT/DELETE/Order-Use, dass sie weg ist. Dementsprechend: ein erfolgreicher PUT ist gleichzeitig dein Health-Check.
Tours haben keine eigene Reservation-Route. Tour-Plätze entstehen mit der Anfrage-Bestätigung oder dem Order-Finalize. Das tickets/reservations-Pattern lässt sich nicht direkt auf Tours übertragen - dort regelt die Anfrage-Mechanik den Verfügbarkeits-Konflikt.
60-Minuten-Cap. Lange Checkouts (Login + Adresse + Payment + 3DS-Challenge) können knapp werden. Sobald du in den 50-Minuten-Bereich kommt, entweder Order anlegen oder die Reservation freigeben und neu starten.