1. Revenue Management Systems (RMS) Implementation Guide
  2. RMS Use Cases
  3. Reservation Management

Reservation Management

Since rooms can be associated with both reservations and business blocks (which have distinct data models), the methods for retrieving relevant data for each are outlined in different sections in this guide. You can retrieve past and future reservation information for a hotel from OPERA Cloud.

Use Case Description Operation
Retrieve summary of reservations activity on a daily basis You can retrieve a daily summary of reservations for a property by given dates. This can be useful for an overview of reservation activity on a daily basis. getReservationsDailySummary (asynchronous)
Retrieve detailed reservation information You can retrieve detailed information about reservations stored in the OPERA Cloud system. This can be useful to analyze reservation data for forecasting and pricing strategies. getReservations (synchronous)
Retrieve Reservation Rate Break Down You can retrieve summary rate information based on the given rate plan code, room type, number of adults, and specified date range. This can be useful to analyze pricing trends and set competitive rates. getRateInfo
Retrieve Reservation Stay Records Fetches detailed records of a guest's stays at a hotel. This can be useful for analyzing guest history and behavior patterns. getStayHistory

1. Retrieve summary of reservations activity on a daily basis using getReservationsDailySummary

You must use the asynchronous operation getReservationsDailySummary to capture the daily summary of reservations. This summary captures the key elements of the reservation and stay details, providing an overview of the booking, guest information, stay details, and revenue generated. It can be used for operational planning, revenue management, and reporting purposes.

Business Logic Comments
Retrieving the initial Reservation Summary Data using start/endDate

The reservation summary data can be requested using startDate/endDate to fetch the reservation summary data for a given date range:

  • startDate: The beginning date to filter reservations.
  • endDate: The ending date to filter reservations.

Other critical parameters include:

  • hotelId: Specifies the hotel for which reservations are being queried.
  • reservationId: Retrieves a specific reservation by its unique ID.
  • startDate: The beginning date to filter reservations.
  • endDate: The ending date to filter reservations.
  • status: Filters reservations based on their current status.
  • guestName: Filters reservations by the guest's name.
  • roomType: Filters reservations by the type of room booked.
  • rateCode: Filters reservations based on the rate code applied.
Retrieving the incremental Reservation Summary Data using startLastModifiedDate/endLastModifiedDate

The reservation summary data can be requested using startLastModifiedDate/endLastModifiedDate to fetch the reservation summary data for a given date range:

  • startLastModifiedDate: Filters reservations that have been modified on or after this date.
  • endLastModifiedDate: Filters reservations that have been modified on or before this date.
Key Considerations
  • The hotelId parameter is essential to identify which hotel's reservations are being queried.
  • Keep the date range (startDate and endDate or startLastModifiedDate and endLastModifiedDate) as narrow as possible to reduce the search window to a specific time frame.
  • Filtering options such as status, guestName, roomType, and rateCode allow for more precise and relevant search results.
Key Response Data Elements

The key response data elements include:

  • Hotel Information:
    • Hotel ID: Identifier for the hotel.
  • Reservation Information:
    • Reservation IDs: Unique identifiers for the reservation, including confirmation and reservation types.
    • Status: Current status of the reservation (for example, Prospect, Confirmed).
    • Type: Type of reservation system used.
    • Room Count: Total number of rooms reserved.
  • Guest Information:
    • Country: Origin country of the guest.
    • Adults: Number of adults included in the reservation.
    • Children: Breakdown by age groups (1-3, 4-12, 13-17) with counts.
  • Booking Information:
    • Booking and Creation Dates: Specific dates and times detailing when the booking was made and when the reservation record was created or last modified.
  • Stay Details:
    • Arrival and Departure Dates: Specific start and end dates of the guest's stay.
    • Room Type: Description of the room type booked.
    • Daily Summary: Includes rate codes, amounts, and market codes.
    • Transaction Date: The specific date of the transaction.
  • Revenue Information:
    • Revenue by Category: Detailed breakdown of room, food and beverage, and other revenues.
    • Total Revenue: Sum total of all revenue generated from the reservation.
    • Tax Details: Specific tax amounts associated with the booking.
