HomeGuides
Guides

Retrieve Bookings

Suggest Edits

Retrieve bookings

Agoda offers two methods to access booking information, enhancing the visibility of your production.

Booking List API

This API provides a list of bookings based on specified criteria such as date range or tags (your own booking reference ID). Check out the sample request and response below.

Book List API - By DataTime Request Example

{
  "dateTimeRange": {
    "from": "2021-11-19T00:00:00",
    "to": "2021-11-19T01:00:00"
  }
}

Book List API - By Tags Request Example


{
  "tags": [
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  ]
}

Parameters for Booking List Request Schema (* = Require)

Element
Attribute
Description

BookingListRequestV4 > dateTimeRange

from*
datetime 		The start date and time for the booking made date or last modified time. The maximum query window is 24 hours.

To*
datetime 		The end date and time, which must be within 24 hours from the "from" time. Note that the time is in the Bangkok time zone.

BookingListRequestV4 > tags

 Tags*
array[String] 		Tags are identifiers you generate and assign to your bookings. You can search for bookings using these tags. A single request can include up to 1,000 tags.

BookingList API - Response Example by datetime or tags

{
  "bookings": [
    {
      "id": 61399351,
      "status": "Departed",
      "tag": "77777777-7777-7777-7777-777777777777",
      "propertyId": 6110691,
      "propertyName": "Affiliate API Test Booking",
      "cityName": "Bangkok",
      "received": "2020-02-09T14:32:00.000+05:30",
      "lastModified": "2020-02-21T00:10:00.000+05:30",
      "checkIn": "2020-02-19",
      "checkOut": "2020-02-20",
      "payment": {
        "paymentRate": {
          "currency": "USD",
          "exclusive": 4.09,
          "inclusive": 4.09
        }
      },
      "selfService": "https://master.qa.www.agoda.com/mybooking/customer-request.aspx?cid=1802330&NjEzOTkzNTEequAL-E7udFYCRqLsequAL"
    }
  ]
}

Parameters for BookingList Response Schema (* = Require)

Element
Attribute
Description
BookingListResponseV4 -> bookings id*
integer 		Booking ID.

status*
string 		Possible values for status field are: BookingReceived, BookingCharged, BookingConfirmed, Departed, BookingRejected, BookingCancelled, BookingCancelledByCustomer, BookingTest, TechnicalError, AllotmentAlert

tag*
string 		Your booking reference number.

propertyId*
integer 		Hotel ID

propertyName*
string 		Hotel Name

cityName*
string 		City Name

received*
datetime 		Booking received datetime

lastModified*
datetime 		Booking last modified datetime

checkIn*
date 		Check-in date

checkOut*
date 		Check-out date

selfservice
string 		Self service URL to amend or cancel booking.
BookingListResponseV4 -> bookings -> payment -> paymentRate currency
string 		USD

exclusive
decimal 		Amount of booking in USD, excluding taxes and fees.

inclusive
decimal 		Amount of booking in USD.

BookingList API - Response Example (Error case)

{
    "errorMessage": {
        "id": "907",
        "message": "Invalid data: From date is not earlier than To date"
    }
}

Parameters for BookingList Response Schema (Error case) (* = Require)

Element
Attribute
Description
BookingListResponseV4 -> errorMessage id*
string 		Details are on Response Body Part (Appendix)

subId
string

message
string 		Details are on Response Body Part (Appendix)

Booking Detail API

This API gives detailed information for each booking based on specified booking IDs. Note that you can request details for up to 40 booking IDs at a time. See the sample request and response below.

Recommendation:
Wait at least 1 minute before calling the POST BOOKING API after receiving the BOOKAPI. Implement retry logic for the BookingList/BookingDetails API: at least 3 attempts within 15 minutes.

Booking Detail API - Request Example

{
    "bookingIds": [
        80000040
    ]
}

Parameters for Booking Detail Request Schema (* = Require)

Element
Attribute
Description
BookingDetailRequestV4 bookingIds*
array[integer] 		List of Booking ids, Max: 40 Booking IDs, but recommend <=10 for best performance.

BookingDetail API - Response Example (Correct case)

