Fetching reservations

Read this chapter if you want to manage WooDoo’s reservations via API.

Basic concepts

There are several ways to download reservations from WooDoo. Before describing some strategies, let’s considere the following concepts:

  • Marking: Wired is able to remember what you already fetched: you don’t need to specify filters (for example dates), because in that case only not-read reservations will be returned. Marking can be done automatically or on demand.

  • Push notification: instead of periodically asking our servers for new reservations, consider the idea to establish a notification layer. Wired is able to notify you when a new reservation is ready to be fetched, so you can get it individually using the fetch_booking() call. This will optmize a lot your/our servers load.


Even if you choose to deploy the Push Notification, it’s important to schedule a fetching call with a 2 hours frequence, just in case some notification will be lost. If you are a corporate user, also check the corporate_fetchable_properties() call.


Enabling the Push Notification and Marking is not necessary, but seriously recommended, because it is the best (faster, elegant and reliable) approach.

Setting up the Push Notification

WooDoo is able to notify your system that new reservations are waiting for you. This will be done with a simple POST. The URL used for the POST can be configured for each property with the following call:

push_activation(token, lcode, url[, test= 0])

To disable the push notification you can use, as url, an empty string.

If you use test= 1 while specifying a valid url, a POST is immediately issued (lcode= 1000, rcode= 2000). This way, you will be able to debug the push activation. Notice that if such test will fail, the call will return an error.

Once a new reservation is collected for the property identified with the lcode argument, WooDoo will issue a POST to the relative URL containing two parameters: rcode (the reservation code) and lcode (the property identifier, allowing to use the same URL for multiple properties).

To fetch the notified reservation, use the fetch_booking() call, passing the property code and the reservation code.


When a reservation is deleted or modified, WooDoo will issue a POST containing the same payload as for new reservations.


While receiving and handling a push notification, make sure to return a 200 status code and to provide a fast answer (few seconds). Otherwise you can have a couple of problems. First of all, the push notification system will retry. Moreover, if the notification system will detect too many errors on your server, it can even suspend notifications. To provide a fast response, adopt the following approach: immediately reply 200 and perform your operations after that.

Finally, to check the current Push Notification Url for one property, use:

push_url(token, lcode)

Fetching a single reservation

To fetch a unique reservation identified by rcode, use the following function:

fetch_booking(token, lcode, rcode[, ancillary= False])


The use of fetch_booking() is required when the push notification is active.

Fetching fresh reservations

To fetch new reservations for a property, use the following function:

fetch_new_bookings(token, lcode[, ancillary= 0, mark= 1])

Once called, this function will return only new reservations (not fetched yet). It’s always a good idea to use ancillary= 1, because by enabling this option you will receive more information (see the representation section).

If mark= 1, fetched reservations will be considered marked and will not be returned at the next call.

If you want more control (a sort of transaction), you can specify mark= 0. Then, if the reservations are correctly integrated on your system, you will mark them as fetched with the following call:


WooDoo will return, at maximum, 120 reservations for each call.


don’t use fetch_new_bookings when a push notification comes. Use the fetch_booking() to fetch the single reservation notified instead.

mark_bookings(token, lcode, reservations)

where the reservations argument is an array of reservation codes, i.e. [123, 234, …, 890]. Once marked, the next fetch_new_bookings() call will not return them again. This way, if a bug will prevent a correct integration, mark_bookings() will not be called and WooDoo will continue to return the reservations until the bug is fixed: at that point, the mark_bookings() call will be launched from your side.

The following double remark underlines at the same time a Feature and a Danger :).


if you use an empty array, all the collected reservations will be marked as fetched (check the First time fetch section).


if you use an empty array, all the collected reservations will be marked as fetched (check the First time fetch section).

Fetching for the first time

If you connect a property that has already collected many reservations, you have two possibilities:

  • Ignoring existing reservations

  • Fetching them all

Please, check the following sub-section to better understand the related logic.

Ignoring existing reservations

Ignoring existing reservations, starting to fetch only the new ones, is a good idea, in particular if the property has collected thousands of reservations.

To ignore the existing reservations, just issue the following call:

mark_bookings(token, lcode, emptyarray) :noindex:

By passing an empty array to the mark_bookings() function, all the collected reservations will be marked as fetched. At this point, you can safely launch fetch_new_bookings() by relying on the fact that only new reservations will be retrieved (as described on the previous chapters).

Fetching all existing reservations

To fetch all reservations, you have to cycle a call to:

fetch_new_bookings(token, lcode[, ancillary= 0, mark= 1]) :noindex:


That’s because WooDoo will return, at maximum, 120 reservations for each call.

Make sure to mark them once retrieved with the mark_bookings() call (if you use mark= 0 during the call).

Reservation representations

Now that you know how to fetch reservations, it’s time to understand how to manage the return values of the fetching functions. The representation of a reservation is a KV structure, having the following keys:




The reservation ID (and at the same time creation timestamp= reservation date)


Reservation Status (see below: status)


If originated by an OTA, it contains the OTA ID of this reservation (0 otherwise)


If originated by an OTA, that’s the channel type (booking, expedia, …, check get_channels_info())


If originated by an OTA, that’s the ID of the connected WooDoo Channel


If originated by a Fount Site, it contains the Fount site ID (trivago, tripadv and so on, see fountfield)


If the reservation is modified, this field is not null (see below: modified_reservations)


If was_modified= 1, then status= 5 and you have a modification (see below: modified_reservations)


The reservation amount


The currency code. Three digits (EUR, USD, ..)


Deprecated (see booked_rooms): booked pricing plan: -1= Unknown, 0= Wb Parity or id of the plan


Original Reservation Amount (amount can be modified from the extranet)


If Amount is modified, this field contains the related comment


Deprecated (see date_received_time)


Reservation Date







Information about boards: WooDoo Online Reception only (see below: boards)


Information about total amount of all boards (see below: tboard)


Eventually, this field contains a reason for the current reservation status


Number of adults (when not defined, equal to -1)


Number of children


The eventual sessionSeed tag assigned during the opening of the WooDoo Online Reception


The origin parameter that can be sent in the new_reservation function











A string following the ISO 639-1 Standard for languages (https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)



A string contatining booked rooms IDs, comma separated


Roomnights (almost useless)


Info about addons (for OTA reservations and WooDoo Online Reception add-ons)


Number of room addons in the addons_list (WooDoo Online Reception only)


Number of generic addons in the addons_list (WooDoo Online Reception only)


Per day, per room prices


Info about an eventual special offer: name and discount (WooDoo Online Reception only)


Info about the occupancy of each booked room (it can be empty, see below : rooms_occupancies)


Information about an eventual discount (see below: discount)


An optional array of Mandatory Costs (only for direct reservations)


The amount paid by the customer online (as deposit, WooDoo Online Reception only)


If true (1), dayprices should be ignored (used for youbook and aliens reservations for example)


Optional and detailed info about each room/rate with a day granularity (see below: booked_rooms)


If you fetch with ancillary= 1 (see below: ancillary)


Device used to books (see below: device)


Deprecated (see deleted_at_time)


Info about eventual reservation deletion (see below: deleted)




Standarized info for all channels, like split reservations (see below: channel_data)


City tax value calculated following the rule set on WooDoo, not included in the amount (WooDoo Online Reception only)

The status of a reservation is an integer and can assume the following values:

  • 1: confirmed

  • 2: waiting for approval (WooDoo Online Reception only)

  • 3: refused (WooDoo Online Reception only)

  • 4: accepted (WooDoo Online Reception only)

  • 5: cancelled

  • 6: (probably not used anymore): cancelled with penalty

The ancillary field contains information collected by the channel manager which are out of standard (for example, textual remarks and so on). It is a KV structure. Of course, its keys are strings, while its values are arbitrary. They can be everythign (for example strings, arrays or even structs). Different channels (booking.com, expedia and so on) provide very different information and this is the best way to organize them.

If originated by a Fount Site, the fount field contains the Fount site ID (trivago, tripadv and so on). A list of valid fount IDs can be obtained by the get_fount_symbols() call.

The device field is an integer, it’s detected only for reservations made from our Online Reception, the meaning is described below here:

  • -1: Not Detectable

  • 0: Unknown device

  • 1: Mobile phone

  • 2: Tablet computer

  • 3: Personal computer

  • 4: iPhone

  • 5: iPad

  • 6: Android device

  • 7: BlackBerry

  • 8: iPod

