Overview

Agoda provides two retrieval methods — use these APIs to retrieve booking information for reporting, customer service, and operational visibility. Choose the right API based on your use case.

1.Booking List API

Best for: Syncing & Monitoring

Filter by Time Range: Retrieve bookings within a specific time window (max 24 hours per request; up to 1000 bookings will be returned in each response. ).
Filter by Tags: Look up bookings using your own reference IDs (up to 1,000 tags per request).

2. Booking Detail API

Best for: Full Data & Policies

Lookup by Booking ID: Retrieve full booking details (policies, amendments details, HCN, etc.) for specific Agoda Booking IDs (up to 40 bookingIds per request).

Use cases: When to use which?

Goal	Recommended API
Sync Latest Status (Poll for new/updated bookings)	Booking List (`dateTimeRange`) ⬇ Booking Detail (for full payload)
Find bookings by your reference ID (Find by your Ref ID)	Booking List (`tags`)
Fetch full booking details (booking policies, hotel confirmation number, and whether the booking is eligible for amendments or fee waivers)	Booking Detail (`bookingIds`)

💡 Pro Tip: For system syncing, always use the dateTimeRange filter. Avoid using tags for general synchronization.

Best Practices

Booking Syncing — Suggested Flow

Use the Booking List API for regular synchronization. Partners typically implement scheduled polling and maintain a sync watermark (e.g., last successful sync time) to avoid missing updates.

Recommended schedule

Run a scheduled sync (partners can choose job frequency based on production needs). Note that up to 1,000 bookings will be returned per request in the Booking list API.

Suggested implementation

Store a sync watermark (e.g., last_synced_at)
Call Booking List API with modified_since = last_synced_at - 5 minutes (overlap handles clock drift)
update results into your database (idempotent handling)
Call Booking detail API to enrich full booking information
Advance the watermark only after successful processing
Repeat on a schedule

flowchart TD
    Start([Start Sync]) --> GetWatermark[1. Get last_synced_at]
    GetWatermark --> ListAPI[2. Call Booking List API]
    
    ListAPI -->|Error| RetryList{Timeout/Retryable errors?}
    RetryList -->|Yes| ListAPI
    RetryList -->|No| Alert([Log Error & Escalate via Ticketing])
    
    ListAPI -->|Success| HasBookings{Bookings found?}
    HasBookings -->|No| UpdateWatermark
    HasBookings -->|Yes| DetailAPI[3. Call Booking Detail API - batch of 40 IDs]
    
    DetailAPI -->|Error| RetryDetail{Timeout/Retryable errors?}
    RetryDetail -->|Yes| DetailAPI
    RetryDetail -->|No| Alert
    
    DetailAPI -->|Success| Process[4. Process & Store]
    
    Process --> MoreBatches{More batches?}
    MoreBatches -->|Yes| DetailAPI
    MoreBatches -->|No| UpdateWatermark[5. Update last_synced_at]
    
    UpdateWatermark --> End([End Sync])
    
    style Start fill:#e3f2fd,stroke:#1565c0
    style End fill:#c8e6c9,stroke:#2e7d32
    style Alert fill:#ffcdd2,stroke:#c62828

Notes:

A "retryable" error is a transient server or network failure that can be retried (after rechecking the booking status), while a "non-retryable" error is a permanent client-side or business error. For more details about retryable error codes, please refer to the **Appendix ** section

Fetching Hotel Confirmation Number — Suggested Flow

The Booking Detail API provides the hotel confirmation number (HCN) assigned by the hotel. However, not all bookings have an HCN immediately available. Use a daily retry strategy until the check-in day cut-off to maximize the chance of obtaining the HCN.

⚠️ Important Notes

HCN vs supplierReference: The hotelConfirmationNumber is the unique confirmation number assigned by the hotel. The supplierReference is provided by the supplier and may not match the hotel's own confirmation number.
Not all bookings have HCN: Most bookings will have an HCN, but for some (such as those routed through certain suppliers), the HCN may not be available. If HCN is missing after cut-off time, use supplierReference if available. If neither HCN nor supplierReference is available, use the Booking ID as fallback.
Cut-off time: Continue polling for the HCN until 23:59:59 (hotel local time) on the check-in date

