Overview

By integrating the Book API, partners can send booking requests to Agoda in JSON format. We offer two URL endpoints: the mandatory Book API for making bookings and the optional Precheck API. Since hotel rates and availability are dynamic, price changes and allotment updates can cause booking failures. Therefore, we highly recommend using the Precheck API to verify the selected offer's validity before sending the book request.

1. Precheck API

Call the Precheck API to verify price and availability for the selected offer before sending a book request. It can run in the background while the customer enters their personal details in the booking form and helps reduce booking failures caused by rate or allotment changes.

2. Book API

Call the Book API to place the order after precheck succeeds. The response returns the booking result and, on success, the booking ID and processing status.

Booking Flow

Steps:

1. After the customer selects an offer and enters the booking form page, call the Precheck API to verify price and availability for the selected room(s).
2. If the precheck response is successful (status code = 200), proceed to call the Book API to place the order.
3. If the precheck response indicates a price change (status code= 501) or room unavailability (status codes= 502 or 503), halt the booking request and prompt the customer to choose an alternative offer.
4. If the book response is successful, the response returns the booking ID and "processing": false; if it returns "processing": true, the booking is still being processed; if the book response returns an error, the booking failed.

Notes

• The Precheck API call has a response SLA of 60 seconds. The Book API call has a response SLA of 120 seconds.
• If the precheck response takes longer than 60 seconds, partners should proceed with the booking request.
• If a book response returns "processing": true, it indicates the booking is still under processing and has not been confirmed. Partners should call the Booking Detail API confirm the booking status.
• If a timeout occurs while placing a booking, do not immediately resend the same booking request. Use your reference ID (Tag) check whether Agoda successfully received the reservation.
• If a precheck or book request fails due to a rate change, the response can support returning updated price details (priceMismatchData) for the affected room(s). Please refer to Precheck Failure with Updated Search Price / Book Failure with Updated Price Information for details.

The following flowchart can be used as a reference for the booking flow. (We understand some partners may not read processing flag when confirming bookings. In this case, please discuss with your technical account manager about the booking confirmation flow)

flowchart TD
    Start([Start]) --> CallPrecheck[Call the Precheck API]
    CallPrecheck --> PrecheckResult{Is the precheck response successful?}
    
    PrecheckResult -->|Error| HaltBooking([Halt the booking request])
    PrecheckResult -->|Timeout| CallBook[Proceed to call the Book API]
    PrecheckResult -->|Success| CallBook
    
    CallBook --> BookResult{Is the book response successful?}
    
    BookResult -->|Success| CheckProcessing{Is processing = true?}
    CheckProcessing -->|No| BookingComplete[Booking ID + processing: false]
    BookingComplete --> BookSuccess([Book Success])
    
    CheckProcessing -->|Yes| BookingProcessing[Booking ID + processing: true]
    BookingProcessing --> UnderProcessing[Booking under processing]
    UnderProcessing --> CallDetailAPI[Call the Booking Detail API]
    
    CallDetailAPI -->|Retry up to 30 minutes| CheckStatus{Status: BookingCharged / BookingConfirmed?}
    CheckStatus -->|Yes| BookSuccess
    CheckStatus -->|No| ManualCheck([Manual check with Agoda Customer Support])
    
    BookResult -->|Error| BookFailed([Book Failed])
    BookResult -->|Timeout| CallListAPI[Use tag to call the Booking List API]
    CallListAPI -->|Retry up to 10 minutes| BookingFound{Booking found?}
    BookingFound -->|No| BookFailed
    BookingFound -->|Yes| CallDetailAPI

    style Start fill:#e3f2fd,stroke:#1565c0
    style BookSuccess fill:#c8e6c9,stroke:#2e7d32
    style BookFailed fill:#ffcdd2,stroke:#c62828
    style HaltBooking fill:#ffcdd2,stroke:#c62828
    style ManualCheck fill:#fff9c4,stroke:#f57f17

Precheck API - Request Example

={
    "precheckDetails": {
        "searchId": 1629183207719830000,
        "tag": "00000000-0000-0000-0000-000000000000",
        "allowDuplication": false,
        "checkIn": "2022-12-23",
        "checkOut": "2022-12-24",
        "property": {
            "propertyId": 12157,
            "rooms": [{
                "currency": "USD",
                "paymentModel": "Merchant",                
                "blockId": "blockId_v3",
                “offerToken” : “offer_token”
                "count": 1,
                "adults": 2,
                "children": 2,
                "childrenAges": [5, 6],
                "rate": {
                    "inclusive": 798.58
                },
                "surcharges": [{
                    "id": 278,
                    "rate": {
                        "inclusive": 12.00
                    }
                }, {
                    "id": 279,
                    "rate": {
                        "inclusive": 12.00
                    }
                }]
            }]
        },
        "language": "en-us",
        "userCountry": "US"
    }
}

Parameters for Precheck API - Request Schema (* = Require)

Parameter for Precheck API - Response Example

Correct case - All room elements submitted passed precheck.

{
    "status": 200,
    "errorList": []
}

Price Failure (room)
If one room element fails the precheck due to a rate change, the other room elements are assumed to have passed the precheck. In case of a failure, only the room(s) with the issue will be returned, and these can be linked to the request using uid -> blockid.

{
    "status": 501,
    "message": "All room rate and allotment are not available",
    "errorList": [
        {
            "hotelId": 12153,
            "uid": "9a21a5bf-cc52-1cbe-c379-1a4b26a14c76",
            "code": 501,
            "message": "Room has allotment still available but the rate has changed"
        }
    ]
}

