RoomRates API

When a user selects a hotel from search results, the Rooms & Rates API fetches all available rooms and rates from every supplier configured in your channel, deduplicates them, and returns a structured response. This is the most complex API in the engine — understanding what each object means before you implement will save significant time.

POST{baseEndpoint}/api/hotel/{hotelId}/roomsandrates/{token}

The five response objects — read this first

rooms

Raw room data from every configured supplier. If 5 suppliers return the same king room, you will see it 5 times here. Do not use this directly for rendering — use standardisedRooms instead.

rates

Raw rate data across all suppliers. In a single-room search, one recommendation maps to one rate. In a multi-room search, one recommendation can map to multiple rates — because some suppliers bundle all rooms into one rate ID, while others issue a separate rate ID per room.

Always check occupancies inside each rate to confirm how many rooms it covers and which room it belongs to.

recommendations

ZentrumHub's deduped, unique rate plans. One recommendation equals the cheapest available rate across all suppliers for a specific combination of room type, board basis, and refundability. This is where the engine's core deduplication logic surfaces. The recommendationId is what you pass to the Price API.

standardisedRooms

Mapping-service-normalised unique rooms. From 50 raw room entries across 10 suppliers, you get the actual 5 unique rooms here — deduplicated and normalised into consistent names and attributes. Only present if you have subscribed to the mapping service. Required for multi-supplier setups.

standardisedRoomGroups Use this

The developer-friendly object that clubs standardised rooms with their available rate plan options. Each entry gives you a room, its rate plans, and a pre-calculated total that already accounts for multi-room rate bundling across suppliers. Sorted cheapest to highest.

Use this as your primary data source for the room selection UI. It removes the need to manually cross-reference recommendations against standardisedRooms.

Multi-room searches — important detail

When searching for more than one room, some suppliers return a single rate ID covering all rooms together, while others return individual rate IDs per room. A single recommendation can therefore contain multiple rate IDs.

Do not assume one rate ID per recommendation in multi-room searches. Always check occupancies inside each rate object to confirm how many rooms it covers. standardisedRoomGroups handles this for you automatically — the total field already sums across all rate IDs in the group, regardless of how the supplier bundled them.

Using the mapping service

Mapping service is required for multi-supplier setups. Without it, standardisedRooms and standardisedRoomGroups will not appear in the response. You will need to use rooms and cross-reference via roomId in occupancies instead. For single-supplier accounts this is manageable; for multi-supplier it creates significant implementation overhead.

Token

Token is valid for 60 minutes. The same token from Search Init is passed in the URL. It carries the search context (check-in, check-out, occupancy) so you do not need to re-send those details. After 60 minutes the token expires and a new search is required.

Error codes

Code	Message
4001	Invalid data in request — refer to fields[] for details
4004	The hotel you selected is sold out
5000	Unknown system error — contact support with the correlationId

Interactive Explanation of room and rates

Request fired

rooms

rates

Dedup

recs

stdRooms

Groups

Step 1 of 7

Request fired

Client calls Rooms & Rates for a hotel

Your client

POST /roomsandrates

hotelId: HTL_001

token: srch_xyz

checkIn: 2025-06-10

rooms: 1 × 2 adults

→

API call

Booking Engine

✓ Validates channel
✓ Applies markup rules
✓ Identifies suppliers
✓ Fires parallel calls

→

parallel

HotelBeds

RateHawk

Expedia

TBO

Booking.com

The search token carries check-in, check-out & occupancy — you don't re-send it in every downstream call.

rooms object — raw room data from all suppliers. Names, images, bed config, facilities. No prices here.

HotelBeds

King Room