Introduction

By integrating the Book API, partners can send book 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 right before sending the book request.

Precheck API

The Precheck service aims to boost booking success rates by allowing partners to verify allotments and rates before sending a booking request. This can be done in the background while the customer enters their personal details in the booking form.

Successful Precheck: If the Precheck response is successful, the customer will enjoy a smooth booking process.
Failed Precheck: If the Precheck response fails, partners can inform customers to choose a different room offer.

Two scenarios can cause a Precheck to fail, and partners should halt the booking request:

Price Changes: Prices may change due to hotel owners updating rates, especially during peak seasons (status code = 501).
Room Unavailability: The room may no longer be available because it was booked by another customer or partner moments ago (status codes = 502 or 503).
Other scenarios where partners should continue with the booking request include:
- Successful Precheck: Allotment and price are still available (status code = 200).
- Timeouts: If the Precheck response takes longer than 60 seconds, partners should proceed with the booking request. Technical errors may occur internally or externally.
- Other Errors: Ignore technical errors and proceed with the booking request.
  Partners should implement the logic: IF status code is 501, 502, or 503, THEN ask the customer to find a different room offer; ELSE continue with the booking request.
  For detailed request and response information or a full API description; click here to see a sample.

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": "YmNlMTU5MzctYTE3MS0wMzAwLTQwNzctMjc1NWU1ZWUzNTE0OjMzMg==",
                "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)

Element	Attribute	Description
precheckDetails	searchId* integer	The unique search ID provided by the JSON search response. This helps link the search, precheck, and booking processes.Please note that searchid only valid for 1 hr. We encourage our partner to do a refresh search& percheck before book request, the time gap should be within a few mins between each calls
	tag string	Partner's reference numbers created by the partner's system. Note: Use English characters only.
	allowDuplication boolean	Possible values: `true`: The API will disregard booking duplication validation and allow the booking to proceed. `false`: The API will check for booking duplication and return an error without creating the booking. Suggestion: Build logic in your system to capture and block real duplicate bookings, then pass `allowDuplication=true` to us.
	checkIn* date	The check-in date in the format YYYY-MM-DD. It should be more than, equal to, or less than one day from today's date to account for property time zone differences.
	checkout* date	YYYY-MM-DD. The checkout date in the format YYYY-MM-DD. It must be the local hotel date and later than the check-in date.
	language* string	The language must be the same as used during the search. Refer to the Appendix for language codes.
	userCountry string	Guest’s nationality in ISO code format. It is recommended to implement this to get accurate rates. Details are in the Country section of the Appendix document. Accepts 2 characters containing a-z or A-Z. Note: The same `userCountry` must be passed throughout the BookRequest and PrecheckRequest.
precheckDetails->property	1 hotel in a precheckDetails
precheckDetails->property	propertyId* integer	Agoda's hotel ID
property > rooms	currency* string	Three-letter currency code. Details are in the Currency section of the Appendix. Note: The same currency used during the search is required. If booking multiple rooms, the currency in each Room element must match. Multiple currencies per room are not supported
	paymentModel* string	Possible values for paymentModel field are: - agency: Booking will be charged at the hotel - merchant, - merchantcommission
	blockId * string(max 500 bytes)	Unique identifier for each room, provide as a unique key for partner's caching.
	count* integer	Number of rooms required (non-negative integer). Note: The total number of rooms must match the number required during the search.
	adults* integer	Number of adults required (non-negative integer). Note: Available adults range from 1 to 36. Each room must have at least 1 adult, and the total number of adults across all rooms must match the number required during the search.
	children* integer	Number of children required (non-negative integer). Note: Available children range from 0 to 35. The total number of children across all rooms must match the number required during the search.
	bookNowPayLaterDate string	The date by which payment must be made for BNPL bookings
	childrenAges array[integer]	The age list of children (minimum: 0, maximum: 17). To be passed only when the number of children is greater than 0. The same `childrenAges` must be passed throughout the SearchRequest, PrecheckRequest, and BookRequest. Example: If there are 2 children aged 5 and 6, then `childrenAges: [5, 6]`. An empty array like `childrenAges: []` is not allowed. Extra beds and meals are not guaranteed for stay-for-free children.
