Create & Modify Reservations

Use this interface to create, modify, or cancel reservations in Minihotel. A reservation may contain one room stay or multiple room stays, such as a group reservation. Requests can include room and rate details, guest counts, contact details, address information, remarks, and more.

Reservation Creation - Request

Element	Attributes / Value	Description	Format / Example
Bookings		Root element containing the request.	`<Bookings>`
Authentication	`username`, `password`	Minihotel API credentials.	`<Authentication username="Test" password="3657488" />`
Hotel	`id`	Minihotel property ID.	`<Hotel id="sandbox" />`
Booking	`id`	Unique reservation ID from the requesting system. Do not reuse an ID to create a different reservation. Use the original ID when modifying or cancelling an existing reservation.	String, for example `123456789`
Booking	`type`	Action to perform.	`Book`, `Modify`, or `Cancel`
Booking	`createDateTime`	Reservation creation date. Despite the attribute name, this value contains a date only.	`dd/MM/yyyy`, for example `23/12/2019`
Booking	`source`	Identifies the OTA, agent, or other source that created the reservation. Maximum 15 characters.	String, for example `Expedia`
Booking	`rateCode`	Rate code selected for the reservation. The rate code is linked to a currency in Minihotel.	String, for example `Standard`
Booking	`Board`	Meal-plan or board code.	Property-defined code, for example `HB`
Booking	`Vat`	This is an optional parameter. If the Vat Attribute is not set, then Minihotel considers the country field when calculating VAT, according to the default system settings.	`Yes` Including Vat `Not` Not including Vat
Booking	`Arrtime`, `Deptime`	Expected arrival and departure times.	`HH:mm` in 24-hour time, for example `15:00` and `10:00`
RoomStays		Container for one or more `RoomStay` elements.	`<RoomStays>`
RoomStay	`roomTypeID`	Room-type code configured for the property.	String, for example `TRP`
RoomStay	`roomTypeName`	Room-type name.	String, for example `Triple Room`
RoomStay	`roomNumber`	Specific room to reserve. If omitted, Minihotel assigns an available room of the requested type.	String, for example `204`
RoomStay	`Board`	Board code for this room stay. Recommended when different rooms may use different board types.	Property-defined code, for example `HB`
StayDate	`arrival`, `departure`	Arrival and departure dates for the room stay.	`yyyy-MM-dd`, for example `2020-01-21` and `2020-01-23`
RoomCount	`NumberOfUnits`	Number of units represented by the room stay.	Positive integer, for example `1`
GuestCount	`adult`, `child`, `baby`	Number of guests in each age category.	Non-negative integers, for example `adult="2" child="1" baby="0"`
PerDayRates	`CurrencyCode`	Container for the room’s daily rates. Note: The currency defined inside MiniHotel's settings by the selected `rateCode` takes precedence over the currency specified in this field.	ISO 4217 currency code, for example `USD`
PerDayRate	`stayDate`, `baseRate`	Rate for a specific stay date.	Date: `yyyy-MM-dd`; amount: decimal using a period, for example `baseRate="450.00"`
Total	`AmountAfterTaxes`, `CurrencyCode`	Total amount after taxes and its currency. Note: The currency defined inside MiniHotel's settings by the selected `rateCode` takes precedence over the currency specified in this field.	Decimal using a period and ISO 4217 code, for example `900.00` and `USD`
GuestNames		Container for one or more guest names associated with a room stay.	`<GuestNames>`
Name	`givenName`, `surname`	Guest's first and last name.	String
PrimaryGuest		Container for the main guest's details.	`<PrimaryGuest>`
Address	`Street`, `Zip`, `City`	Primary guest's address. Treat `Zip` as text so leading zeros are preserved.	String
Country	`CountryName`, `iso2`, `iso3`, ``	Primary guest's country	ISO 3166-1 alpha-2 and alpha-3 codes, for example `US` and `USA`
Language	`iso2`	Primary guest's language.	ISO 639-1 two-letter code, for example `EN`
Phone	Text value	Contact numbers. Treat these values as text so a leading `+` or zero is preserved.	String, for example `+17189726000`
Email	Text value	Primary guest's email address.	Valid email address
CreditCard	`Type`, `Number`, `NameOnCard`, `Expirationdate`, `cvv`	Payment card details. Include these fields only when required for the integration and handle them in accordance with all applicable security requirements. Please obtain approval from our team before using this option. These fields may also be used to pass payment card token data, where applicable.	Expiration: `MMyy`, for example `1028`; CVV: 3 or 4 digits
SpecialRequest	Text value or attributes	Special request associated with the reservation.	String
Remarks	Text value	General reservation remarks.	String; XML special characters must be escaped
ResGlobalInfo		Overall information for a multi-room reservation.	`<ResGlobalInfo>` Note: This element is an Optional, not mandatory to use.
Timespan	`arrival`, `departure`	Overall arrival and departure dates for a multi-room reservation.	`yyyy-MM-dd`
Total	`AmountAfterTaxes`, `CurrencyCode`	Total amount after taxes and its currency, used for multi-room reservations. Note: The currency defined inside MiniHotel's settings by the selected `rateCode` takes precedence over the currency specified in this field.	Decimal using a period and ISO 4217 code, for example `900.00` and `USD`