{
  "bookings": [
    {
      "bookingId": 80000040,
      "tag": "12345667",
      "status": "BookingCharged",
      "checkIn": "2021-12-01",
      "checkOut": "2021-12-02",
      "naturalDisaster": false,
      "property": {
        "propertyName": "Kurumba Maldives",
        "country": "Maldives",
        "city": "Maldives Islands",
        "addressLine1": "Avenue Connaught Place, City Center New Delhi 110001",
        "addressLine2": ""
      },
      "amendments": [
        {
          "amendmentId": "12318131",
          "amendmendType": "DateAmendment",
          "amendmentStatus": "Confirmed",
          "amendmentDate": "2024-07-26T07:43:20.786Z"
        }
      ],
      "amendmentFeatures": [
        "DateAmendment",
        "GuestInfoAmendment",
        "SpecialRequest"
      ],
      "room": {
        "roomType": "Beachfront Deluxe Bungalows",
        "roomsBooked": 1,
        "ratePlan": "Retail",
        "rateType": "Sell"
      },
      "totalRates": [
        {
          "currency": "USD",
          "exclusive": 448.90,
          "inclusive": 551.65,
          "tax": 66.33,
          "fees": 36.42
        }
      ],
      "taxSurchargeInfo": "Included : Taxes and fees USD 87.36",
      "payment": {
        "rates": [
          {
            "currency": "USD",
            "inclusive": 551.65
          }
        ]
      },
      "agodaPromotion": false,
      "source": "Hotel",
      "supplierReference": "1",
      "cancellationPolicy": "Any cancellation received within 3 days prior to arrival date will incur the full period charge. Failure to arrive at your hotel or property will be treated as a No-Show and no refund will be given (Property policy).",
      "howToGetThere": "",
      "specialRequest": "High floor",
      "occupancy": {
        "numberOfAdults": 2,
        "numberOfChildren": 0
      },
      "isFeeWaiverAllowed": true,
      "feeWaiverStatus": "Pending",
      "bookingDate": "2024-11-26T05:42:33.000+07:00",
      "hotelConfirmationNumber": "R5180672169926001"
    }
  ]
}

Parameters for Booking Detail Response Schema (Correct case) (* = Require)

