API Reference

OTA_HotelAvailNotifRQ

Request URL: http://supplyota.agoda.com/b2b/ota/2013A/hotels

OTA_HotelAvailNotifRQ

You can update availability restrictions for a single hotel per one request message. However, you can update multiple restrictions within one message. We recommend to update one hotel and one room per request.

Basic Structure

The basic structure of the message is as per below:

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelAvailNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2005-08-01T09:30:47+08:00" EchoToken="abc123" Target="Production" PrimaryLangID="en">
   <AvailStatusMessages HotelCode="HOTEL">
      <AvailStatusMessage LocatorID="1">
         <StatusApplicationControl Start="2010-01-01" End="2010-01-01" InvTypeCode="A1K" RatePlanCode="GLD" />
         <!-- Content omitted -->
      </AvailStatusMessage>
      <AvailStatusMessage LocatorID="2">
         <StatusApplicationControl Start="2010-01-02" End="2010-01-02" InvTypeCode="A1K" RatePlanCode="GLD" />
         <!-- Content omitted -->
      </AvailStatusMessage>
      <AvailStatusMessage LocatorID="3">
         <StatusApplicationControl Start="2010-01-03" End="2010-01-03" InvTypeCode="A1K" RatePlanCode="GLD" />
         <!-- Content omitted -->
      </AvailStatusMessage>
   </AvailStatusMessages>
</OTA_HotelAvailNotifRQ>

The OTA_HotelAvailNotifRQ message contains:

  1. One AvailStatusMessages element which define the hotel to update (@HotelCode attribute).
  2. Multiple AvailStatusMessages/AvailStatusMessage elements which define the transaction id (@LocatorID) used to communicate back to the sender.
  3. Each AvailStatusMessage element will contain a single StatusApplicationControl element. This element is used to specify the room type, rate plan code and date range for which the update applies. The dates affected by the update are controlled by the mandatory @Start and @End attributes.

How to set restrictions

The restriction details will be identified in either StatusApplicationControl/RestrictionStatus or StatusApplicationControl/LengthsOfStays element. One of these element must appear once in each StatusApplicationControl element.

Close/Open Restrictions Setting

Close for sale, closed to arrival and closed to departure update can be set by using the StatusApplicationControl/RestrictionStatus element. Please see the example of the settings below.

Restriction Type
How it will be sent
Room is closed for sale
<RestrictionStatus Status="Close" />
Room is open for sale
<RestrictionStatus Status="Open" />
Room is set as closed to arrival
<RestrictionStatus Status="Close" Restriction="Arrival" />
Room is set as open to arrival
<RestrictionStatus Status="Open" Restriction="Arrival" />
Room is set as closed to departure
<RestrictionStatus Status="Close" Restriction="Departure" />
Room is set as open to departure
<RestrictionStatus Status="Open" Restriction="Departure" />

Length of Stay Setting

Minimum and maximum length of stay updates can be set by using the StatusApplicationControl/LengthsOfStay element. This element contains a single LengthOfStay element with the attributes @MinMaxMessageType and @Time. @Time is the length of stay in days. Please see the example of the setting below.

Restriction Type
How it will be sent
Room has minimum length of stay 2 nights
<LengthsOfStay>
   <LengthOfStay MinMaxMessageType="SetMinLOS" Time="2"/>
</LengthsOfStay>
Room does not have minimum length of stay
<LengthsOfStay>
   <LengthOfStay MinMaxMessageType="RemoveMinLOS"/>
</LengthsOfStay>
Room has maximum length of stay 5 nights
<LengthsOfStay>
   <LengthOfStay MinMaxMessageType="SetMaxLOS" Time="5"/>
</LengthsOfStay>
Room does not have maximum length of stay
<LengthsOfStay>
   <LengthOfStay MinMaxMessageType="RemoveMaxLOS"/>
</LengthsOfStay>

OTA_HotelAvailNotifRQ Specification

Element

Number

Type

Description

OTA_HotelAvailNotifRQ

1


Root node

@TimeStamp

1

DateTime

Time of the transaction

@Version

1

Decimal

Current version is 1.0

@EchoToken1StringGlobally unique identifier for the request. We suggest to use epoch time that the request was sent to Agoda. This should be reflected as an EchoToken in the response.
@Target1StringTarget which can be either Production or Sandbox
@PrimaryLangID1StringLanguage ID, now only support English (en)

OTA_HotelAvailNotifRQ / AvailStatusMessages

1


Contains the availability messages

@HotelCode

1

String

The code for the property whose availability is being updated

AvailStatusMessages / AvailStatusMessage

1..n


Contains the availability messages. There can be multiple of these nodes per request

@LocatorID1LongIdentifies the transaction id, normally use to communicate back to the sender

AvailStatusMessage / StatusApplicationControl

1


Contains date and room identification information

@Start

1

Date

The start date for which the availability update is being set. This date is inclusive.

@End

1

Date

The end date for which the availability update is being set. This date is inclusive.

@RatePlanCode

1

String

Identifies the rate plan. The RatePlanCode is used in conjunction with the InvTypeCode to identify the room and rate plan to update.

@InvTypeCode

1

String

Identifies the room. The InvTypeCode is used in conjunction with the RatePlanCode to identify the room and rate plan to update.

StatusApplicationControl /
LengthsOfStay / LengthOfStay

0..1


