General Information

there's some text here

Headers

#### Request Headers | Key | Value | Remarks | |---------------|---------------------------------|-----------------------------------------------------------------------------------------------------------| | Content-Type | application/json | All requests will be in JSON format. | | Authorisation | Username: Test ; Password: Test | Basic Authentication
Username and Password are given as examples - please provide stronger credentials | #### Response Headers | Key | Value | Remarks | |--------------|------------------|-------------------------------------------------------------------------------------------| | Content-Type | application/json | All responses should be in JSON format (except 4xx/5xx cases, where JSON is not required) |

Request Timeout Settings

You may choose to include a timeout, which may be set differently for each endpoint. However, please note the MAX_TIMEOUT value for each endpoint that must not be exceeded. Beyond the MAX_TIMEOUT value, our request will be deemed void, and any response received after the timeout duration will be discarded. The MAX_TIMEOUT duration on Agoda's end is calculated from the moment the request is sent by us. When deciding your timeout limits, please account for potential latency in the transmission of our request and your response. You should aim to return a response to us (and provide sufficient time for us to receive it) before the timeout limit is reached on our end. #### Timeout information | API | Recommended Timeout | Max Timeout | |-----------------------------------|---------------------|-------------| | Hotel Search / Availability Check | 30-55 seconds | None | | Allotment Check / Precheck | 30-55 seconds | 60 seconds | | Booking | 30-55 seconds | 60 seconds | | Cancel | 30-55 seconds | 60 seconds | | Booking Detail | 30-55 seconds | 60 seconds | | Booking IDs | 30-55 seconds | 60 seconds |

Response Status

This section describes and explains the appropriate response statuses and codes to return in specific scenarios. #### HTTP Return Code 200 Scenarios | Response Status (String) | Status Code | Remarks | |--------------------------|-------------|------------------------------------------------------------------------------------------------------------------------------------------| | SUCCESS | 200 | This should be returned by all successful responses. Please refer to footnote [1] below for the list of SUCCESS cases for each endpoint. | | NO_AVAILABILITY | 200 | For availability check: no available rooms for given criteria. Should return an empty list of hotels/rooms. | | NO_ALLOTMENT | 200 | For allotment check/Precheck: Given rate is no longer available for booking. | | BOOKING_FAIL | 200 | For hotel booking: cannot create booking. | | BOOKING_PENDING | 200 | For hotel booking: Booking request has been sent for a non-IsInstantConfirm room | | BOOKING_NOT_EXISTS | 200 | For hotel booking detail: booking does not exist | | CANCEL_FAIL | 200 | For booking cancellation: could not cancel booking | [1] Return a SUCCESS response when: - Availability check: Hotel is valid and rooms are available for the given search criteria. - Allotment check: The given room with rate plan that user is attempting to book is still available. - Hotel booking: Booking is confirmed. - Hotel booking detail: Booking exists for the given booking reference ID. - Booking cancellation: Booking is successfully cancelled. - Booking IDs: As long as HTTP return status code is 200, response status will be SUCCESS.
#### HTTP Return Code 4xx/5xx Scenarios | Response Status (String) | Status Code | Remarks | |---------------------------------|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | MALFORMED_REQUEST | 400 | Request sent has syntax error(s) | | UNAUTHORIZED | 401 | Access credential is incorrect | | BOOKING_TIMEOUT | 408 | For hotel booking: the booking request timed out. Return this status if suppliers want to retry the booking attempt. *Note: suppliers need to ensure booking deduplication has been implemented in order for retry to work correctly.* | | RATE_EXCEEDED | 429 | Requests sent have exceeded allowed QPS | | UNEXPECTED_ERROR | 500 | Any undefined error returned. Please provide additional details in the response | | UNSUPPORTED_COUNTRY_CODE | 501 | The country code(s) specified in the request is/are not supported | | SUPPLIER_SERVER_ERROR | 503 | Supplier service unavailable/server down - need to escalate to supplier |

Board Codes