property > rooms > rate	inclusive* number	Please use the inclusive rate you get in our search response under: properties->room->rate. Do not use the totalPayment rate
property > rooms > surcharges	id* integer
property > rooms > surcharges > rate	inclusive* number	decimal Surcharge inclusive amount

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)

Element	Attribute	Description
status* string		200: success 400: Invalid request format 501: rate precheck failure 502: hotel allotment precheck failure 503: room allotment precheck failure 500: internal server error
Message* string		Error message, e.g. All room rate and allotment are not available.
errorList	hotelId * Integer	Agoda Hotel IDs.
	roomId Integer	Room Identifier
	uid* string	This corresponds to the blockid of the room sent in the precheck request.
	code* string	501: rate precheck failure 502: hotel allotment precheck failure 503: room allotment precheck failure 500: internal server error
	message* string	Error message, e.g. All room rate and allotment are not available.

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)

Element	Attribute	Description
status* string		200: success 400: Invalid request format 501: rate precheck failure 502: hotel allotment precheck failure 503: room allotment precheck failure 500: internal server error
Message* string		Error message, e.g. All room rate and allotment are not available.
errorList	hotelId* Integer	Agoda Hotel IDs.
errorList	roomId Integer	Room Identifier
errorList	uid* string	This corresponds to the blockid of the room sent in the precheck request.
errorList	code* string	501: rate precheck failure 502: hotel allotment precheck failure 503: room allotment precheck failure 500: internal server error
errorList	message* string	Error message, e.g. All room rate and allotment are not available.
errorList > priceMismatchData (Not applicable for all partners.)	requestedRate Big Decimal	This fields is present in response when Error Code - 501: rate precheck failure And updated search price is available This corresponds to previous rate that have been sent in the pre check request. e.g. - 95.45
errorList > priceMismatchData (Not applicable for all partners.)	rateMethod string	This fields is present in response when Error Code - 501: rate precheck failure And updated search price is available This corresponds to payment method. e.g. - "PRPN"
errorList > priceMismatchData (Not applicable for all partners.)	currency string	This fields is present in response when Error Code - 501: rate precheck failure And updated search price is available This corresponds to currency. e.g. - "USD", "INR"
errorList > priceMismatchData (Not applicable for all partners.)	newRate Big Decimal	This fields is present in response when Error Code - 501: rate precheck failure And updated search price is available This corresponds to the changed rate e.g. - 100.45
errorList > priceMismatchData (Not applicable for all partners.)	searchResponse Search API Response	This fields is present in response when Error Code - 501: rate precheck failure And updated search price is available This corresponds to the search api response from Search API section

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": "YmNlMTU5MzctYTE3MS0wMzAwLTQwNzctMjc1NWU1ZWUzNTE0OjMzMg==",
          "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

Element	Attribute	Description
waitTime Integer		Specifies how long (in seconds) the partner want to wait for the Booking response. Minimum is 20 seconds, but 120 seconds is recommended.
bookingDetails*	searchId* Integer	The unique search ID provided by the JSON search response. This helps link the search, precheck, and booking processes. Please note that searchid only valid for 1 hr. We encourage our partner to do a refresh search& percheck before book request, the time gap should be within a few mins between each calls
	tag* String	Partner's reference numbers created by the partner's system. Note: Use English characters only.
	allowDuplication Boolean	Possible values: `true`: The API will disregard booking duplication validation and allow the booking to proceed. `false`: The API will check for booking duplication and return an error without creating the booking. Note: The default value is `false`. If `allowDuplication=true`, partners should build their duplication policy or checking logic, especially for non-refundable cases. If any dates of the stay period overlap, it will be considered a duplicate. Suggestion: Build logic in your system to capture duplicate bookings and pass `allowDuplication=true` to us.
	checkIn* date	The check-in date in the format YYYY-MM-DD. It should be more than, equal to, or less than one day from today's date to account for property time zone differences.
	checkOut* date	YYYY-MM-DD, Check-out date must be local hotel date
	userCountry String	Guest's nationality in ISO code format. Must be the same as the request performed in search and precheck.
