Dynamic API

1. Integration

Q: What is Agoda API Integration workflow?
A:

Q: Does Agoda need to add my domain/URL/IPs into Agoda whitelist?
A: Yes. please provide your IP for our whitelist

2. Search Related

Q: Does Agoda API have any rate limiter?
A: Yes, Agoda has rate limiters on both content and dynamic APIs. The exact limits will be provided during onboarding. If exceeded, you will receive a "429 error - too many requests."

Q: Does Agoda provide a demo account for testing before completing all commercial procedures?
A: No, due to security concerns and varying configurations, Agoda does not provide demo accounts.

Q: What’s the maximum number of hotels I can send in one search request?
A: For JSON API, you can send up to 100 properties for the cheapest rates. If "ratesPerProperty" is not provided, you will always get the cheapest rate per property.

Q: Why can't I find Agoda landing URL in JSON search response?
A: Ensure "metaSearch" is included in the extra parameters. If not, add it to get detailed information.

Q: How can I know which rate needs to be paid at hotel?
A: Check the "paymentModel" field. If it is "Agency," the booking will be charged at the hotel. If it is "Merchant" or "Merchantcommission," the booking will be prepaid.

Q: What's the meaning of "blockId" and "blockBackup" in search response?
A: "blockId" is the unique identifier for each product in JSON API. Use this for caching instead of parameters like room type, benefits, and cancellation policy. "blockIdBackup" is the old version in XML format and will be decommissioned after all partners migrate to JSON API.

Q: What to do if there is no available room allotment returned by the API, but the Agoda website shows availability?
A: Do not compare the price/inventory you receive in the API with our website.

3. Precheck Related

Q: Do I need to integrate precheck API?
A: It is optional but strongly recommended for better technical performance and customer experience.

Q: What should I do after getting precheck failure?
A: If the precheck status code is (501, 502, 503), ask the customer to find a different room offer. If the status code isn't (501, 502, 503) or times out, continue submitting the booking request.

Precheck / Makebook Failure with Updated Search Price

Q: Will the new price be returned for all offers when there’s a price difference?
A: No. The updated price will only be returned for the specific offer selected by the partner during Precheck/Makebook.

Q: Will the updated price always be returned in case of price changes?
A: Typically, the Precheck/Makebook API will return the updated price when there are price changes. Updated prices are retrieved by making another call to the Affiliate Search API. However, if errors, rate limiting, or timeouts occur, the Precheck/Makebook API will return the existing failure response without changes

.
Q: When the Precheck API returns the updated price due to price changes, is a secondary Precheck mandatory?
A: A secondary Precheck is not mandatory. Partners can call the Makebook API directly with the updated rate.

Q: Can the feature be enabled separately for Precheck and Makebook API?
A: Yes, the feature can be enabled separately.

4. Booking Related

Q: What are some common causes of booking failures?

A: Booking failures are most commonly due to: 1) Duplication validation if allowDuplication is set to false, 2) tTimeout during booking processing, 3) Parameters out-of-sync throughout the booking flow (search → precheck ->book), and 4) API errors or system maintenance. More information can be found in the Book API section of our Best Practices page.

Q: Why did I receive a "Room price has changed" error?

A: Such errors typically occur due to discrepancies between the price at the time of search and booking, often due to dynamic pricing, inventory updates, or mismatched parameter submission between the Availability Search and Booking creation stage.

Q: What causes HTTP 400 errors (Bad Request)?

A: HTTP 400 errors usually indicate that the request format sent to the server is malformed or missing required parameters. We will provide an Agoda error message for this type of error, which provides more detailed information.
If the error message is unclear, please contact your tech manager.

Q: What does a "Guest nationality restriction by hotel" error mean?

A: This means that the booking was rejected because the property enforces restrictions based on guest nationality, which may be due to local government regulations or other factors that Agoda cannot control. More information about this restriction can be found in our content Feed 19.

Q: Why do I need to give "searchId" in JSON Booking API?
A: The unique searchId from the JSON search response helps link search -> precheck -> booking.

