1. Prohibited Countries Policy

We do not operate in or have any affiliations with the following countries: Cuba, Syria, Sudan, Iran, and North Korea. Consequently, you will not find hotels from these countries in our system, and bookings from customers in these regions will be rejected.

2. Sandbox Environment

• Our sandbox servers are identical to our production servers, but any booking requests made to will not result in actual hotel reservations or credit card charges.
• Use the sandbox environment to test functionality and verify data, then re-verify in the live environment.
• The JSON request format in the sandbox is less strict than in the live environment, so minor errors might pass in the sandbox but not in production.
• All JSON requests must strictly follow the API specifications, such as using guest titles like “Mr.”, “Ms.”, “Mrs.”, or “Dr.” only.
• Sandbox maintenance occurs daily from 5:30 PM to 6:30 PM IST. During this time, there may be some expected downtime. We kindly encourage you to avoid testing during this maintenance window to ensure a smoother experience
• Test bookings will remain for 7 days, and the environment will be refreshed every Friday at 11:00 AM GMT+7.
• To enhance sandbox performance, we have defined a list of properties to cover all test cases as follows:

Sandbox supported Hotel

3. Environment Setup

• In an HTTP POST request, the Authorization parameter is mandatory for all APIs. If omitted, the API will return the error message: "Site ID or API key is invalid or missing in the header."
• For security, to comply with the PCI Security Industry Standard, all partners must ensure that TLS v1.2 is used by their production systems.
• To maintain high-quality service on our APIs, partners should set a time-to-live (TTL) of ≤5 minutes on DNS servers and applications connecting to Agoda API URLs. This allows Agoda to quickly switch to another data center if one becomes unavailable.
• To test cURL installation, use the Curl Command, a tool to check if your request can reach the Agoda application gateway. This command can be run on Windows, Linux, or Unix.
• For application timeout settings, set a 30-second timeout for all API calls, except for Precheck (60 seconds) and Booking API (120 seconds).

4. Mandatory Hotel Content

• Hotel Remark
  A ‘notice’ to customers if there are particular events or situations happening at a hotel. This information can be pulled from Data Feed # 19.

• Child and Extra beds policy
  A ‘notice’ to customers if there are any additional costs for extra beds and what age to define children.

5. Search API

• Hotellist search Supports maximum 100 hotels per request. Please refer to “ratesPerProperty” for details. (all search requests can be sent in parallel)

• Search criteria

  • Maximum of "rooms":20
  • Maximum of "adults":36
  • Maximum of "children":35
  • Default maximum length of stay is 30 days
    If partners have a long stay booking demand, please contact your agoda representative for further discussion to implement length of stay more than 30 days
  • Check-in and Check-out date must be within 1 year

• Children are NOT allowed to stay at a hotel unless adults accompany them, then number of "adults" must be “greater or equal to” number of "rooms"

• Important information from Search response API:

  • 1.Extra bed available or not under "extraBeds" tag
  • 2.The Inclusive attribute inside the Rate element is per room per night rate
  • 3.Cancellation policy indicated under "cancellationPolicy"
  • 4.Cancellation is based on property time zone. And cancellation amount indicated under "properties -> cancellationPolicy -> date -> rate"
  • 5.Meal plans mentioned for each room under "benefits"

  Benefit Category	Sample	How to define quantities
  Breakfast without specific quantities, please refer to normal bedding field.		[normalBedding] breakfasts per room per nightIn this case, 2 breakfasts per room per night
  Breakfast with specific quantities		2 breakfasts per room per night, in this case this explicit value overrides the #1 scenario
  Breakfast with structured quantities		${1} breakfast per room per night In this case, 4 breakfast per room per night

  
  

6. Excluded Surcharges

Excluded Surcharges are charges that must be paid directly to the hotel by the customer, and must be shown to customers before booking so that they can prepare for extra charges at check-in.

7. Book API

• AllowDuplication
  • If guest name, email, and room type are identical and any dates of the period of stay overlap, system will consider the booking as duplicated.
  • True=> API will disregard booking duplication validation and allow to process booking
  • False=> API will check booking duplication and return error without creating booking (default)
  • We suggest partner build the logic in your system to capture& block the real duplicate booking and pass allowDuplication=true to us.