The boards field contains information about selected boards. The WooDoo Online Reception, in fact, allows user to select their preference about them. It is a KV structure containing Room IDS as keys and Board String (‘bb’, ‘fb’, ..) as values.

The tboard field contains the total amount of all boards for the whole reservation period.

The booked_rooms field contains an array containing one struct for every booked room. For each room struct another list is provided, containing one struct representing each booked day. The room-level struct contains the room ID. The day-level struct contains:

  • day: european date

  • price

  • rate_id ( <0: Unknown; 0: WuBook Parity (aka standard rate); >0: the id of the booked pricing plan).

Both room and day level structs contain an “ancillary” field. It contanis non-standard information (collected from OTAs).

For OTA reservations, it is possible we wont receive details about daily prices. In such cases, this field is automatically generated: the room-level “ancillary” field contains the information auto_generated: True; this automatic generation consists in splitting and adapting values from the reservation fields: dayprices and booked_rate.

The discount value is a KV structure having the following keys:

  • type: the discount type (Percentage= 1, Daily Amount= 2, Fixed Amount= 3, No discount= 4, Pricing Plan= 5, Hidden fixed amount= 6, Fixed amount that will appear as a percentage discount = 7, Package= 8)

  • pricing_plan: a pricing plan id (if the discount is configured with a plan)

  • value: the discount value

  • code: the used discount code

  • name: the discount name

  • id: the discount id

The special_offer value is a KV structure having the following keys:

  • id: the special offer id

  • name: the special offer name

  • type: the special offer type (Percentage= 1, Fixed= 2, Related to a Pricing Plan= -1)

  • value: the special offer value (if ‘type’ is 1 or 2: discount value, otherwise: -1)

  • pricing_plan: the linked pricing plan ID (if ‘type’ is -1: ID of the Pricing Plan, otherwise: -1)

  • discount: the amount discounted

See OFFERS for more info.

The addons_list value is an Array, having a KV structure as each element.

For WooDoo Channel reservations, each KV structure contains these fields:

  • name: the addon name

  • req: the required quantity

  • price: the addon price (per unit)

For WooDoo Online Reception reservations, each KV structure contains these fields:

  • id: the opportunity id

  • name: the opportunity name

  • number: the required quantity

  • perday: 1 for daily price, 0 for global price

  • id_room: the room id

  • price: the opportunity price (total)

See OPPORTUNITIES for more info.

The rooms_occupancies value is an Array, having a KV structure as each element. Each KV structure contains two fields: id (the Room ID) and occupancy (an integer).

If the reservation was deleted: deleted_at_time is the date when it happened, and deleted_advance is the number of days respect to arrival date. deleted_from means where the deletion was made, and can be:

  • 1: cancelled by the customer

  • 2: cancelled from the BackOffice

  • 3: cancelled from the Distribution Channel

  • 4: cancelled by the WuBook staff

  • 5: cancelled using the Alien service

  • 6: cancelled using the Wired service

  • 7: cancelled from the payment gateway (WooDoo Online Reception only)

  • 8: cancelled after a modification

The channel_data field is a KV structure with information that can be treated in a standard way for all the channels. By the moment, it includes the following keys:

  • split_reservation, which has as value another KV structure with two keys: n_stream and tot_stream. So, in case of a reservation is part of a split, you’ll know wich part of this split is the current reservation (n_stream) and how many parts is the original reservation split on (tot_stream).

  • paymodel, which has two possible string values:




    The guest pays the OTA who pays the hotel in turn


    The hotel pays the OTA after receiving full payment from the guest

  • vat_included, which has a boolean value that define if the VAT is included or not in the amount.

  • addons_embedded, which has a boolean value that define if the addons are included or not in the amount.

  • vcc_additional_info, which contains information about virtual cards. It has as value a KV structure with these keys:




    The card validity start date


    The card validity end date


    The avaiable amount


    The currency code. Three digits (EUR, USD, ..)

Reservation modifications