The table below shows the possible board codes that can may be stored in the `boardCode` attribute in `PullSpecRate`. Each `boardCode` attribute should hold a single code, corresponding to a chosen code from the "Code" column. | Code | Description | Meals Included | |------|-----------------|-------------------------------------| | RO | Room Only | No Meals | | BB | Bed & Breakfast | Breakfast | | HB | Half Board | Breakfast, Dinner | | FB | Full Board | Breakfast, Lunch, Dinner | | AI | All Inclusive | Breakfast, Lunch, Dinner, Beverages |

Channels

| Channel Code | Channel Name | Description | |--------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------| | 1 | Retail | Unrestricted Rate | | 2 | Closed User Group | Shown to a select subset of Agoda users | | 6 | Domestic | Rates meant for domestic customers of the hotel (Fencing criteria: IP address of user is from same country as hotel) | | 7 | Mobile | Special rates only to be sold through mobile web/app | | 9 | China | Special rate for customers from China (Fencing criteria: IP address of user is in China) | | 21 | International | Rates meant for foreign customers of the hotel (Fencing criteria: IP address of user is from different country than hotel location) | | 23 | B2B | Special rates for B2B partners (may also be sold to Agoda users who are logged in) | | 35 | VIP | Extremely closed user group: shown to our most frequency travallers | | 3958 | Packages | Special Rates to be sold bundled with other inclusions |

Benefits

This section displays the possible benefit codes that may be inluded in the `benefits` list in the `PullSpecRate` object. | Code | Name | |------|---------------------------------------------------| | 166 | Day Use - 3 Hours Use Only | | 169 | Day Use - 6 Hours Use Only | | 173 | Day Use - 12 Hours Use Only | | 298 | Speed Boat Transfer (Both Ways) | | 299 | Speed Boat Transfer (One Way) | | 300 | Seaplane Transfer (Both Ways) | | 301 | Seaplane Transfer (One Way) | | 302 | Domestic Flight & Speed Boat Transfer (Both Ways) | | 303 | Domestic Flight & Speed Boat Transfer (One Way) | | 323 | Couple Friendly | | 324 | Local ID Accepted |

Booking Status

This table describes possible values that may exist in the `bookingStatus` field inside a `PullSpecBookingId` object or a `PullSpecBookingDetailResponse` object. | Status | Description | |-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | BookingPending | Booking was made but has not been confirmed. Booking will be BookingPending confirmed within {x} minutes (Note: this status is valid only for non-isInstantConfirm bookings). | | Confirmed | Booking was confirmed. (Earlier PullSpec versions use status "Booked", which has been deprecated in favour of "Confirmed". "Booked" remains supported, but suppliers implementing current or later versions should use "Confirmed") | | Failed | Booking attempt failed. | | Cancelled | Booking was cancelled |

Backward Compatibility

(this may need to be removed) Supplier implementation should be able to ignore additional fields in the request. This will allow supplier's current implementation to stay compatible with newer versions of the specification.

General Implementation Information

Please ensure that the following have been adhered to in your implementation: 1. Is the protocol going to be HTTPS? Agoda requires HTTPS in production to live the integration. 2. What is the basic authentication credential for Agoda to authenticate the API? 3. If there is content encoding for response, is the encoding GZIP? 4. Are the APIs following the API endpoint convention? This will speed up the integration process on both sides. 5. Is the version in the response body consistent with the version in URL? 6. Are there any hotel IDs with available rooms for Agoda to test the implementations? 7. Are the response data types correct? For example: - Channel and allotment in the search response should be integer instead of String - Price should be double instead of String - hotel code, room code, and rate plan code should be String instead of Integer 8. Is the price returned in the search response and precheck response total price? 9. Is booking deduplication implemented? 10. Does cancelling an already cancelled booking return success? In addition, we expect that your implementation should be able to ignore additional fields in the request. This will allow your current implementation to stay compatible with newer versions of the specification.

Cancellation Policy (PullSpecCancellationPolicy) structure

