Reservation Guide

Before integrating the Reservations APIs, it's important to understand how reservation data is organized and processed. A reservation can include multiple room types, multiple rooms of the same type, and multiple guests. This guide explains how these components work together so you can build valid reservations and avoid common integration issues.

Why This Guide Exists

The reservation APIs support complex bookings with multiple room types, multiple rooms, and multiple guests. While the API reference explains each field individually, it doesn't show how those fields work together to represent a complete reservation.

This guide explains the reservation workflow, guest and room mapping, and GroupEventCode assignment so you can build valid reservations and avoid common integration mistakes that may prevent successful delivery to the hotel's PMS.

Reservation Workflow

Reservations are created in two phases, then optionally updated, and are pushed onward to the hotel's PMS via ResNotif.

1. Create a pending reservation (Phase 1). Call POST /api/v1/cultswitch/reservations/create with guest, room, and stay details. The reservation is held in a pending state — nothing has been confirmed with the hotel yet.
2. Confirm the reservation (Phase 2). Call POST /api/v1/cultswitch/reservations/confirm to finalize the booking. This is the point at which the reservation becomes binding.
3. Update payment details (optional). Call POST /api/v1/cultswitch/reservations/cc-update if credit card data needs to be added or changed after creation.
4. Delivery to the hotel PMS. Confirmed reservations are sent onward to the property's PMS (e.g. SiteMinder) as a ResNotif message. This is where the guest/room/rate-plan mapping described below is consumed — a malformed mapping here is what causes deliveries to fail.
5. Look up a reservation. Call GET /api/v1/cultswitch/reservations/v2 with the booking or channel ID at any point to retrieve current reservation status.

Guest Mapping

Every physical room booked in a reservation gets its own <ResGuest> node in the outbound ResNotif message. The node is identified by a composite reference, ResGuestRPH, built from three parts:

Segment	Field	Meaning
11	IndexNumber	A sequence number for the reservation line itself. Stays constant across all rooms in this example.
509364	RoomTypeCode	The Room ID of the sellable unit being booked (from the Rooms API).
2533832	RatePlanCode	The Rate Plan ID that prices this room (from the Rate Plans / Products API).

A single reservation can contain several such nodes — one per guest, per booked room — each carrying its own GroupEventCode to distinguish which physical room instance the guest belongs to.

Room Mapping

A room booking is identified by the combination of RoomTypeCode and RatePlanCode. Together, these values represent a unique product (a specific room type sold under a specific rate plan).

When multiple units of the same product are booked, they share the same RoomTypeCode and RatePlanCode. Each room is distinguished only by its GroupEventCode.

A different room type - or the same room type with a different rate plan—is treated as a new product and starts its own GroupEventCode sequence from 1.

GroupEventCode Assignment Rules

In practice: for each distinct product in the reservation, number its guests 1, 2, 3… based only on how many units of that product were booked. Move to the next product and start again from 1 — regardless of how many ResGuest nodes came before it in the message.

Worked Example: A Real Delivery Failure

The reservation below was rejected by the hotel's PMS (SiteMinder) because of exactly the mistake described above.

Property	Buddy Lodge Hotel (Objekt-Id: 137476)
Reservation ID	20260705-511480-1257574694 (24522062)
Created	2026-07-04 13:45:01 GMT
Failure	Not delivered to hotel PMS (SiteMinder) via ResNotif
Rooms booked	2 × Superior King Room (Room ID 509364, Rate Plan ID 2533832) + 1 × Superior Twin Room (Room ID 510576, Rate Plan ID 2533830)

Incorrect mapping — GroupEventCode continues across room types

2 × Superior King Room (509364 / 2533832):

<ResGuest ResGuestRPH="11-509364-2533832" GroupEventCode="1">
<ResGuest ResGuestRPH="11-509364-2533832" GroupEventCode="2">

1 × Superior Twin Room (510576 / 2533830):

<ResGuest ResGuestRPH="11-510576-2533830" GroupEventCode="3">

Correct mapping — each room type restarts at 1

1 × Superior Twin Room (510576 / 2533830):

<ResGuest ResGuestRPH="11-510576-2533830" GroupEventCode="1">

2 × Superior King Room (509364 / 2533832):

<ResGuest ResGuestRPH="11-509364-2533832" GroupEventCode="1">   (first room guest)
<ResGuest ResGuestRPH="11-509364-2533832" GroupEventCode="2">   (second room guest)

Where: 11 = IndexNumber, 509364 / 510576 = RoomTypeCode, 2533832 / 2533830 = RatePlanCode.

Common Integration Mistakes

Don't	Do
Use a single GroupEventCode counter for the entire reservation.	Restart the GroupEventCode sequence for each unique RoomTypeCode + RatePlanCode combination.
Assume RoomTypeCode alone identifies a product.	Treat the RoomTypeCode and RatePlanCode pair as the unique product identifier.
Use the same counter for IndexNumber and GroupEventCode.	Generate IndexNumber and GroupEventCode independently, as they serve different purposes.
Validate only single-room reservations.	Test reservations with multiple room types and quantities to verify guest and room mapping.