Sample API request/response
  1. startReservationsDailySummary

1.1. startReservationsDailySummaryProcess (requested using the parameters startDate/endDate)

startReservationsDailySummaryProcess (startDate/endDate)

Endpoint:
POST {{HostName}}/rms/rsv/async/v1/externalSystems/{{ExternalSystemId}}/hotels/{{HotelId}}/reservations/dailySummary


Request Body:
{"criteria": {
"hotelId": {{HotelId}},
"timeSpan": {
"startDate": "2022-09-02",
"endDate": "2022-09-02"
}
}
}



Sample Successful Response:
202 Accepted

1.2. startReservationsDailySummaryProcess (requested using the parameters startLastModifiedDate/endLastModifiedDate)

startReservationsDailySummaryProcess (startLastModifiedDate/endLastModifiedDate)

Endpoint:
POST {{HostName}}/rms/rsv/async/v1/externalSystems/{{ExternalSystemId}}/hotels/{{HotelId}}/reservations/dailySummary


Request Body:
{
"criteria": {
"hotelId": {{HotelId}},
    "lastModifiedDate": {
"startLastModifiedDate": "2023-10-04",
"endLastModifiedDate": "2023-10-04"
}
  }
}


Sample Successful Response:
202 Accepted

2. getReservationsProcessStatus

getReservationsProcessStatus

Endpoint:
HEAD  {{HostName}}/rms/rsv/async/v1/externalSystems/{{ExternalSystemId}}/hotels/{{HotelId}}/reservations/dailySummary/{{RequestId1}}


Sample Successful Response:
201 Created
(You are ready to proceed to Step 3)

3. getReservationsDailySummary

getReservationsProcessStatus

Endpoint:

GET  {{HostName}}/rms/rsv/async/v1/externalSystems/{{ExternalSystemId}}/hotels/{{HotelId}}/reservations/dailySummary/{{RequestId2}}

Sample Successful (200 OK) Response:
{
    "reservations": [
        {
            "hotelId": "BAA_AUTO",
            "reservationIdList": [
                {
                    "id": "1822428",
                    "type": "Confirmation"
                },
                {
                    "id": 1038537,
                    "type": "Reservation"
                },
                {
                    "type": "ParentReservation"
                }
            ],
            "externalReferences": [],
            "resvStatus": "PROSPECT",
            "sharedYn": "N",
            "arrival": "2022-09-02T00:00:00",
            "departure": "2022-09-03T00:00:00",
            "bookingDate": "2023-04-06T00:00:00",
            "resvType": "GDS-SESSION",
            "noOfRooms": "1",
            "guestCountry": "US",
            "createDateTime": "2023-04-06T21:18:19",
            "lastModifiedDate": "2023-04-06T21:18:19",
            "createdHotelDateTime": "2023-04-06T21:18:19",
            "modifiedHotelDateTime": "2023-04-06T21:18:19",
            "children1": 0,
            "children2": 0,
            "children3": 0,
            "origin_of_booking": "FOR",
            "dailySummary": [
                {
                    "rateCode": "HAPPY2",
                    "rateAmount": "150",
                    "rateAmountCurrency": "USD",
                    "marketCode": "RETB",
                    "roomType": "Z1DLK",
                    "bookedRoomType": "Z1DLK",
                    "netRateAmount": "150",
                    "netRateAmountCurrency": "USD",
                    "roomRevenue": "150",
                    "roomRevenueCurrency": "USD",
                    "fbRevenueCurrency": "USD",
                    "otherRevenueCurrency": "USD",
                    "totalRevenue": "150",
                    "totalRevenueCurrency": "USD",
                    "tax": "33.75",
                    "taxCurrency": "USD",
                    "roomTypeCharged": "Z1DLK",
                    "trxDate": "2022-09-02T00:00:00",
                    "sourceCode": "FOR",
                    "adults": "1"
                }
            ]
        }
    ]
}

2. Retrieve Detailed reservation using getReservations