Reservation Creation - Request Example:

<?xml version="1.0"?>
<Bookings>
<Authentication username="Test" password="3657488" />
<Hotel id="sandbox" />
<Booking id="123456789" type="Book" createDateTime="23/12/2019" source="Web" rateCode="Standard" Board="HB">
<RoomStays>
<RoomStay roomTypeID="TRP" roomTypeName="Triple Room" Board="HB"><StayDate arrival="2020-01-21" departure="2020-01-23"/>
<RoomCount NumberOfUnits="1" />
<GuestCount adult="2" child="1" baby="0" />
<Total AmountAfterTaxes="900" CurrencyCode="USD" />
<GuestNames givenName="Jon" surname="Doe" />
</RoomStay>
</RoomStays>
<PrimaryGuest>
<Name givenName="Jon" surname="Doe"></Name>
<Address Street="79 Street" Zip="565643" City="Seattle" />
<Country iso3="USA" iso2="US" />
<Phone>7189726000</Phone>
<Email>[email protected]</Email>
<CreditCard Number="4111111111111111" NameOnCard="Jon Doe" Expirationdate="1022" cvv="898" />
</PrimaryGuest>
<Remarks>Note1 Note2 Note3</Remarks>
</Booking>
</Bookings>

Create a Multi Room Reservation - Request Example:

<?xml version="1.0"?>
<Bookings>
<Authentication username="Test" password="3657488" />
<Hotel id="sandbox" />
<Booking id="40406060550" type="Book" createDateTime="2018-03-11" Source="Web" RateCode="Standard" Board="BB">
<RoomStay roomTypeID="DBL" roomTypeName=""><StayDate arrival="2018-04-11" departure="2018-04-12" />
<RoomCount NumberOfUnits="1" />
<GuestCount adult="2" child="0" baby="0" />
<PerDayRates CurrencyCode="USD"><PerDayRate stayDate="" baseRate="" />
</PerDayRates><Total AmountAfterTaxes="930" CurrencyCode="USD" />
<GuestNames><Name givenName="mickey" surname="mouse" /></GuestNames></RoomStay>
<RoomStay roomTypeID="TRP" roomTypeName=""><StayDate arrival="2018-04-11" departure="2018-04-13" />
<RoomCount NumberOfUnits="1" />
<GuestCount adult="1" child="2" baby="0" />
<PerDayRates CurrencyCode="USD"><PerDayRate stayDate="" baseRate="" />
</PerDayRates><Total AmountAfterTaxes="1370" CurrencyCode="USD" />
<GuestNames><Name givenName="mini" surname="mouse" />
</GuestNames></RoomStay><PrimaryGuest><Name givenName="mini" surname="mouse" />
<Address Street="bear st" Zip="12150" City="Larnaca" />
<Country CountryName="" iso2="US" iso3="USA" />
<Language iso2="HE" />
<Email>[email protected]</Email><Phone>046999999</Phone><Fax />
<CreditCard Type="MasterCard" Number="80808080808080" NameOnCard="Jon" Expirationdate="0418" cvv="802" />
</PrimaryGuest><SpecialRequest />
<Remarks>Payment Method: Credit Card (MasterCard)\n Rate Code: USD</Remarks>
<ResGlobalInfo>
<Timespan arrival="2018-04-11" departure="2018-04-13" />
<Total AmountAfterTaxes="" CurrencyCode="USD" />
</ResGlobalInfo>
</Booking>
</Bookings>