Q: How can I use "allowDuplication" in JSON Booking API?
A: If "allowDuplication"=true, Agoda API will disregard booking duplication validation. Partners should build their duplication policy, especially for non-refundable cases. If "allowDuplication"=false, Agoda API will check for duplicates and return an error without creating a booking. The default is false, and it will be considered a duplicate if any dates overlap.

Q: How can I use "tag" in JSON Booking API?
A: "tag" is a unique partner reference string created by the partner's system, useful in scenarios like booking timeouts.

Q: How can I send special requests to Agoda?
A: Send special requests using the Booking API when creating the booking or the Special Request API after the booking is created. Requests can be in English or the hotel's local language, with a minimum of 1 character and a maximum of 4,000 characters. Agoda will forward these to the hotel or host, but fulfillment is not guaranteed.

Q: What email address should I send in customer detail?
A: If the partner handles payment and customer service, use the partner's email for pay-in-advance bookings and the customer's email for pay-at-hotel (Agency) bookings. If Agoda handles payment and customer service, use the customer's email.

Q: What should I do if I get the booking id with the "processing"=true in booking response?
A: If "processing" is true, the booking is still processing. Do not confirm the booking to customers and keep checking the status through BookingList or BookingDetail API. If still pending after 30 minutes, consider it a booking failure.
Q: Can I amend bookings via API?
A: Yes , we have amendment API to support date, guest name and special request amendment​.

Q: My payment method is invoicing, what should I send in section via BookRequest?
A: If you have signed a commercial agreement with the invoicing payment model, you need to send a self-closing tag via BookRequest.

5. Post-Booking Related

Q: How to handle discrepancies in post-booking data?

A: Continuously check the booking status through BookingList or BookingDetail API, and if discrepancies exist, update the necessary details or consult Agoda support.

Q: What steps to follow if cancellation fails?

A:The cancellation process involves two steps: first, call the Cancel API and then call the Confirm Cancel API. If any of the step failed, Please contact Agoda Support

Q: What should I do if I get timeout or no response after sending the booking requests?
A: Use your unique booking tags as "tags" when calling the Agoda BookingList API to continuously check the booking information. For example, make the first API call 1 minute after booking, the second call 2 minutes after booking, and the third call 5 minutes after booking.

Q: What should I do when I get "Awaiting" in "supplierReference" after creating booking?
A: If "supplierReference" shows "Awaiting", you can send a voucher to the customer without this check-in reference information. Then, call the BookingDetail API to check this information again a few hours or days before the check-in date.

Q: How can I cancel my booking?
A: The cancellation process involves two steps: first, call the Cancel API, and then call the Confirm Cancel API.

Q: How can I get the hotel confirmation number?
A: The Hotel Confirmation Number (HCN) is available in the hotelConfirmationNumber field in the Booking Details API. You may share this with customers for reference.

Q: What is the difference between hotelConfirmationNumber and supplierReference in the Booking Details API?
A:hotelConfirmationNumber (HCN): The unique confirmation number assigned by the hotel, used to identify the booking in the hotel’s system.
supplierReference: The reference number provided by the supplier. It may not always match the hotel’s own confirmation number.

Q: Will all bookings have an HCN in the Booking Details API?
A: No. Most bookings will have an HCN, but for some (such as those routed through certain suppliers), the HCN may not be available. In these cases, use the Agoda Booking ID (BID) or supplierReference to locate the reservation.

Q: Is there a recommended cut-off time for partners to start calling CS team for HCN?
A: Yes. The recommended cut-off time is by 23:59:59 (hotel local time) on the check-in date. Partners can continue polling for the HCN until the end of the check-in day.

Amendment Related

Q: How do I identify if a booking is amendable?
A: A new field, amendmentFeatures, will be introduced in Booking Details to indicate amendment eligibility. Sample response:"amendmentFeatures": ["DateAmendment", "GuestInfoAmendment", "SpecialRequest"]

Q: Are amendments allowed for both refundable and non-refundable bookings?
A: Yes. Eligibility depends on the values returned in the booking details response.

Q: What is the estimated SLA for the Amendment Confirm API? How long should partners wait to ensure the amendment was successful?
A: The estimated SLA is 120 seconds. If the amendment status is still pending after this time (in rare cases), you can check the status by calling the Booking Details API and reviewing the amendment status.