bookingDetails > property*	propertyId* Integer	Integer Agoda Hotel IDs.
bookingDetails > property > rooms*	blockId* string(max 500 bytes)	Unique identifier for each room, provided as a unique key for the partner's caching.
	specialRequest String	Special request for this room (min 1 character, max 4,000 characters). Agoda will forward these to the hotel or host upon booking. Note: All special requests are subject to availability. Text can be in English or the local language.
	currency* String	Three-letter currency code. Details are in the Currency section of the Appendix. Note: The same currency used during the search is required. If booking multiple rooms, the currency in each Room element must match. Multiple currencies per room are not supported.
	paymentModel* String	Possible values for the paymentModel field are: `agency`: Booking will be charged at the hotel. `merchant` `merchantcommission`
	bookNowPayLaterDate String	The date by which payment must be made for BNPL bookings.
	count* Integer	Number of rooms required (non-negative integer). Note: The total number of rooms must match the number required during the search.
	adults* Integer	Number of adults required (non-negative integer). Note: Available adults range from 1 to 36. Each room must have at least 1 adult, and the total number of adults across all rooms must match the number required during the search.
	children* Integer	Number of children required (non-negative integer). Note: Available children range from 0 to 35. The total number of children across all rooms must match the number required during the search.
	childrenAges array[Integer]	The age list of children (minimum: 0, maximum: 17). To be passed only when the number of children is greater than 0. The same `childrenAges` must be passed throughout the SearchRequest, PrecheckRequest, and BookRequest. Example: If there are 2 children aged 5 and 6, then `childrenAges: [5, 6]`. An empty array like `childrenAges: []` is not allowed. Extra beds and meals are not guaranteed for stay-for-free children.
