Rates and Availability

Availability

Rates and Availability API can be used to push the following information from the IT provider to STAAH:

• Room Inventory count:

  • per IT provider's room id

  • per date

• Room Rate amount:

  • per IT provider's Room and Rate combination

  • per date

• Restrictions:

  • per IT provider's Room and Rate combination

  • per date)

At the time of fresh integration, STAAH requests that IT providers send rates/inventory/restrictions at least one full year from the current date (For example - on January 1, 2015, complete data should be loaded from January 1, 2015, until December 31, 2015, for all rooms, rates, and their applicable restrictions).

Maximum length of request should be less than or equal to 4 MB.

The maximum number of JSON requests permitted per property per hour is 10,000. When the limit is reached, JSON requests will not be processed, and the system will return error 'Limit has been reached'. Reset for JSON request allocation is renewed every hour, every day.

Endpoint

POST

https://connect-sandbox.su-api.com/SUAPI/jservice/availability

---

Attributes

---

hotelid / ClientID alphanumeric (Required)

The unique property ID as assigned by the provider upon creation of the property. Required existing hotel id to create rates for the room types.

Accepts alphanumeric values.

Space and Special characters are not allowed except Hyphen (" - ").

Maximum 20 characters allowed.

---

room object

This is an object represents the detail of the room.

---

roomid alphanumeric (Required)

The room ID / Listing ID as assigned by the provider.

Needs to be an active room in the STAAH system and if room is not available in STAAH then we will create on request.

roomid, RoomID, ListingID & InvCode defines the same field.

Amount of elements possible within parent: Min: 1 Max: unbounded

Accepts alphanumeric values and hyphen ( - ).

Space and other special characters are not allowed. Maximum 20 characters allowed.

---

date datetime (Required)

The date(s) that you are updating. STAAH prefers IT Providers to issue one large request by updating the inventory with combined dates as much as possible. Which can be accomplished by using attributes {date "from":"..." "to":"..."}

Needs to be an active room in the STAAH system and if room is not available in STAAH then we will create on request.

Min:1 Max:unbounded

---

value datetime (Optional)

Specifying a value in requests will update the date that is specified per value.

Only current date to max up to 500 days in the future.

Format: YYYY-MM-DD

---

from datetime (Required)

Specifying a range in requests will update the date from and including the date specified.

Only current date to max up to 730 days in the future.

Format: YYYY-MM-DD

---

to datetime (Required)

Specifying a range in requests will update the date until and not including the date specified.

Only current date to max up to 730 days in the future.

Format: YYYY-MM-DD

---

rate string (Optional)

IT provider's rate category ID which you are updating.

Rates to be updated need to be active in the STAAH system.

Note that rate elements become optional when updating only availability for a hotel.

---

rateplanid alphanumeric (Optional)

IT provider's unique rateplan ID.

Needs to be an active rate in the STAAH system.

---

roomstosell integer (Optional)

Set the amount of rooms that can be sold by OTAs to this number.

Rate should not be specified when updating roomstosell.

It cannot be a negative number.

Please note rate elements become optional when updating availability for a hotel.

---

price double (Optional)

The price for the given room for the given date for the given rate category.

Price cannot be removed after a value has been set, cannot be a negative number.

---

NumberofGuests integer (Optional)

Number of guests for which price is applied.

Needs to be non-negative integer and maximum 30.

---

closed boolean (Optional)

If set to 1 (or 0), this room will be closed (or opened) for the given date for the given rate category. All other information (such as roomstosell and price) is preserved.

The closed element functions as a restriction and defines whether a room is bookable or not.

---

minimumstay integer (Optional)

The minimum stay for the given room for the given date for the given rate category.

The minimumstay element functions as a restriction. If a booking takes place on this day a minimum stay (for the whole booking) of this number of days is required.

Each day in a stay has a room and rate category ID associated with it. Each set of consecutive days with the same rate category ID in a stay, must comply with the minimum stay setting of each of those days in that set (as if it were a separate stay).

Note this minimum stay restrictions have an effect on any given day of a booking, whereas the 'minimum stay arrival' restriction only affects a search for availability or reservation on the arrival date.

---

maximumstay integer (Optional)

The maximum stay for the given room for the given date for the given rate category.

The maximumstay element functions as a restriction. If a booking takes place on this day a maximum stay (for the whole booking) of this number of days is required.

Each day in a stay has a room and rate category ID associated with it. Each set of consecutive days with the same rate category ID in a stay, must comply with the maximum stay setting of each of those days in that set (as if it were a separate stay).

Note this maximum stay restrictions has an effect on any given day of a booking, whereas the maximum stay arrival' restriction only affects a search for availability or reservation on the arrival date.

---

minimumstaythrough integer (Optional)

The minimum stay through for the given room for the given date for the given rate category.

Properties set a policy requiring guests to stay a minimum number of nights during a specific period, from check-out for the given room and rate category. Example: A three-night minimumstaythrough is set for August 28th. Any guest whose stay includes that day (August 28th) must select a check-out date of 3 days or more from August 28th.