Notice that a modified status does not exist. Why? A modification is always managed with a cancellation and a new reservation. In other words, when a reservation is modified (this happens only for reservations originated by OTAs), the old reservation is cancelled. A new reservation is then inserted on the system, reflecting the modifications. In this case, the modified_reservations and was_modified fields contain a complete information about the modification.

The modified_reservations and was_modified fields must be perfectly understood. They appear when a reservation is modified. How? Let’s make an example:

Moment 1: a new reservation is received, its reservation code is 123.

    If you fetch reservations now, you will get a reservation with the following values
    (notice that modified_reservations is null and was_modified= 0):

    Reservation 1:
      rcode=  123
      status= 1
      was_modified= 0

Moment 2: the reservation is modified

    If you fetch reservations now, as described before, you will get 2 reservations with the following values:

    Reservation 1 (the cancellation of the old reservation):
      rcode=  123
      status= 5
      modified_reservations= 123
      was_modified= 1

    Reservation 2: (the new reservation)
      rcode=  234
      status= 1
      modified_reservations= 123
      was_modified= 0

So, the first concept is: when a reservation is modified, its status becomes 5 (cancelled). The modified_reservations field becomes equal to rcode and was_modified becomes 1. Surely, the next resevation is the replacement of this one. This new reservation has the modified_reservations field equal to the rcode of the previous reservation (this way, you can understand that it replaces it) and status = 1.

Now, let’s add another element of complexity. What happens if the reservation is modified again? Always considering the previous example, let’s check this possibility:

Moment 3: the reservation is modified again

    If you fetch reservations now, you will get 2 reservations with the following values:

    Reservation 1 (the cancellation of the old reservation):
      rcode=  234
      status= 5
      modified_reservations= 123
      was_modified= 1

    Reservation 2: (the new reservation)
      rcode=  345
      status= 1
      modified_reservations= 234
      was_modified= 0

As you can see, the logic is the same. Just notice that the modified_reservations field of the Reservation 1, differently by the previous case (where it was equal to rcode), continue to report 123: this way, you will know that this reservation was originally the replacement of 123.

Other functions

Altough the previous chapters can be considered a complete reference to fetch reservations form wubook, we list on this last section the full list of available functions you can use to improve things or to better manage particular cases.

fetch_bookings(token, lcode[, dfrom= None, dto= None, oncreated= 1, ancillary= 0])

This function is used to fetch reservations eventually using a range of dates as filter. Notice that retrieved reservations returned when you specify a date are not marked as fetched. The dfrom and dto arguments are european dates (as string: “21/12/2021”). When oncreated is 1, the filter is applied against the reservation date. When oncreated is 0, the filter is applied against the arrival date.

If not filter (dfrom and dto) is specified, this call will be equal to a fetch_new_bookings() call, with mark parameter = 1.


WooDoo will return, at maximum, 120 reservations for each call.

fetch_deleted_bookings(token, lcode, dfrom[, dto= None, ancillary= 0])
Same logic as fetch_bookings() but for deleted reservations.
This function will never mark reservations as fetched, since dfrom is always required.
fetch_bookings_codes(token, lcode, dfrom, dto[, oncreated= 1])

Similar to fetch_bookings(), but instead of returning the list of reservations, this functions returns just an array of reservation codes.


To retrieve a list of valid fount IDs and relative names.

XML Examples

Here, you’ll find some examples of reservations creation, modification and deletion in XML format.

1- Creation: below, there is an example of a brand-new creation.

+ show/hide code
2 - Modification - Case 1: in this case, we are modifying the dates of both of the rooms present in the previous example.


the modified dates are the same for every room.

+ show/hide code
3- Modification - Case 2: in this case, we are modifying the dates for only one room among the rooms present in the Example 1.


this implies a splitting of the XML call, which is a better choice because it gets rid of reduntant useless data sending.

+ show/hide code
4 - Modification - Case 3: in this case, we are deleting the reservation of one of the rooms.


in this case, there’s no need to split the call; the XML sent is just one.

+ show/hide code

5 - Deletion - Case 1: in this case, we are deleting the modification made before in Example n. 3.

+ show/hide code

6 - Deletion - Case 2: in this case, we are deleting the modification made before in Example n. 4.

+ show/hide code