• Tag
  • The tag attribute can be partner’s reference number
  • English character and numbers ONLY (“_” and “-” are also ok)
  • Maximum length 50 characters
• The following values must be in-sync throughout the booking flow (Search / Precheck / Book APIs)
  1. Check In
  2. Check Out
  3. User Country
  4. Currency
  5. Language
  6. No. of rooms
  7. No. of Adults
  8. No. of Children
  9. Children's Ages (to be passed only when no. of children > 0)
  10. If any surcharge returned in the Search API, same must be passed in the Precheck & Book API as well

CLICK HERE to download the Book Now Pay Later (BNPL) Introduction.
See the image below for a preview of the Book Now Pay Later (BNPL) Introduction file:

8. Booking Confirmation Flow

Agoda highly recommends implementing the booking confirmation flow to minimize post-booking check-in issues.
After sending a booking request, wait up to 120 seconds (booking cutoff time). Agoda will try to reserve the allotment(s) and confirm the booking. Processing time varies due to several factors.

• When partners receive Agoda BookingID and itineraryID from BookAPI, the booking is considered confirmed.
• To get booking details or status, call our POST BOOKING API (BookingListAPI/BookingdetailsAPI).
• Wait at least 1 minute before calling POST BOOKING API after receiving a response from BOOKAPI, and implement a retry logic: at least 3 times in 15 minutes.

Some partners may want to include calling BookingListAPI/Bookingdetails API in their confirmation flow. Discuss this with your Agoda Technical Account Manager before going live.
This practice depends on the partner's system flow. Statistically, 90% of bookings are confirmed within a minute, and 98% within an hour. If confirmation is not received in an acceptable time frame, contact Agoda Customer Service to manually confirm the booking.

9. Multiple different room types

Agoda does NOT support booking multiple different room types (e.g., Room1 = Superior and Room2 = Deluxe). Only multiple rooms of the same type are supported.

10. BookingList API

BookingList API supports up to 1,000 booking IDs.

11. BookingDetail API

BookingDetail API supports up to 40 booking IDs. Set a wait time of 30 seconds with a minimum of 3 retries in case of timeout.

12. Cancel a booking

To cancel a booking, complete two steps:

• Cancellation API and Confirm_cancellation API. BookingID, Reference, and RefundRateInclusive must match to proceed.
• ConfirmCancellationAPI can proceed after receiving the cancellation response.

13. Child and Extra beds policy

Notify customers of any additional costs for extra beds and the age definition for children.

• If a child stays on existing bedding (free of charge), room benefits are not provided. Customers will pay additional charges directly to the hotel, e.g., for breakfast.

14. Special Request

There are two ways to submit special requests:

1. Include 'SpecialRequest' in Book API.
2. Submit separately via Special Request API, waiting 30 seconds after receiving the booking ID.

Certification Process

The certification process ensures your integration is fully prepared to serve customers on your live production servers. You must pass certification and receive approval from us before your application can go live and handle bookings.
Criteria:

• Hotel Database: Ensure hotels and room information are correctly mapped and regularly updated.
• Special Hotel Content: Display any hotel remarks clearly to users.
• Searching: Implement hotel list search properly and capture search results accurately.
• Booking: Calculate the total price correctly, and prominently display any excluded surcharges.
• Booking Status: Implement and handle the booking confirmation flow correctly.
• Cancellation: Implement the two-step cancellation process and ensure bookings can be successfully canceled.
• Reporting: Retrieve booking reports using the BookingList and BookingDetail APIs.
• Customer Voucher: Follow Agoda’s guidelines and format strictly, displaying key sentences such as:
  • "This booking is pre-paid and please refer to the Agoda booking ID upon check-in."
  • "This reservation is booked and payable by Agoda."

Agoda Self-Service Portal

We offer a self-service portal for partners to manage and modify their bookings online. Through this portal, you can update booking information, check booking status, and handle changes efficiently—all in one place.

If you would like access to the self-service portal, please contact your technical account manager directly. Our team will assist you with the onboarding process and answer any questions you may have.