The table below shows various scenarios and examples on how to specify cancellation policies as a PullSpecCancellationPolicy object. All scenarios and examples below assume a room price of $200. `amount` must specify the absolute amount to be charged if the booking is cancelled under that specified cancellation policy. It should not store a percentage value - percentages are provided in the examples below for clarity only. `daysBeforeCheckIn` refers to the number of calendar days before the check-in date when the specified cancellation policy starts taking effect. A calendar day refers to 00:00H to 23:59H of a single day, thus a day begins at 00:00:00H in the hotel's local timezone, and ends at 23:59:59H. `daysBeforeCheckIn` is always calculated based on the hotel's local timezone, and by number of calendar days from the check-in date, not by 24-hour blocks - check-in time is not considered when calculating `daysBeforeCheckIn`. An example is given below, with the check-in date being 31 Dec 2023. | daysBeforeCheckIn | Date | Cancellation Policy Active from (in hotel's local timezone) | |-------------------|-------------------------------|-------------------------------------------------------------| | 0 | 31 Dec 2023 (day of check-in) | 100% Penalty in all cases (no-show) | | 1 | 30 Dec 2023 | 30 Dec 2023 00:00H | | 2 | 29 Dec 2023 | 29 Dec 2023 00:00H | | 3 | 28 Dec 2023 | 28 Dec 2023 00:00H | **IMPORTANT!** There is always an implicit rule that cancellation on the day of check-in, and no-shows, will be charged 100% of the booking price. Similarly, there is an implicit rule that for any day prior to the largest `daysBeforeCheckIn` value specified in any of the cancellation policies, cancellation will be free (e.g if the check-in date is 31 Dec 2023, and the largest value of daysBeforeCheckIn is 4, then any cancellation on 26 Dec 2023 or earlier will be free). These rules apply regardless of the cancellation policies specified, and cannot be overridden. **Never set `amount` to 0.** #### Partially Refundable from (x) days before check-in In this example, (x) = 1. Cancellation Code: `1D20P_100P` cancellationPolicy: ```json { "cancellationPolicy": { "policies": [ { "amount": 40.00, "daysBeforeCheckIn": 1 } ] } } ``` Description: - Free cancellation if cancelled more than 1 day before check-in date - Pay $40 (i.e. 20% of the room price) if cancelled 1 day or less before check-in date - Pay full amount ($200, i.e. 100% of room price) if cancelled on/after check-in date #### Partial Refund Only This example demonstrates a case where a partial refund policy will apply from the moment the booking is made, regardless of how many days before check-in the customer makes the booking. This is intended to cover cases where no free cancellation will be provided at any time once the rate is available for booking. Agoda only supports booking start (check-in) dates up to 365 days in advance (end dates may be more than 365 days in the future, but for the purposes of calculating cancellation policy start dates this does not matter), so using a `daysBeforeCheckIn` value of 365 or greater will result in the specified cancellation policy being active from the moment the rate becomes bookable by customers. Cancellation Code: `365D50P_100P` cancellationPolicy: ```json { "cancellationPolicy": { "policies": [ { "amount": 100.00, "daysBeforeCheckIn": 365 } ] } } ``` Description: - Pay $100 (i.e. 50% of the room price) if cancelled 365 days or less before check-in date. However, because Agoda only supports booking up to 365 days in advance, this effectively becomes a partial-refund-only cancellation policy that comes into effect immediately after it is booked, regardless of when the booking is made. This becomes equivalent to paying $100 (50% of room price) if cancelled at any time after booking. Any `daysBeforeCheckIn` value of 365 or larger will work. - Pay full amount ($200, i.e. 100%) of room price if cancelled on/after check-in date. #### Fully Refundable until check-in Cancellation Code: `0D100P_100P` cancellationPolicy: ```json { "cancellationPolicy": { "policies": [ { "amount": 200.00, "daysBeforeCheckIn": 0 } ] } } ``` Description: - Free cancellation if cancelled any time before midnight (00:00 in the hotel's local time) of the check-in date. - Pay full amount ($200, i.e. 100%) if cancelled on day of check-in. #### Fully refundable until (x) days before check-in In this example, (x) is 2 - that is, this cancellation policy becomes active within 2 days of check-in. Cancellation Code: `2D100P_100P` cancellationPolicy: ```json { "cancellationPolicy": { "policies": [ { "amount": 200.00, "daysBeforeCheckIn": 2 } ] } } ``` Description: - Free cancellation if cancelled more than 2 days before check-in - Pay full amount ($200, i.e. 100%) if cancelled 2 days or less from check-in date. #### Multi-level cancellation policies In general, each object within the `policies` list is considered one level. You can add more levels to the cancellation policy by simply adding more objects to the `policies` list. The cancellation policy with the smallest `daysBeforeCheckIn` value that is active on the calendar day when the booking is cancelled will be used. As an example: Cancellation Code: `4D20P_2D50P_100P` ```json { "cancellationPolicy": { "policies": [ { "amount": 40.00, "daysBeforeCheckIn": 4 }, { "amount": 100.00, "daysBeforeCheckIn": 2 } ] } } ``` Description: - Free cancellation if cancelled more than 4 days before check-in. - Pay $40 (i.e. 20% of room price) if cancelled 4 days or less before check-in date. - Pay $100 (i.e. 50% of room price) if cancelled 2 days or less before check-in date. - Pay $200 (i.e. 100% of room price) if cancelled on the day of check-in. [//]: # (comment: saving the section below for the day when PullSpec supports >2 levels of cancellation policies :D) [//]: # (A more complex example may look like this:) [//]: # () [//]: # (```json) [//]: # ({) [//]: # ( "cancellationPolicy": {) [//]: # ( "policies": [) [//]: # ( {) [//]: # ( "amount": 20.00,) [//]: # ( "daysBeforeCheckIn": 365) [//]: # ( },) [//]: # ( {) [//]: # ( "amount": 40.00,) [//]: # ( "daysBeforeCheckIn": 30) [//]: # ( },) [//]: # ( {) [//]: # ( "amount": 100.00,) [//]: # ( "daysBeforeCheckIn": 7) [//]: # ( },) [//]: # ( {) [//]: # ( "amount": 180.00,) [//]: # ( "daysBeforeCheckIn": 2) [//]: # ( }) [//]: # ( ]) [//]: # ( }) [//]: # (}) [//]: # (```) [//]: # () [//]: # (Description:) [//]: # (- Pay $20 (i.e. 10% of room price) if cancelled at any time after booking.) [//]: # (- Pay $40 (i.e. 20% of room price) if cancelled 30 days or less before check-in date.) [//]: # (- Pay $100 (i.e. 50% of room price) if cancelled 7 days or less before check-in date.) [//]: # (- Pay $180 (i.e. 90% of room price) if cancelled 2 days or less before check-in date.) [//]: # (- Pay full room price ($200) if cancelled on day of check-in.) #### Always non-refundable Cancellation Code: `365P100P_100P` cancellationPolicy: (choose one of the below - there is no preference towards either) ```json { "cancellationPolicy": { "policies": [] } } ``` OR ```json { "cancellationPolicy": null } ``` Description: - Pay full amount ($200, i.e. 100% of room price) if cancelled at any time after booking. #### Understanding Cancellation Codes (do we need this section)

200Success

400Malformed Request - Request sent has syntax error.

401Unauthorised - Access credential is incorrect.

408For hotel booking: booking request time out. Return this status if suppliers want booking retry. Note: suppliers need to ensure booking deduplication has been implemented in order for the retry to work correctly.

429Rate Exceeded - Requests sent have exceed allowed QPS.

500Unexpected Error Code - Any undefined error returned. Need to provide more details in response

501Unsupported Country Code - The country codes specified in the request is not supported.

503Supplier Server Error - Supplier service unavailable/server down. Need to escalate to supplier