Documentation

Use Cases

In this part of our documentation, we would like to explain to you, how to use our API in order to implement some of the well-known scenarios.

Revenue Management System

Revenue management systems obtain information about reservations, revenue and pricing from MEWS. And based on the data they may recommend or directly update rate prices, give future revenue estimates, predict occupancy etc. In bigger hotels, there are might be more than 50k reservations in a year, so it is necessary to always limit the API calls in terms of potential data size, in order to avoid timeouts, network errors etc. A recommended approach, how to implement a RMS client is described below. Folowing these guidelines should ensure that both our servers and RMS clients are not unnecessiraly overutilized.

Initial Data Pull

Performed once when setting up the connection, because the RMS needs to obtain historical data.

RMS should obtain the reservations in time-limited batches using Get All Reservations with Reservation Time Filter set to Start (that will give you all reservations with arrival time colliding with the selected interval). Size of the batches depends on size of the hotel and its occupancy, but in general weekly batches are recommended and should work well even for big hotels (1000+ units). In order to get reservations e.g. in the past year, RMS should call Get All Reservations sequentially 52 times (one call for each week in the past year). That would give RMS all reservations that have arrival within the past year. To obtain revenue items associated with reservations, Items should be set to true in the Extent parameter of the Get All Reservations operation.

One can take advantage of the fact that reservations are usually booked a few weeks or months in advance. The further in future, the lower the occupancy, so the reservation batch length may increase with the distance to future from current date. E.g. weekly batches can be used only for the first three months of the future year when there is higher occupancy. And for the remaining 9 months, monthly batches would be sufficient. This would reduce the API call count from 52 to 21 (12 weekly batches + 9 monthly batches).

Sometimes the data obtained through the previous two steps are not sufficient enough for RMS. So additionally, RMS can pull e.g. business segments via Get All Business Segments or rates via Get All Rates. Note that it is important to get the reservations and revenue first and the additional data later after that. If done the other way around, it might happen that RMS would receive a reservation with e.g. RateId which does not correspond to any rate that was pulled beforehand. Rates, business segments etc. are dynamic and hotel employees could create a new one and assign it to a reservation right before the reservation gets pulled to RMS.

Periodic Future Update

Performed periodically after the connection is set up so that RMS has future reservations and revenue up to date. Length of the period is not specified, but it is recommended to update the future data once or twice a day. If you need to get the reservation changeset more frequently, you should use the Get All Reservations with the Reservation Time Filter set to Updated. That gives you just reservations that were created or updated within the specified interval.

Information About the Rates

To know the data abou the hotel’s rates, there are two relevant API calls. Get All Rates can give you information about the names (and ids) of the rates in the property, their status, rate groups and restrictions. Get Rate Pricing gives you the pricing of specific rate for a specific time period.

Update Rate Price

To make the life easier for the revenue managers, it is suggested that Revenue management systems work “two-way” meaning that they don’t just pull the data from Mews for analysis into their platform but that they offer the option to push the suggested prices automatically to the PMS. For that should the Update Rate Price API call be used. Individual rate, room category and time span can be chosen.

Notes

When calculating occupancy, it is important to take hierarchy of spaces into account. For example if there is a reservation for whole dorm, it occupies the dorm but also all child spaces in the hierarchy (the beds). And vice versa, if there is a bed reservation, it occupies the bed but also all parent spaces (the dorm).

We consider a space occupied if there is a reservation colliding with interval 18:00 to 24:00 on that day. So e.g. reservation from 14:00 to 16:00 is not calculated towards occupancy.

Devices

In order to communicate with devices on the local hotel network, such as printers, lock systems, PBX, TVs, key cutters or fiscal machines, MEWS has introduced the concept of Devices and Device Commands. When a relevant action happens in MEWS, a device command is generated and put into the Device Command Queue. Using the Device Commands API, you can pull the commands from the queue, process them as you find necessary and later mark them as processed. Of course, as many of the actions with devices should happen in real time, you should in most of the cases use this in combination with Websockets to avoid polling for new commands. Whenever a relevant command is created, you would receive a notification about such an event through the opened websocket.

Establishing connection

First of all, you should subscribe your application for receiving Device Command Events by connecting to the Websockets endpoint. Since then, your application will receive all the newly created device commands in real time.

Once you are receiving all the newly created commands through the created websocket, you might need to obtain all of the commands that were already pending in the Device Command Queue while your application was offline. To do so, you should use the Get All Active Commands API call. You want to pull the pending commands every time your application reconnects using Websockets, no matter how long it was offline. Otherwise, there might be some unprocessed commands in your queue.

Processing commands

Once you are notified via a websocket about the fact that a device command was created, you need to pull the command into your applicaiton. To do so, use the Get All Active Commands API call. Once proccessed, you should mark those commands as processed using the Update Command API call.

Fiscal Machines

In case your device is a Fiscal Machine (no matter whether it is a virtual or a physical one), you would get a command containing Fiscal Machine Command Data. That involves all data of the related Bill including all the payments and revenue items in a form of Accounting Items. Currently, there is no way how to send any fiscal code generated by the fiscal machine back to the MEWS PMS.

Key Cutters

In case your device is a Key Cutter, you would get a command containing Key Cutter Command Data.

POS

Point of sales systems (POS) need to be able to create charges in MEWS. With MEWS, you cannot charge on a specific room as rooms do not pay bills, customers do. Therefore, a POS system needs to identify/search customers to whose bills revenue items can be posted.

Search customers

The easiest and most convenient way to search for customers to be charged is via the Search customers API call. This will allow you to search among all customers that are somehow involved in checked in reservations as well as all the customers with the Paymaster Customer classification selected. Customers can be either searched by Name (which applies for first name, last name and full name) or by SpaceId which then returns all active customers within the reservation.

Note that this call has the name of the customer as an optional parameter. You can also use the SpaceId parameter to obtain a list of guests occupying a particular space (e.g. staying in a particular hotel room).

Adding order

Once the customer to be charged is identified, the items can be posted onto their bill using the Add order API call.

Notes

To operate with a POS system accordingly, the Connector integration needs to be set up properly. The hotel needs to select a service under which all the items sent from the POS will be recorded in MEWS. By default, only positive charges are allowed. Rebates need to be explicitely enabled by the hotel. MEWS admin can make the aforementioned changes.

Back to Top