It is highly recommended that you use the asynchronous operation getReservationsDailySummary for your reservation use cases. However, if you want to fetch detailed information of up to 1000 reservation records including the reservation, guest, room, and rate details, you can use the synchronous operation getReservations.

Note:

To save additional costs and calls to the system, only use this synchronous operation when absolutely necessary.

This data is useful to analyze and optimize pricing, availability, and overall revenue strategy. The following is a breakdown of the kind of data it returns and how you can use it. 

Business Logic Comments

Filtering the Reservation Data
You can filter the reservation data based on the following:

  • reservationId: Fetch specific reservation by ID.

  • startDate: Filter reservations starting from this date.

  • endDate: Filter reservations ending on this date.

  • status: Filter by reservation status.

  • guestName: Filter by guest name.

  • roomType: Filter by room type.

  • rateCode: Filter by rate code.

  • wildCardSearch: If you are not sure of the search criteria, you can search by text by entering a sequence of characters. This will search the reservations that match this text in any of the response fields.

Key Response Data Elements

The key response data elements include:

  • Reservation ID: Unique identifier for the reservation.

  • Status: Current status of the reservation (e.g., confirmed, canceled, checked-in).

  • Guest Details: Information about the guest, including name, email, and phone number.

  • Room Details: Details about the room, including room type, room number, check-in and check-out dates.

  • Guest Stay Details: Information about the guest stay details like arrivalDate, departureDate. 

  • Rate Details: Information about the rate, including rate code, description, amount, and currency.

  • Package Details: Information about the packages included in the reservation, such as packageCode, packageDescription, and packageAmount.

  • Special Requests: Any special requests made by the guest.

  • Payment Details: Payment method information, including card type and last four digits of the card number.

Sample API request/response

getReservations

getReservations (wild card search)

Endpoint: 
{{HostName}}/rsv/v1/hotels/{{HotelId}}/reservations?text=jones