Optional, used for minimum and maximum length of stay

@MinMaxMessageType

1

String

Mandatory if LengthsOfStay present. Can be one of the following

SetMinLOS: Sets the minimum length of stay

SetMaxLOS: Sets the maximum length of stay

RemoveMinLOS: Removes the minimum length of stay

RemoveMaxLOS: Removes the maximum length of stay

@Time

1

Integer

Mandatory if LengthsOfStay is present and MinMaxMessageType is of type "Set". Sets the minimum number of nights required for a stay or maximum number of nights qualified for a booking.

AvailStatusMessage / RestrictionStatus

0..1


Optional, used to close the room for sale, for arrival, or for departure.

@Status1String

Mandatory if RestrictionStatus is present.
Can be one of two values
Open: Should open a room for sale
Close: Should close or 'stop sell' a room for sale

@Restriction0..1String

Can be one of two values.
Arrival: The restriction is on arrival
Departure: The restriction is on departure

If there is no restriction type, the update should be assumed to be a full close or open for a room date.

Request examples

Example of the OTA_HotelAvailNotifRQ messages

Set MinLOS to Two Days

\<OTA_HotelAvailNotifRQ xmlns="<http://www.opentravel.org/OTA/2003/05"> Version="1.0" TimeStamp="2005-08-01T09:30:47+08:00" EchoToken="abc123" Target="Production" PrimaryLangID="en">  
  <AvailStatusMessages HotelCode="HOTEL">  
    <AvailStatusMessage LocatorID="1">  
      <StatusApplicationControl Start="2010-01-01" End="2010-01-01" InvTypeCode="A1K" RatePlanCode="GLD"/>  
      <LengthsOfStay>  
        <LengthOfStay MinMaxMessageType="SetMinLOS" Time="2"/>  
      </LengthsOfStay>  
    </AvailStatusMessage>  
  </AvailStatusMessages>  
\</OTA_HotelAvailNotifRQ>

Remove MinLOS Restriction

<OTA_HotelAvailNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2005-08-01T09:30:47+08:00" EchoToken="abc123" Target="Production" PrimaryLangID="en">
  <AvailStatusMessages HotelCode="HOTEL">
    <AvailStatusMessage LocatorID="1">
      <StatusApplicationControl Start="2010-01-01" End="2010-01-01" InvTypeCode="A1K" RatePlanCode="GLD"/>
      <LengthsOfStay>
        <LengthOfStay MinMaxMessageType="RemoveMinLOS"/>
      </LengthsOfStay>
    </AvailStatusMessage>
  </AvailStatusMessages>
</OTA_HotelAvailNotifRQ>

Set MaxLOS to Five Days

<OTA_HotelAvailNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2005-08-01T09:30:47+08:00" EchoToken="abc123" Target="Production" PrimaryLangID="en">
  <AvailStatusMessages HotelCode="HOTEL">
    <AvailStatusMessage LocatorID="1">
      <StatusApplicationControl Start="2010-01-01" End="2010-01-01" InvTypeCode="A1K" RatePlanCode="GLD"/>
      <LengthsOfStay>
        <LengthOfStay MinMaxMessageType="SetMaxLOS" Time="5"/>
      </LengthsOfStay>
    </AvailStatusMessage>
  </AvailStatusMessages>
</OTA_HotelAvailNotifRQ>

Remove MaxLOS Restriction

<OTA_HotelAvailNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2005-08-01T09:30:47+08:00" EchoToken="abc123" Target="Production" PrimaryLangID="en">
  <AvailStatusMessages HotelCode="HOTEL">
    <AvailStatusMessage LocatorID="1">
      <StatusApplicationControl Start="2010-01-01" End="2010-01-01" InvTypeCode="A1K" RatePlanCode="GLD"/>
      <LengthsOfStay>
        <LengthOfStay MinMaxMessageType="RemoveMaxLOS"/>
      </LengthsOfStay>
    </AvailStatusMessage>
  </AvailStatusMessages>
</OTA_HotelAvailNotifRQ>

Update All Values

Below is a sample request for a message that updates availability, closed to sale, MinLOS, closed to arrival and closed to departure.

<OTA_HotelAvailNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2005-08-01T09:30:47+08:00" EchoToken="abc123" Target="Production" PrimaryLangID="en">
  <AvailStatusMessages HotelCode="HOTEL">
    <AvailStatusMessage LocatorID="2">
      <StatusApplicationControl Start="2012-01-01" End="2012-01-01" InvTypeCode="A1K" RatePlanCode="GLD"/>
      <LengthsOfStay>
        <LengthOfStay MinMaxMessageType="SetMinLOS" Time="2"/>
      </LengthsOfStay>
    </AvailStatusMessage>
    <AvailStatusMessage LocatorID="3">
      <StatusApplicationControl Start="2012-01-01" End="2012-01-01" InvTypeCode="A1K" RatePlanCode="GLD"/>
      <RestrictionStatus Status="Close" Restriction="Arrival"/>
    </AvailStatusMessage>
    <AvailStatusMessage LocatorID="4">
      <StatusApplicationControl Start="2012-01-01" End="2012-01-01" InvTypeCode="A1K" RatePlanCode="GLD"/>
      <RestrictionStatus Status="Close" Restriction="Depature"/>
    </AvailStatusMessage>
  </AvailStatusMessages>
</OTA_HotelAvailNotifRQ>