Create Multiple Reservations in One Request:

<?xml version="1.0"?>
<Bookings>
    <Authentication username="Test" password="3657488" />
    <Hotel id="sandbox" />

    <Booking id="testing2000010"
             type="create"
             createDateTime="28/08/2026"
             source="Test56789012345"
             rateCode="USD"
             board=""
             Vat="Not">
        <RoomStays>
            <RoomStay roomTypeID="DBL" roomTypeName="Double" board="CC">
                <StayDate arrival="2026-11-15" departure="2026-11-18" />
                <RoomCount NumberOfUnits="1" />
                <GuestCount adult="2" child="0" baby="0" />
                <Total AmountAfterTaxes="600" CurrencyCode="USD" />
                <GuestNames givenName="John" surname="Connor" />
            </RoomStay>
        </RoomStays>
        <PrimaryGuest>
            <Name givenName="John" surname="Connor" />
            <Address Street="100 Main Street"
                     Zip="90001"
                     City="Los Angeles" />
            <Country iso3="USA" iso2="US" />
            <Phone>12135550101</Phone>
            <Email>[email protected]</Email>
        </PrimaryGuest>
        <Remarks>First valid booking in a multiple-booking request</Remarks>
    </Booking>

    <Booking id="testing2000011"
             type="create"
             createDateTime="28/08/2026"
             source="Test56789012345"
             rateCode="USD"
             board=""
             Vat="Not">
        <RoomStays>
            <RoomStay roomTypeID="DBL" roomTypeName="Double" board="CC">
                <StayDate arrival="2026-11-20" departure="2026-11-24" />
                <RoomCount NumberOfUnits="1" />
                <GuestCount adult="1" child="0" baby="0" />
                <Total AmountAfterTaxes="800" CurrencyCode="USD" />
                <GuestNames givenName="Sarah" surname="Connor" />
            </RoomStay>
        </RoomStays>
        <PrimaryGuest>
            <Name givenName="Sarah" surname="Connor" />
            <Address Street="200 Sunset Boulevard"
                     Zip="90028"
                     City="Los Angeles" />
            <Country iso3="USA" iso2="US" />
            <Phone>12135550102</Phone>
            <Email>[email protected]</Email>
        </PrimaryGuest>
        <Remarks>Second valid booking in a multiple-booking request</Remarks>
    </Booking>
</Bookings>

Reservation Creation - Response

Response element / type	Attribute	Description	Format / Example
BookingConfirmRQ		Root element returned after successful reservation creation.	`<BookingConfirmRQ>`
BookingConfirmNumbers		Container for one or more reservation confirmation results.	`<BookingConfirmNumbers>`
BookingConfirmNumber	`bookingID`	Booking ID received in the corresponding `<Booking>` request.	String, for example `123456789`
BookingConfirmNumber	`resnumber`	Minihotel reservation number assigned to the booking. Preserve it as a string because it may contain leading zeros.	9-character string, for example `007012539`
Error response		Returned when a reservation cannot be created. Contains an error code and a description of the failure.	For example, `ERR 517: Booking ID 123456789 already exists in reservation 007012539`

Successful Response

When a reservation is successfully created, the response includes its Booking ID and the Minihotel reservation number:

<BookingConfirmRQ>
    <BookingConfirmNumbers>
        <BookingConfirmNumber
            bookingID="123456789"
            resnumber="007012539" />
    </BookingConfirmNumbers>
</BookingConfirmRQ>

When several reservations are successfully created in the same request, each reservation receives its own <BookingConfirmNumber>:

<BookingConfirmRQ>
    <BookingConfirmNumbers>
        <BookingConfirmNumber
            bookingID="123456789"
            resnumber="007012539" />
        <BookingConfirmNumber
            bookingID="123456790"
            resnumber="007012540" />
    </BookingConfirmNumbers>
</BookingConfirmRQ>

Failed Reservation Responses

If a reservation cannot be created, the response returns an error code and description indicating the reason for the failure.

Common examples:

ERR 001: Invalid XML

ERR 516: Invalid XML: no reservation was created

ERR 517: Booking ID testing2000004 already exists in reservation 007004482

ERR 599: General settings error. Please contact us so we can investigate the issue