Suggested Implementation

Wait 1 minute after receiving the booking before the first API call (allows time for HCN processed)
Call Booking Detail API with the Booking ID
Check if hotelConfirmationNumber is available in the response
If HCN exists: Return it to the partner/guest
If HCN missing & before 23:59:59 checkin time (hotel local time): Retry
If API fails : Retry for 30mins. If all retries fail within 30 minutes, escalate to your Technical Account Manager
If HCN still missing after cut-off: Return supplierReference (if any) -> Booking ID as fallback

flowchart TD
    Start([Booking Confirmed]) --> Wait1Min[Wait 1 minute before first call]
    Wait1Min --> CallAPI[Call Booking Detail API with Booking ID]
    CallAPI --> Response{API Success?}
    
    Response -->|No| RetryAPI{Timeout/Retryable errors?}
    RetryAPI -->|Yes| CallAPI
    RetryAPI -->|No| Escalate([Log Error & Escalate via Ticketing])
    
    Response -->|Success| CheckHCN{HCN Available?}
    CheckHCN -->|Yes| Success([Return HCN])
    CheckHCN -->|No| CheckCutoff{Before 23:59:59 on Check-in Date?}
    CheckCutoff -->|Yes| WaitRetry[Schedule Retry every 6-12 hours]
    WaitRetry --> CallAPI
    CheckCutoff -->|No| Fallback([Return supplierReference as Booking ID])

    style Start fill:#e3f2fd,stroke:#1565c0
    style Success fill:#c8e6c9,stroke:#2e7d32
    style Fallback fill:#fff9c4,stroke:#f57f17
    style Escalate fill:#ffcdd2,stroke:#c62828
    style WaitRetry fill:#fff9c4,stroke:#f57f17
    style CheckCutoff fill:#f3e5f5,stroke:#7b1fa2

Notes:

A "retryable" error is a transient server or network failure that can be retried (after rechecking the booking status), while a "non-retryable" error is a permanent client-side or business error. For more details about retryable error codes, please refer to the **Appendix ** section

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).
The Booking List API results can return a maximum of up to 1000 bookings per response. You can use the optional cursor-based pagination through the pageInfo object to retrieve more results.
Refer to the sample request and response below.

Booking List API - by DateTime request example

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

Booking List API - by Tags request example


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

Booking List API - with Pagination

The Booking List API supports optional cursor-based pagination through the pageInfo object on the request and response.

📘
Note: This is an opt-in feature that is only available if enabled. Contact your Account Manager if you wish to enable pagination support.

First page

{
  "dateTimeRange": {
    "from": "2026-01-01T00:00:00",
    "to": "2026-02-01T00:00:00"
  },
  "pageInfo": {
    "limit": 500
  }
}

Note: For paginated results, you should use the same dateTimeRange / tags across all pages in a dataset (the same criteria specified on the first page request should apply to subsequent page calls).

{
  "dateTimeRange": {
    "from": "2026-01-01T00:00:00",
    "to": "2026-02-01T00:00:00"
  },
  "pageInfo": {
    "token": "pageInfo.token_value_from_previous_call_response",
    "limit": 500
  }
}

Parameters for Booking List Request Schema (* = Require)

Element	Attribute	Description
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 1000 tags.
BookingListRequestV4 > pageInfo	token string	Cursor for the next page. This indicates the start after the last booking record from the previous call. You may omit when calling the first page or when pagination is not used.
	limit integer	Maximum number of bookings to return per page. The maximum allowed is 1000 (higher numbers specified will be capped at 1000). Defaults to 1000 if omitted.

BookingList API - Response example (with optional pagination info)

{
  "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"
    }
  ],
  "pageInfo": {
    "token": "eftHkaqv..."
  }
}

Parameters for BookingList Response Schema (* = Require)

Element	Attribute	Description
Element	Attribute	Description
BookingListResponseV4 -> bookings	id* Long	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.
pageInfo	token String	Next-page cursor. Empty pageInfo indicates end of data/pages. Present only when pagination is enabled for the partner. Note that a token is onlyvalid for 24 hours and expires after.

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