Allotment Failure (room)
If one room element fails the precheck due to no allotment, the other room elements are assumed to have passed the precheck. In case of a failure, only the room(s) with the issue will be returned, and these can be linked to the request using uid -> blockid.

{
    "status": 502,
    "message": "All room rate and allotment are not available",
    "errorList": [
        {
            "hotelId": 60001,
            "roomId": 3046618,
            "uid": "a82816db-c0c3-9ee0-a8eb-ed1a3f8af0ee",
            "code": 502,
            "message": "Hotel no longer has allotment"
        }
    ]
}

Price Failure combine with Allotment Failure (room)
If two room elements fail the precheck—one due to a price change and another due to no allotment—the other room elements are assumed to have passed the precheck. In case of a failure, only the room(s) with the issue will be returned, and these can be linked to the request using uid -> blockid.

{
    "status": 503,
    "message": "All room rate and allotment are not available",
    "errorList": [
        {
            "hotelId": 12153,
            "uid": "13d197b6-5d07-885d-ebb5-a351c9d2f0dd",
            "code": 503,
            "message": "Room no longer has allotment"
        }
    ]
}

Parameter for Precheck API - Response Schema (* = Require)

Precheck Failure with Updated Search Price

Important: This feature is not available for all partners. If you would like to enable it, please contact us.

Precheck API – Response Example

When a precheck fails due to a rate change, the response will include updated price information for the affected room(s).

If one room fails the precheck because of a rate change, only that specific room will be returned in the response. All other rooms are assumed to have passed the precheck.
You can identify the affected room(s) using the uid and blockid fields, which link the response to your original request.
The response will include a priceMismatchData field, which provides both the originally requested rate and the new rate, along with other relevant pricing details.
This allows you to handle price changes efficiently and present the most accurate information to your users.

{
    "status": 501,
    "message": "All room rate and allotment are not available",
    "errorList": [
        {
            "hotelId": 12153,
            "uid": "9a21a5bf-cc52-1cbe-c379-1a4b26a14c76",
            "code": 501,
            "message": "Room has allotment still available but the rate has changed",
            "priceMismatchData": {
                requestedRate: 95.14,
                rateMethod: "PRPN",
                currency: "USD",
                newRate: 99.24,
                searchResponse: {Object of Search Response from Search API Section }
            }
        }
    ]
}

Parameter for Precheck API - Response Schema (* = Require)

Book API

Book API - Request Example

{
  "waitTime": 120,
  "bookingDetails": {
    "userCountry": "US",
    "searchId": 1629183207719830000,
    "tag": "00000000-0000-0000-0000-000000000000",
    "allowDuplication": false,
    "checkIn": "2022-12-23",
    "checkOut": "2022-12-24",
    "property": {
      "propertyId": 12157,
      "rooms": [
        {          
           "blockId": "blockid_v3",
           “offerToken”: “offer_token”
          "rate": {
            "inclusive": 798.58
          },
          "surcharges": [
            {
              "id": 278,
              "rate": {
                "inclusive": 12
              }
            },
            {
              "id": 279,
              "rate": {
                "inclusive": 12
              }
            }
          ],
          "guestDetails": [
            {
              "title": "Mr.",
              "firstName": "JSONTest",
              "lastName": "JSONTest",
              "countryOfResidence": "US",
              "gender": "Male",
              "age": 30,
              "primary": true
            }
          ],
          "currency": "USD",
          "paymentModel": "Merchant",
          "count": 1,
          "adults": 2,
          "children": 2,
          "childrenAges": [
            5,
            6
          ],
          "specialRequest": "high floor"
        }
      ]
    }
  },
  "customerDetail": {
    "language": "en-us",
    "title": "Mr.",
    "firstName": "Test",
    "lastName": "Test",
    "email": "[email protected]",
    "phone": {
      "countryCode": "66",
      "areaCode": "2",
      "number": "22222222222"
    },
    "newsletter": false
  },
  "paymentDetails": {
    "creditCardInfo": {
      "cardType": "Visa",
      "number": 123456789000,
      "expiryDate": "032029",
      "cvc": 543,
      "holderName": "JSONTEST",
      "countryOfIssue": "US",
      "issuingBank": "BankName"
    }
  }
}

Parameters for Book API - Request Schema * = Require

Book API - Response Example

{
    "status": "200",
    "bookingDetails": [
        {
            "id": 80001230,
            "itineraryID": 70001230,
            "selfService": "https://master.qa.www.agoda.com/account/editbooking.html?bookingId=3ph/MkP30sOSifafln+WPw==",
            "processing": false
        }
    ]
}

Example of Error

{
  "status": "400",
  "errorMessage": {
    "id": "909",
    "subId": "7110",
    "message": "Sorry, there are no available rooms for your chosen dates"
  }
}

Parameters for Book API - Response Schema * = Require

Book Failure with Updated Price Information

Important: This feature is not available for all partners. If you would like to enable it, please contact us.

When a rate change occurs, the response will include the updated price details in the priceMismatchData field, providing both the originally requested rate and the new rate, along with relevant pricing information

Example of Error

{
  "status": "400",
  "errorMessage": {
    "id": "940",
    "message": "Room price has changed"
    "priceMismatchData": {
        requestedRate: 95.14,
        rateMethod: "PRPN",
        currency: "USD",
        newRate: 99.24,
        searchResponse: {Object of Search Response from Search API Section}
    }
  }
}