Constraints: Cannot be a negative number

---

maximumstaythrough integer (Optional)

The maximum stay through for the given room for the given date for the given rate category.

Properties set a policy restricting guests to stay a maximum number of nights during a specific period, from check-out for the given room and rate category. Example: A fourteen-night maximumstaythrough is set for August 28th. Any guest whose stay includes that day (August 28th) can only select a check-out date within 14 days from August 28th.

Constraints: Cannot be a negative number

---

closedonarrival boolean (Optional)

The closed on arrival setting (0 or 1). If set, the guest may not arrive in this room for the given room for the given date for the given rate category.

This restriction does not allow a reservation to be made when visitors want to arrive on the selected date. When the restriction is set to '0' for a certain date, guests are free to make a reservation with arrival on this date whereas a "1" will restrict guests to book rooms with this arrival date.

---

extraadultrate double (Optional)

The price for the extra adult for the given date for the given rate category.

extraadultrate cannot be removed after a value has been set, cannot be a negative number.

---

extrachildrate double (Optional)

The price for the extra child for the given date for the given rate category.

extrachildrate cannot be removed after a value has been set, cannot be a negative number.

---

closedondeparture boolean (Optional)

The closedondeparture setting (0 or 1). If set, the guest may not depart from this room for the given room for the given date for the given rate category.

This restriction does not allow a reservation to be made when visitors want to depart on the selected date.

When the restriction is set to '0' for a certain date, guests are free to make a reservation with departure on this date whereas a "1" will restrict guests to book rooms with this departure date.

---

Sample Request

To push updates for a single day use:

{
    "hotelid": "KC",
    "room": [{
        "roomid": "STD",
        "date": [{
            "value": "2020-08-17",
            "rate": [{
                "rateplanid": "BAR"
            }],
            "roomstosell": "15",
            "price": [{
                    "NumberOfGuests": "1",
                    "value": "290.00"
                },
                {
                    "NumberOfGuests": "2",
                    "value": "350.00"
                }
            ],
            "closed": "0",
            "minimumstay": "1",
            "maximumstay": "14",
            "closedonarrival": "0",
            "extraadultrate": "5.00",
            "extrachildrate": "2.00",
            "closedondeparture": "0"
        }]
    }]
}

To push updates for a date range use:

{
    "hotelid": "KC",
    "room": [{
        "roomid": "STD",
        "date": [{
            "from": "2020-08-15",
            "to": "2020-12-31",
            "rate": [{
                "rateplanid": "BAR"
            }],
            "roomstosell": "8",
            "price": [{
                    "NumberOfGuests": "1",
                    "value": "100.00"
                },
                {
                    "NumberOfGuests": "2",
                    "value": "120.00"
                }
            ],
            "closed": "0",
            "minimumstay": "1",
            "maximumstay": "14",
            "closedonarrival": "0",
            "extraadultrate": "10.00",
            "extrachildrate": "10.00",
            "closedondeparture": "0"
        }]
    }]
}

---

Response

Attributes

---

Status string

Status of the request.

---

TicketId string

The ticket id if the status of the request is success.

---

Sample Success Response

The sample response does the following:

• All changes made will have an effect on room with ID "1000202" and property with ID "P103".

• All changes made will have an effect on the 28th of August 2014.

• The room rate will be set to 2900.00 per night for the 1 guest and 3500.00 per night for the 2 guests of this room.

• The room will be open/bookable, because closed is set to 0.

• This room/rate/date combination can only be booked if the total reservation contains 2 or more nights.

• This room/rate/date combination can only be booked if the total reservation contains 14 or less nights.

• This room/rate/date combination is bookable when arriving on the 28th of August.

• guests cannot book this room/rate/date combination if their departure is on the 28th of August.

{
    "Status":"Success"
    "TicketId":159870515681827209466
}

---

You may receive some errors even if the response HTTP code is 200 OK.

Errors Due to Invalid Request Message Body

This error will be received if you try to push inventory for date range which is more than 730 days in future starting from current date.

Sample Error Response (921)

{
    "Status": "Fail",
	"Errors": [{
		"Code": "921",
		"ShortText": "Date : value should be less than 730 days from current date "
	}]
}

---

Errors Due to Maximum Capping Limit Reached for Number of Requests (per hour per property)

This error will occur if more than 10,000 updates are pushed per Hotel ID per hour. The maximum limit is 10,000 requests per property per hour. The cap is reset every hour, each day.

Sample Error Response

{
    "Status": "Fail",
    "Errors": [{
        "ShortText": "Limit has been reached"
    }]
}

---

Error Due to Invalid Request Message Body

This will consist of one element error and its value will be a free text string of all errors happened due to invalid message body data. Errors will be separated by semicolon ";".

Sample Error Response (873)

{
    "Status": "Fail",
	"Errors": [{
		"Code": "873",
		"ShortText": "price: Value is not a nonnegative (a non-negative number), found '2900r.00'"
	}]
}