bookingDetails > property > rooms > rate*	inclusive* Number	The cost per room, inclusive of tax and service fees. Use the inclusive rate from the search response under `properties -> room -> rate` . Do not use the totalPayment rate.
bookingDetails > property > rooms > surcharges	id* Integer	The unique identifier for the surcharge.
bookingDetails > property > rooms > surcharges > rate*	inclusive* Number	The cost per room service charge inclusive of tax and service fees
	exclusive Number	The cost per room per night exclusive of tax and service fees
	tax Number	Tax amount of the room value.
	fees Number	Fees of the room value.
	margin Number	Two possible values for margin are: `y`: Margin applied. `n
bookingDetails > property > rooms > guestDetail*	title* String	Guest Title. Possible values are: - Mr. - Ms. - Mrs. - Dr. Note: This can be left blank.
	firstName* String	Guest First Name *English characters only. punctuation is not allowed
	lastName* String	Guest Last Name *English characters only. punctuation is not allowed
	countryOfResidence* String	Guest's nationality in ISO code format. Details are in the Country section of the Appendix document. Accepts 2 characters containing a-z or A-Z.
	gender String	Available values are: Male or Female.
	age Integer	Available age from 1 to 150 inclusive.
	isChild Boolean	True or False depending on whether the guest is a child
	primary Boolean	Indicates if this guest is the first/lead guest for the booking. The first guest should have this value set to true, and other guests should be set to false.
customerDetail*	language* String	Refer to the Appendix for language codes. This must match the language used in the JSON search request. Note: The same language must be passed throughout the SearchRequest, PrecheckRequest, and BookRequest.
	title* String	Customer Title. Possible values are: Mr. Ms. Mrs. Dr. Note: This can be left blank.
	firstName* String	Guest First Name *English characters only. Punctuation is not allowed.
	lastName* String	Guest Last Name *English characters only. Punctuation is not allowed.
	email* String	Accepts English characters only. White-space characters are not allowed. Partner fulfillment model (Partner handles payment and customer service): Use the Partner Email address (fixed) for pay-in-advance (Merchant) bookings, and use the customer email address for pay-at-hotel (Agency) bookings. Agoda fulfill assisted model (Agoda handles payment and customer service): Use the customer email address.
	newsletter* Boolean	Possible values are: true false Note: Use this to indicate if a newsletter is needed.
customerDetail > phone*	countryCode String	Customer Country Code for Phone.
	areaCode String	Customer Area Code for Phone.
	Number* String	Customer Phone Number. Accepts 5 to 15 numerical values. White-space or any punctuation is not allowed.
paymentDetails > creditCardInfo	cardType* String	Possible values for the cardType field are: Visa MasterCard JCB AmericanExpress CarteBleue Discover Note: Discover card is not available for all partners. Please get confirmation from Agoda. Refer to the appendix document for accepted currencies per payment card section. If cardType is Discover, please also see countryOfIssue and issuingBank elements. For CC partners, you should send paymentDetails, including cardType, number, expiryDate, cvc, holderName, and countryOfIssue. For Invoice partners, please keep paymentDetails blank.
	number* String	Credit card number will consist of 15 or 16 digits. Each digit can be 0-9.
	expiryDate* String	Expiry Date in the format MMYYYY. Each character can be 0-9.
	cvc* String	CVC code consisting of 3-4 digits. Each digit can be 0-9.
	holderName* String	Cardholder name.
	countryOfIssue* String	ISO code.
	issuingBank* string	If cardtype=Discover, please send Discover in this element

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

Element	Attribute	Description
status* String		Details are on Response Codes Part (Appendix)
bookingDetails	id* Integer	Agoda Booking Id
	iteineraryId* Integer	Agoda itinerary Id.
	selfService* String	This is providing URL for selfservice platform.
	processing Boolean	True, if booking is processing. False, if booking processing is completed and booking is confirmed.
errorMessage	id* String	Error Id
	subId* String	Error subId to identify exact sub system erro
	message* String	Error reason, e.g. Authentication failed.

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}
    }
  }
}

Element	Attribute	Description
status* String		Details are on Response Codes Part (Appendix)
bookingDetails	id* Integer	Agoda Booking Id
bookingDetails	itineraryId* Integer	Agoda Itinerary Id.
bookingDetails	selfService* String	This is providing URL for selfservice platform.
bookingDetails	processing Boolean	True, if booking is processing. False, if booking processing is completed and booking is confirmed.
errorMessage	id* String	Error Id
errorMessage	subId* String	Error subId to identify exact sub system error
errorMessage	message* String	Error reason, e.g. Authentication failed.
errorMessage >>priceMismatchData (Not applicable for all partners.)	requestedRate Big Decimal	This fields is present in response when room price changes during booking And updated search price is available This corresponds to previous rate that have been sent in the pre check request. e.g. - 95.45
errorMessage >>priceMismatchData (Not applicable for all partners.)	rateMethod string	This fields is present in response when room price changes during booking And updated search price is available This corresponds to payment method. e.g. - "PRPN"
errorMessage >>priceMismatchData (Not applicable for all partners.)	currency string	This fields is present in response when room price changes during booking And updated search price is available This corresponds to currency. e.g. - "USD", "INR"
errorMessage >>priceMismatchData (Not applicable for all partners.)	newRate Big Decimal	This fields is present in response when room price changes during booking And updated search price is available This corresponds to the changed rate e.g. - 100.45
errorMessage >>priceMismatchData (Not applicable for all partners.)	searchResponse Search API Response	This fields is present in response when room price changes during booking And updated search price is available This corresponds to the search api response from Search API section