Sample Successful (200 OK) Response:
"getReservations": {
        "response": {
            "reservations": {
                "reservationInfo": [
                    {
                        "reservationIdList": [
                            {
                                "id": "236552",
                                "type": "Reservation"
                            },
                            {
                                "id": "379252",
                                "type": "Confirmation"
                            },
                            {
                                "id": "5735646",
                                "type": "ExternalReference"
                            }
                        ],
                        "roomStay": {
                            "arrivalDate": "2020-05-08",
                            "departureDate": "2020-05-09",
                            "originalTimeSpan": {
                                "startDate": "2020-05-08",
                                "endDate": "2020-05-09"
                            },
                            "expectedTimes": {
                                "reservationExpectedArrivalTime": "2020-05-08 19:17:25.0",
                                "reservationExpectedDepartureTime": "2020-05-09 13:30:00.0"
                            },
                            "adultCount": "2",
                            "childCount": "1",
                            "roomClass": "ALL",
                            "roomType": "STDQ",
                            "numberOfRooms": "1",
                            "roomNumber": "2010",
                            "ratePlanCode": "UPGRADE",
                            "rateAmount": {
                                "amount": "100",
                                "currencyCode": "USD"
                            },
                            "rateSuppressed": false,
                            "fixedRate": false,
                            "guarantee": {
                                "guaranteeCode": "CHECKED IN",
                                "shortDescription": "Checked In"
                            },
                            "marketCode": "CORP",
                            "sourceOfBusiness": "CWEB",
                            "sourceOfBusinessDescription": "Website",
                            "balance": {
                                "amount": "115.55",
                                "currencyCode": "USD"
                            },
                            "roomTypeCharged": "STDQ",
                            "roomNumberLocked": false,
                            "pseudoRoom": false
                        },
                        "reservationGuest": {
                            "givenName": "Sarah",
                            "middleName": "F",
                            "surname": "Jones",
                            "phoneNumber": "415 555 0100 ",
                            "email": "Sarah@example.com",
                            "language": "E",
                            "vip": {
                                "vipCode": "GOLD",
                                "vipDescription": "Gold"
                            },
                            "address": {
                                "cityName": "Redwood Shores",
                                "postalCode": "94065",
                                "state": "CA",
                                "country": {
                                    "code": "AU"
                                }
                            },
                            "anonymization": {},
                            "guestLastStayInformation": {
                                "lastStayRoom": "304"
                            },
                            "guestRestricted": false,
                            "nameType": "Guest",
                            "id": "288106",
                            "type": "Profile"
                        },
                        "reservationPaymentMethod": {
                            "paymentMethod": "CA"
                        },
                        "displayColor": "GREEN",
                        "reservationIndicators": [
                            {
                                "indicatorName": "EXTERNALREFERENCES",
                                "count": "1"
                            },
                            {
                                "indicatorName": "PREFERENCE",
                                "count": "3"
                            },
                            {
                                "indicatorName": "PROFILENOTE",
                                "count": "2"
                            },
                            {
                                "indicatorName": "PACKAGEITEM",
                                "count": "1"
                            },
                            {
                                "indicatorName": "OPENFOLIO"
                            },
                            {
                                "indicatorName": "STAYREVENUE"
                            },
                            {
                                "indicatorName": "HISTORYFUTURE",
                                "count": "3"
                            },
                            {
                                "indicatorName": "COMMUNICATION",
                                "count": "6"
                            },
                            {
                                "indicatorName": "ASSOCIATEDPROFILES",
                                "count": "1"
                            }
                        ],
                        "sourceOfSale": {
                            "sourceType": "PMS",
                            "sourceCode": "HOTEL1"
                        },
                        "waitlist": {},
                        "advanceCheckIn": {
                            "advanceCheckedIn": true,
                            "expectedReturnTime": "2020-05-09 15:00:00.0"
                        },
                        "hotelId": "HOTEL1",
                        "hotelName": "Hotel One",
                        "roomStayReservation": true,
                        "createDateTime": "2020-01-09 01:02:48.0",
                        "lastModifyDateTime": "2020-02-26 03:00:08.0",
                        "reservationStatus": "CheckedOut",
                        "computedReservationStatus": "CheckedOut",
                        "walkInIndicator": true,
                        "commissionPayoutTo": "None",
                        "paymentMethod": "CA",
                        "preRegistered": false,
                        "openFolio": true,
                        "allowMobileCheckout": false,
                        "optedForCommunication": false
                    }
                ],
                "totalPages": "1",
                "offset": "20",
                "limit": "20",
                "hasMore": true,
                "totalResults": "1"
            }
        }
    }
}

3. Retrieve Reservation Rate Break Down using getRateInfo The synchronous getRateInfo can be used to retrieve a detailed breakdown of reservation rates. This information includes rate codes, room types, and rate amounts, which are crucial for analyzing pricing strategies and ensuring accurate billing. The data can be utilized for revenue management, operational planning, and detailed reporting purposes.

Business Logic Comments
Retrieving the Reservation Rate Breakdown Data

You can retrieve the reservation rate breakdown data based on the following parameters:

  • id: The unique identifier for the specific reservation or block being queried.
  • ratePlanCode: The code of the rate plan being queried.
  • roomType: The type of room associated with the rate plan.
  • adults: Number of adults included in the reservation.
  • criteriaStartDate: The start date for the rate criteria.
  • criteriaEndDate: The end date for the rate criteria.
  • hotelId: Specifies the hotel for which the rate information is being queried.
Key Response Data Elements

Rate Information includes:

  • Rate Plan Code: Identifier for the rate plan.
  • Room Type: Type of room the rate applies to.
  • Rate Amount: The price of the room per night.
  • Rate Currency: The currency in which the rate is denoted.
  • Rate Description: Description of the rate plan.
  • Market Code: Market segment associated with the rate.
  • Source Code: Source of the booking (for example, direct, OTA).
  • Total Revenue: Calculated total revenue based on the rate and duration.
  • Tax Amount: Applicable taxes on the rate.
  • Net Rate Amount: Rate amount after applying any discounts or adjustments.
  • Daily Rate Details: Breakdown of rates on a daily basis within the specified date range.