Q: If a booking was created with only primary guest information, can I add secondary guests via this amendment?
A: Yes. In your Amendment API call, keep the primaryGuest unchanged and add secondaryGuests to include additional guest information.

Q: How do I change only the primary guest’s name without affecting secondary guests?
A: In the Amendment API call, provide only the updated primaryGuest details and omit secondaryGuests.

Q: How do I change only the primary guest name without changing secondary guests?
A: In the Amendment API call, provide only the primaryGuest details and do not include secondaryGuests.

Q: Can a booking have more than one primary guest in a Guest Info Amendment?
A: No. Each booking can have only one primary guest.

Q: What happens if I try to amend more guest names than the number of guests in the booking?
A: This is not allowed. The Confirm Amendment request will fail.

Q: Can I modify guest details such as nationality, gender, or children’s ages?
A: No. Only guest name changes are allowed. Other information must remain consistent.

Q: If a customer wants to amend guest information again, can the partner proceed while the previous amendment is pending?
A: No. If amendmentStatus is pending, further amendments cannot be made.

Q: If a customer wants to send a special request, can the partner proceed while the previous amendment is pending?
A: Yes. Special requests are independent of other amendments (Guest/Date).

Q: Are special requests included in the Amendment History in the Booking Details API?
A: No, this is expected.

Q: Is there a limitation on the number of amendments allowed on a booking?
A: No, there are no limitations.

Q: Do amendments happen in real time, or are they sent to the hotel for approval?
A: Some amendments are processed in real time, while others require property approval. This depends on supply and hotel configuration. Always check the Booking Details API to confirm the amendment status..

Sandbox API

Q: Why I can't find any search result from several hotels on Sanbox?
A: Please ensure you use Sandbox hotel list in: BestPractices.

Q: I can't find my test booking from BookingList and BookingDetail API.
A: This could be due to our weekly Sandbox maintenance, which cleans up all existing bookings, or you may have sent the BookingDetail request too soon. Please wait 30 seconds after receiving the BookResponse.

Q: I get 'No search result' from the list of Sandbox test hotels. What to do?
A: This might be due to data sync or cache update delays. Please retry with other available Sandbox test hotels.

Q: I get 'Internal Error' or other system internal errors from in the response. What to do?
A: If the errors are not from your side, please contact Agoda for assistance.

Q: How to handle booking failures in sandbox?

A:Please refer to error message to identify specific issues, correct it and make a book again. If all are correct but you still cannot make a book, please contact your tech manager.

Q: What to do if sandbox API requests time out?

A: Retry the requests after some time; if issues persist, contact Agoda support for further assistance.

Static API

Q: How can I get hotel and room detail information?
A: Agoda provides a Content Feed API for hotel and room details. The URL and usage instructions will be included in the welcome package.

Q: How many photos can I get from Agoda?
A: You can get up to 20 photos for each hotel and 3 photos for each room.

Q: What are the steps to Access the hotel Information by Brands?
A: 1. Feed 20: To get all the hotel brands; 2.Feed 16: To get the Hotel per brand; 3:Feed 19: Use Hotel_IDs to get full hotel information, including other languages by specifying olanguage_id as an optional paramet

Q: Do you have any advice on the priority of mapping?
A: Focus on high-probability hotels that convert to bookings to improve the search-to-book ratio by updating the content feed.

Q: What is the recommendation logic and frequency for static content refreshing?
A: Refresh content information frequently to keep it up-to-date. Schedule two jobs for static content refresh:
Weekly refresh job: Target all hotels using Feed3, Feed5, Feed13, and Feed19.
Daily refresh job: Target changed hotels using Feed32 and Feed19.

Q: What are room types I should map?
A: Map the Agoda master room type, which you can find indicated via the Content API.

Q: Why do I always receive 'API Suspended'?
A: This happens because you send too many requests to the Agoda Data Feed, exceeding our suspension limit. Once suspended, traffic will be blocked for 15 seconds. Spread out your requests throughout the day instead of sending them all at once.

Q: What should I do if Agoda's content information is wrong and leads to disputes?
A: Please raise "Dispute Inquiry" tickets via https://traveldistribution.support.agoda.com/kb/s/contactsupport/support-ticket-page to us for further investigation.