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?

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

Best Practices

Booking Syncing — Suggested Flow

Overview

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

1. Store a sync watermark (e.g., last_synced_at)
2. Call Booking List API with modified_since = last_synced_at - 5 minutes (overlap handles clock drift)
3. update results into your database (idempotent handling)
4. Call Booking detail API to enrich full booking information
5. Advance the watermark only after successful processing
6. 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

Overview

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

1. Wait 1 minute after receiving the booking before the first API call (allows time for HCN processed)
2. Call Booking Detail API with the Booking ID
3. Check if hotelConfirmationNumber is available in the response
4. If HCN exists: Return it to the partner/guest
5. If HCN missing & before 23:59:59 checkin time (hotel local time): Retry
6. If API fails : Retry for 30mins. If all retries fail within 30 minutes, escalate to your Technical Account Manager
7. 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). Check out the sample request and response below.

Book List API - By DataTime Request Example

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

Book List API - By Tags Request Example

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

Parameters for Booking List Request Schema (* = Require)

BookingList API - Response Example by datetime or tags

{
  "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"
    }
  ]
}

Parameters for BookingList Response Schema (* = Require)

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)

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.

Booking Detail API - Request Example

{
    "bookingIds": [
        80000040
    ]
}

Parameters for Booking Detail Request Schema (* = Require)

BookingDetail API - Response Example (Correct case)

{
  "bookings": [
    {
      "bookingId": 80000040,
      "tag": "12345667",
      "status": "BookingCharged",
      "checkIn": "2021-12-01",
      "checkOut": "2021-12-02",
      "naturalDisaster": false,
      "property": {
        "propertyName": "Kurumba Maldives",
        "country": "Maldives",
        "city": "Maldives Islands",
        "addressLine1": "Avenue Connaught Place, City Center New Delhi 110001",
        "addressLine2": ""
      },
      "amendments": [
        {
          "amendmentId": "12318131",
          "amendmendType": "DateAmendment",
          "amendmentStatus": "Confirmed",
          "amendmentDate": "2024-07-26T07:43:20.786Z"
        }
      ],
      "amendmentFeatures": [
        "DateAmendment",
        "GuestInfoAmendment",
        "SpecialRequest"
      ],
      "room": {
        "roomType": "Beachfront Deluxe Bungalows",
        "roomsBooked": 1,
        "ratePlan": "Retail",
        "rateType": "Sell"
      },
      "totalRates": [
        {
          "currency": "USD",
          "exclusive": 448.90,
          "inclusive": 551.65,
          "tax": 66.33,
          "fees": 36.42
        }
      ],
      "taxSurchargeInfo": "Included : Taxes and fees USD 87.36",
      "payment": {
        "rates": [
          {
            "currency": "USD",
            "inclusive": 551.65
          }
        ]
      },
      "agodaPromotion": false,
      "source": "Hotel",
      "supplierReference": "1",
      "cancellationPolicy": "Any cancellation received within 3 days prior to arrival date will incur the full period charge. Failure to arrive at your hotel or property will be treated as a No-Show and no refund will be given (Property policy).",
      "howToGetThere": "",
      "specialRequest": "High floor",
      "occupancy": {
        "numberOfAdults": 2,
        "numberOfChildren": 0
      },
      "isFeeWaiverAllowed": true,
      "feeWaiverStatus": "Pending",
      "bookingDate": "2024-11-26T05:42:33.000+07:00",
      "hotelConfirmationNumber": "R5180672169926001"
    }
  ]
}

Parameters for Booking Detail Response Schema (Correct case) (* = Require)

BookingDetail API - Response Example (Error case)

{
    "errorMessage": {
        "id": "909",
        "message": "Internal Error"
    }
}

Parameters for Booking Detail Response Schema (Error case) (* = Require)