Sample API request/response

getRateInfo

Endpoint:
GET {{HostName}}/rsv/v1/hotels/{{HotelId}}}/reservations/rateInfo?ratePlanCode=BC&riteriaStartDate=2023-11-29&criteriaEndDate=2023-11-29


Sample Successful (200 OK) Response:
{
    "summary": {
        "details": [
            {
                "summaryDate": "2023-11-29",
                "revenue": 0,
                "package": 0,
                "tax": 0,
                "gross": 0,
                "net": 0,
                "ratePlanCode": "BC",
                "currencyCode": "NOK"
            }
        ],
        "gross": 0,
        "net": 0,
        "currencyCode": "NOK",
        "start": "2023-11-29",
        "end": "2023-11-29",
        "hasSuppressedRate": false
    },
    "links": []
}

4. Retrieve Reservation Stay Records using getStayHistory

The synchronous operation getStayHistory is designed to retrieve detailed records of a guest's stays at a hotel. This data provides a comprehensive overview of a guest’s past visits, which is valuable for various operational and analytical purposes.

Business Logic Comments
Retrieving the Reservation Stay Records

Once a guest checks out, you can retrieve the reservation stay records history based on the following parameters:

  • profileId: Fetches the stay history for the specific guest profile.
  • hotelIds: Filters the stay history to include only specified hotels.
  • reportType: Defines the type of report to generate (for example, ProfileStayRecords for stay history).
  • stayFrom: The beginning date to filter the stays.
  • stayTo: The ending date to filter the stays.
  • summary: Determines whether the response includes a summary (true) or detailed records (false).
Key Response Data Elements

Stay History Information Includes the following:

Stay Records:

  • Hotel ID: Identifier for the hotel where the stay occurred.
  • Arrival Date: Date when the guest checked in.
  • Departure Date: Date when the guest checked out.
  • Room Type: Type of room the guest stayed in.
  • Room Number: Specific room number assigned to the guest.
  • Rate Code: Code representing the rate plan applied.
  • Rate Amount: The amount charged per night.
  • Rate Currency: Currency in which the rate is denoted.
  • Total Revenue: Total revenue generated from the stay.
  • Room Revenue: Revenue from the room charges.
  • Food & Beverage Revenue: Revenue from food and beverage purchases.
  • Other Revenue: Revenue from other services or products.
  • Special Requests: Any special requests made by the guest during their stay.
  • Payment Method: Method of payment used by the guest.
  • Card Type: Type of credit card used (if applicable).
  • Last Four Digits: Last four digits of the card used for payment.

Guest Preferences and Comments:

  • Preferences: Specific preferences indicated by the guest.
  • Comments: Any additional comments or notes related to the stay.
Sample API request/response

getStayHistory

Endpoint:
GET {{HostName}}/crm/v1/profiles/{{ProfileId}}/stayHistory?fetchInstructions=HistoryReservation


Sample Successful (200 OK) Response:
{
    "profileStayDetails": {
        "reservationInfoList": {
            "historyList": {
                "reservationInfo": [
                    {
                        "reservationIdList": [
                            {
                                "id": "36901",
                                "type": "Reservation"
                            },
                            {
                                "id": "3577366",
                                "type": "Confirmation"
                            }
                        ],
                        "roomStay": {
                            "arrivalDate": "2023-05-23",
                            "departureDate": "2023-05-24",
                            "roomType": "QE",
                            "ratePlanCode": "48HRS",
                            "rateAmount": {
                                "amount": 2590,
                                "currencyCode": "NOK"
                            },
                            "rateSuppressed": false,
                            "guarantee": {
                                "guaranteeCode": "GTDCCOPI"
                            }
                        },
                        "attachedProfiles": [],
                        "hotelId": "SH765",
                        "reservationStatus": "NoShow",
                        "computedReservationStatus": "NoShow"
                    }
                ],
                "hasMore": false,
                "totalResults": 1
            },
            "futureList": {
                "hasMore": false,
                "totalResults": 0
            }
        }
    },
    "links": []
}

Parent topic: RMS Use Cases