Element Attribute Description
BookingDetailsResponseV4 > bookings bookingId*
Integer		 Booking ID
BookingDetailsResponseV4 > bookings tag*
string		 Your booking reference number.
BookingDetailsResponseV4 > bookings status*
string		 Possible values for status field are:
BookingReceived,
BookingCharged, BookingConfirmed,
Departed,
BookingRejected,
BookingCancelled, BookingCancelledByCustomer,
BookingTest,TechnicalError,AllotmentAlert
BookingDetailsResponseV4 > bookings cancellationReason
string		 Reason if booking is cancelled
BookingDetailsResponseV4 > bookings checkIn*
date		 Check-in date
BookingDetailsResponseV4 > bookings checkOut*
date		 Check-out date
BookingDetailsResponseV4 > bookings bookingDate*
datetime		 Booking creation datetime
BookingDetailsResponseV4 > bookings naturalDisaster
boolean		 True if booking impacted by natural disaster
BookingDetailsResponseV4 > bookings taxSurchargeInfo
string		 Information about Tax Surcharges.
BookingDetailsResponseV4 > bookings > property propertyName*
string		 Hotel Name
BookingDetailsResponseV4 > bookings > property country*
string		 Country where hotel located.
BookingDetailsResponseV4 > bookings > property city*
string		 City where hotel located.
BookingDetailsResponseV4 > bookings > property phoneNumber
string		 Phone number for the hotel
BookingDetailsResponseV4 > bookings > property addressLine1*
string		 Address Line 1 for the hotel
BookingDetailsResponseV4 > bookings > property addressLine2
string		 Address Line 2 for the hotel
BookingDetailsResponseV4 > bookings > property hotelEmailAddress
string		 Email address for the hotel
BookingDetailsResponseV4 > bookings > amendments amendmentId
Integer		 The amendment id
BookingDetailsResponseV4 > bookings > amendments amendmentType
String		 Amendment type. Possible values are as below.
- DateAmendment
- GuestInfoAmendment
- Other (Other = cancellation)
Note: Special Request amendment would not be listed in amendment section below. Refer to the specialRequest node.
BookingDetailsResponseV4 > bookings > amendments amendmentStatus
String		 Amendment Status. Possible Values:
- Confirmed
- Rejected
- Cancelled
- Pending
BookingDetailsResponseV4 > bookings > amendments amendmentDate
String		 The amendment date, date time format: 2024-07-09T10:43:20.786Z
BookingDetailsResponseV4 > bookings amendmentFeatures
array[string]		 Used to list only the allowed amendment on the booking.
Possible values:
- DateAmendment
- GuestInfoAmendment
- SpecialRequestAmendment
BookingDetailsResponseV4 > bookings > room roomType*
string		 Room Type
BookingDetailsResponseV4 > bookings > room roomBooked*
integer		 Number of rooms booked
BookingDetailsResponseV4 > bookings > room ratePlan*
string		 Rate Plan
BookingDetailsResponseV4 > bookings > room rateType*
string		 Rate Type Name
BookingDetailsResponseV4 > bookings > room roomTypeNotGuaranteed
boolean		 true if Room type not guaranteed
BookingDetailsResponseV4 > bookings > room > benefits id*
integer		 Benefit Identifier
BookingDetailsResponseV4 > bookings > room > benefits benefitName*
string		 Benefit Name
BookingDetailsResponseV4 > bookings > totalRates currency*
string		 USD
BookingDetailsResponseV4 > bookings > totalRates exclusive*
decimal		 Room rate exclusive in USD
BookingDetailsResponseV4 > bookings > totalRates inclusive*
decimal		 Room rate inclusive in USD
BookingDetailsResponseV4 > bookings > totalRates tax*
decimal		 Total room tax in USD
BookingDetailsResponseV4 > bookings > totalRates fees*
decimal		 Total room fees in USD
BookingDetailsResponseV4 > bookings > totalRates processingFee
decimal
BookingDetailsResponseV4 > bookings > totalRates estimatedCommission
decimal
BookingDetailsResponseV4 > bookings > payment creditCardNumber
string
BookingDetailsResponseV4 > bookings > payment> rates currency
string		 Booking payment currency. Details are on Currency Part (Appendix)
BookingDetailsResponseV4 > bookings > payment > rates inclusive
decimal		 Booking payment amount. It's possible to be paid in different currency.
BookingDetailsResponseV4 > bookings > payment > rates exclusive
decimal
BookingDetailsResponseV4 > bookings > payment > rates tax
decimal
BookingDetailsResponseV4 > bookings > payment > rates fees
decimal
BookingDetailsResponseV4 > bookings > payment > rates agxReferenceCommission
decimal
BookingDetailsResponseV4 > bookings > payment > rates agpReferenceCommission
decimal
BookingDetailsResponseV4 > bookings > payment > rates method
string
BookingDetailsResponseV4 > bookings > payment > rates localCurrency
string
BookingDetailsResponseV4 > bookings > payment > rates localCurrencyAmount
decimal
BookingDetailsResponseV4 > bookings > payment > rates agodaPromotion
boolean		 True if booking applied with promotion.
BookingDetailsResponseV4 > bookings > guestDetails title*
string		 Enum of values including "Mr.","Ms.","Mrs.","Dr."
BookingDetailsResponseV4 > bookings > guestDetails firstName*
string		 First Name of guest
BookingDetailsResponseV4 > bookings > guestDetails lastName*
string		 Last Name of guest
BookingDetailsResponseV4 > bookings > guestDetails countryOfPassport*
string
BookingDetailsResponseV4 > bookings > guestDetails primary*
boolean
BookingDetailsResponseV4 > bookings selfService
string
BookingDetailsResponseV4 > bookings source
string		 Accommodation type
BookingDetailsResponseV4 > bookings supplierReference
string		 Agoda's reference number.
BookingDetailsResponseV4 > bookings bookNowPayLaterDate
date
BookingDetailsResponseV4 > bookings checkInInstructionURL
string
BookingDetailsResponseV4 > bookings cancellationPolicy
string		 Cancellation policy in text format.
BookingDetailsResponseV4 > bookings howToGetThere
string		 Guidance provided by host about how to get to the property.
BookingDetailsResponseV4 > bookings specialRequest
string
BookingDetailsResponseV4 > bookings > occupancy numberOfAdults*
integer
BookingDetailsResponseV4 > bookings > occupancy numberOfChildren*
integer
BookingDetailsResponseV4 > bookings > social grabId
integer
BookingDetailsResponseV4 > bookings > social pinCode
integer
BookingDetailsResponseV4 > bookings isFeeWaiverAllowed
boolean		 True if booking is applicable for fee waiver.
BookingDetailsResponseV4 > bookings feeWaiveStatus
string
BookingDetailsResponseV4 > bookings hotelConfirmationNumber
string		 Displays the hotel confirmation number for the booking. If the booking does not have a hotel confirmation number, empty string will be returned.

BookingDetail API - Response Example (Error case)

{
    "errorMessage": {
        "id": "909",
        "message": "Internal Error"
    }
}

Parameters for Booking Detail Response Schema (Error case) (* = Require)

Element
Attribute
Description
BookingListResponseV4 -> errorMessage id*
string 		Details are on Response Body Part (Appendix)

subId
string

message
string 		Details are on Response Body Part (Appendix)

Updated 4 months ago