For the complete list of possible errors, see the Error Codes page.

Notes:

Booking id

Your booking is assigned a unique identification, ensuring that each ID is used only once. While it's optional, we recommend using an ID from your end. If you choose this option, it's essential to maintain a counter or similar tool to manage these IDs locally.

Opting for an ID from your end offers the advantage of easy reservation tracing within your system (database) in case of malfunctions or mismatches.

For OTAs/Tour Operators storing reservations locally, we strongly advise using your system's reservation numbers. This practice ensures seamless data correlation between your system and Minihotel.

<Booking id="123456789" type="Book" createDateTime="23/12/2019" source="Airbnb" rateCode="Standard" Board="HB">

To submit a booking without a unique booking ID, please use the value 'KioskPos' in the following way: Booking id="KioskPos".Since this is a less common practice, we kindly request that you coordinate with us before opting for the KioskPos option.

RateCode

This is the selected Rate Code. The rate code also determines the reservation's currency (Inside the Minihotel system, each rate is linked to a specific currency). The RateCode attribute must be put inside the <Booking> element.

<Booking id="123456789" type="Book" createDateTime="23/12/2019" source="Expedia" RateCode="Standard" Board="HB">

Roomstay

This element is applicable to both single and multi-room reservations. In the case of multi-room bookings, it will be used multiple times. If you solely utilize the roomTypeID attribute, the system will automatically assign a room number based on the availability of rooms of that type. However, if you specify the roomNumber attribute, the system will reserve the specific room you've designated, blocking it from other bookings.

<RoomStay roomTypeID="TRP" roomTypeName="" roomNumber="204"><StayDate arrival="2020-07-11" departure="2020-07-13" /> <RoomCount NumberOfUnits="1" />

Board

When this parameter is left unspecified, the board value is determined by Minihotel's preset, configured in the settings menu.

<Booking id="123456789" type="Book" createDateTime="23/12/2023" source="Expedia" RateCode="Standard" Board="HB">

When this parameter is set at both the reservation header and room stay levels, resulting in a conflict, the value is dictated by the header level, which holds precedence.

Therefore, it's recommended to leave the board field empty or omit it entirely from the reservation header. Instead, it's best to manage board settings exclusively at the room stay level, particularly when dealing with multi-room reservations or groups.

<RoomStay roomTypeID="TRP" roomTypeName="Triple Room" Board="HB">

Arrtime and Deptime

Arrival and Departure time are set by: Arrtime and Deptime.

These parameters can be used for a regular (overnight) reservations as well as for day use reservations (ie. a zero nights' stay).

Day use reservations must include the following fields:

Arrival date and departure date (both need to be the same)
A room number (mandatory)
Arrival and departure time (both mandatory)

Modification - Request

Modifications can be made to most of the reservation's fields, for example: Name, Dates, Price, Credit Card number, Email and more.

Instructions: Change the booking type attribute to Modify instead of Book.
The XML Structure should remain the same as it is for the reservation creation, apart from the type attribute change.

<Bookings>
<Authentication username="Test" password="3657488" />
<Hotel id="sandbox" />
<Booking id="324234342" type="Modify" createDateTime="23/02/2024" source="Expedia">

Modification - Response

The response for modification is similar to that of reservation creation's. ie. When the modification is successfully authorized, a resnumber is provided, otherwise it's empty / not provided.

<BookingConfirmRQ>
    <BookingConfirmNumbers>
        <BookingConfirmNumber bookingID="324234342" resnumber="007001793" />
    </BookingConfirmNumbers>
</BookingConfirmRQ>

Cancellation - Request

Instructions: Change the booking type attribute to Cancel instead of Book.
The XML Structure should remain the same as it is for the reservation creation, apart from the type attribute change.

<Bookings>
<Authentication username="Test" password="3657488" />
<Hotel id="sandbox" />
<Booking id="324234342" type="Cancel" createDateTime="23/02/2024" source="Expedia">

Cancellation - Response

The response for Cancellation is similar to that of reservation creation's. ie. When the cancellation is successfully authorized, a resnumber is provided, otherwise it's empty / not provided.

<BookingConfirmRQ>
    <BookingConfirmNumbers>
        <BookingConfirmNumber bookingID="324234342" resnumber="007001793" />
    </BookingConfirmNumbers>
</BookingConfirmRQ>