Guides
English
Guides
  1. Documentation
  2. Search API 2.0

API reference

Request fields

📘

Offer context is required in the Search request and only one of the liveOffersContext or allOffersContext must be present in a single API call.

Element Attribute Required Field Description
criteria* propertyIds*
Array[Integer]		 Required Property identifiers to retrieve availability for. Typically one or more Agoda property IDs. Supports maximum 100 hotels per request. Please refer to maxOffersPerContext for details.
checkInDate*
Date		 Required Guest check-in date as a calendar date (yyyy-MM-dd), interpreted in UTC. Bookings are supported only up to 365 days in advance from the current date.
checkOutDate*
Date		 Required Guest check-out date as a calendar date (yyyy-MM-dd), interpreted in UTC. Must be after checkInDate.
locale*
String		 Required BCP 47-style locale (e.g. en-us, th-th) for language and regional formatting of names, policies, and other localized content in the response.
criteria.occupancy* roomCount*
Integer		 Required Number of rooms requested for this search.
adultCount*
Integer		 Required Total number of adults across the stay.
childrenAges
Array[Integer]		 Required Age of each child in years, in order; use an empty list when there are no children. Min value 0 and max value 17.
criteria.currency* booking*
String		 Required ISO currency code used for booking and settlement amounts.
display
String		 Optional Optional ISO currency code for displaying prices to the end user. If omitted, display follows booking currency.
Note: Upcoming feature
features maxOffersPerContext*
Integer		 Required

Number of best offers available for a property.

Number of hotels maxOffersPerContext
For single hotel search1–100 (max)
2–30 HIDs in one search1–25 (max)
31–100 HIDs in one search1 (max)
extra
Array[String]		 Optional

Optional parameters can be added to request additional details in the search response. Refer to the extra parameters section to learn more. If you are a partner using the fulfillment model, do not include META_SEARCH as it is not designed for this mode.

enum [

HOTEL_CONTENT, ROOM_CONTENT, RATE_DETAIL, SURCHARGE_DETAIL, DAILY_RATE, BENEFIT_DETAIL, CANCELLATION_DETAIL, PROMOTION_DETAIL, TAX_DETAIL, CROSSEDOUT_DETAIL, PER_*_RATE, META_SEARCH]

Accepts any of the following values for PER_*_RATE (this extra parameter returns the `perBasis` detail in response): PER_ROOM_PER_NIGHT_RATE, PER_BOOK_RATE, PER_NIGHT_RATE, PER_ROOM_RATE
liveOffersContext (only applicable to live offers search) Object Optional
(with condition)		 An object that contains two sub-objects, userContext and saleContext, to represent the search criteria when a partner requests offers in Live Offers mode.

Either allOffersContext or liveOffersContext must be present in the request, but not both. If both fields are provided, or if neither is included, the system should return a descriptive error.
liveOffersContext.userContext* channel*
Enum		 Required

Enum values: MOBILE_WEB, DESKTOP_WEB, MOBILE_APP

A string enum used by the partner to specify the channels or platforms for which they want to request offers. Single value supported.

The value provided by the partner for this field must be selected from the list of supported values (enum). If an invalid value is submitted—including incorrect case sensitivity—the system should return an error specifying which value is not allowed. This field must always be present, and empty string is not supported.
userGroup*
Enum		 Required

Enum values: LOGGED_OUT, LOGGED_IN, PREMIUM, CROSS_SELL

A string enum by the partner to specify the user group for which they want to request offers.

The value provided by the partner for this field must be selected from the list of supported values (shown). If an invalid value is submitted—including incorrect case sensitivity—the system should return an error specifying which value is not allowed. This field must always be present, and empty string is not supported.
userCountry*
String		 Required A string indicating the end-user country for which the partner wants to retrieve offers. A string indicating countries in ISO2 format. We will support only one user country. In case multiple userCountries are requested, the request will fail.
liveOffersContext.saleContext* packageType*
Enum		 Required

Enum values: PACKAGED, NON_PACKAGED

A string enum by the partner to specify whether they want offers for packaged sales, non-packaged sales, or offers that support both.

The value provided by the partner for this field must be selected from the list of supported values. If an invalid value is submitted—including incorrect case sensitivity—the system should return an error specifying which value is not allowed. This field must always be present, and empty string is not supported.
distributionType*
Enum		 Required

Enum values: DIRECT, FORWARD

A string enum used by the partner to specify whether they want offers for direct sales, forward sales, or both.

The value provided by the partner for this field must be selected from the list of supported values. If an invalid value is submitted—including incorrect case sensitivity—the system should return an error specifying which value is not allowed. This field must always be present, and empty string is not supported.
forwardDistributionPartner
Enum		 Optional

Enum values: GOOGLE, NAVER, ANY

A string enum used by the partner to specify whether they want offers that can be distributed anywhere, or are tied to a specific forward-distribution partner.

Multiple values or delimited inputs are not supported.

If distributionType = FORWARD and this field is not provided, the default value is ANY.

If distributionType = DIRECT and this field is included, the request will return an error indicating that forwardDistributionPartner is not allowed when distributionType is DIRECT.
adType
Enum		 Optional

Enum values: STANDARD, STRATEGIC

A string enum used by the partner to indicate the advertisement type. Defaults to STANDARD.
allOffersContext (only applicable to all offers search) Object Optional
(with condition)		 An object that contains sub-object userContext to represent the search criteria when a partner requests offers in All Offers mode.

Either allOffersContext or liveOffersContext must be present in the request, but not both. If both fields are provided, or if neither is included, the system should return a descriptive error.
allOffersContext.userContext* userCountries*
Array[String]		 Required An array of UPPERCASE strings indicating the end-user countries for which the partner wants to retrieve offers. An array of strings indicating countries in ISO2 format. For now, this array supports only a single value. If more than one value is provided, the request should fail with an error.

For MSE we support up to 5 countries.

Response schema

📘

Booking path:In your book requests, you need to pass each selected rate's id and token from Search through Precheck and Book (replacing the legacy blockId / separate offer token flow).

  • * = Required field
Element Attribute Required Description
meta Object Required Contains additional metadata for partners.
status*
String		 Required Outcome of the search operation for this response. Possible values: SUCCESS, FAILURE.
unavailable*
Array[Integer]		 Required Property IDs that were requested but are unavailable.
data Object Required Contains actual data with properties and offer details.
searchId*
Long		 Required The unique ID that this search received in our system.
properties*
Array[Object]		 Required Properties with rooms and offers.
definitions*
Object		 Required Meta data information inside definitions so that we don't need to repeat this information in all offers. The list will be union of all offers.
data.properties id*
Integer		 Required Agoda's hotel ID.
content
Object		 Optional Hotel level content information.
additionalInfo*
Object		 Required AdditionalInfo about property.
currencies*
Object		 Required

Contains currencies for booking, display and property.

  • booking — Currency used for booking/charge amounts (need to provide same details at the time of booking request).
  • display — Currency used for partner-facing display amounts where relevant.
  • property — Property local / settlement currency for amounts that are quoted or settled in local currency (like for payAtHotel and excluded surcharges).

Details are on Currency Part (Appendix). Note: display and property currency support will be provided in upcoming features.
rooms*
Array[Object]		 Required Array of unique room types for this property. Each room can have multiple offers.
data.properties.additionalInfo chainId
Integer		 Optional Chain for the property. Only enabled for Interco today.
data.properties.content name
Object		 Optional

Hotel name in english and in requested locale (translated) as an addition key.

This field can only be returned when sending HOTEL_CONTENT in features.extra.

Eg — {"en-us":"The Berkeley Hotel Pratunam","th-th":"โรงแรมเดอะเบิร์กลีย์ พระตมำ"}
data.properties.currencies display*
String		 Required Currency used for partner-facing display amounts wherever relevant. Note: Upcoming feature.
booking*
String		 Required Currency used for booking/charge amounts.
property*
String		 Required Property local / settlement currency for amounts that are quoted or settled in local currency. Note: Upcoming feature.
data.properties.rooms id*
Long		 Required The ID of the room type.
parentId*
Long		 Required The ID of the parent room type.
content
Object		 Optional Room level content information.
offers*
Array[Object]		 Required Array of bookable room offers for this room type.
data.properties.rooms.content name
Object		 Optional

Room name in english and in requested locale (translated) as an addition key.

This field can only be returned when sending ROOM_CONTENT in features.extra.

Eg — {"en-us":"Luxury (Main Tower)","th-th":"ห้องหรู (Main Tower)"}
data.properties.rooms.offers id*
String (max 500 bytes)		 Required New unique identifier for each room, provide as a unique key for partner's caching. Please use this one instead of blockIdBackup. Possible characters: A–Z, a–z, 0–9, +, /, _, =, -
token*
String		 Required It carries fence-specific information needed to process the offer.
landingUrl
String		 Optional The landing page URL that you use if the customer clicks through. This field can only be returned when sending META_SEARCH in features.extra.
remainingRoomCount
Integer		 Optional The rooms (allotment) remaining under the same Room ID. This field can only be returned when sending RATE_DETAIL in features.extra.
isRoomTypeGuaranteed
Boolean		 Optional true when the booked room category is guaranteed; false indicates run-of-house or non-guaranteed mapping. This field can only be returned when sending RATE_DETAIL in features.extra.
capacity*
Object		 Required Occupancy for this offer after free-child/infant handling. This field can only be returned when sending RATE_DETAIL in features.extra.
payment*
Object		 Required Payment and collection model for this offer.
ratePlan*
Object		 Required Rate-plan content.
pricing*
Object		 Required Multi-currency, multi-basis pricing container.
policies*
Object		 Required Cancellation and related policy objects for this offer.
benefits
Object		 Optional Benefits provided in the offer. Like free wifi, free breakfast, etc. This field can only be returned when sending BENEFIT_DETAIL in features.extra.
additionalInfo*
Object		 Required Contains fields enabled for specific partners. Contact technical team to get this column.
offerContext*
Object		 Required Parent Objects hold information of the segment that each offer can be exposed to.
data.properties.rooms.offers.capacity normalBedCount
Integer		 Optional It is the effective standard occupancy when mandatory extra beds are treated separately. This field can only be returned when sending RATE_DETAIL in features.extra.
extraBedCount
Integer		 Optional Number of extra beds. This field can only be returned when sending RATE_DETAIL in features.extra.
data.properties.rooms.offers.payment model
String		 Optional

Possible values: AGENCY (booking will be charged at hotel), MERCHANT (pre-paid), MERCHANT_COMMISSION (pre-paid).

This field can only be returned when sending RATE_DETAIL in features.extra.
isPayAtProperty
Boolean		 Optional True if pay at hotel is available for this booking in this room. This field can only be returned when sending META_SEARCH in features.extra.
isBookWithoutCreditCard
Boolean		 Optional true when booking is allowed without a credit card per policy.
bookNowPayLaterDateTime
DateTime		 Optional Later date by which the payment is to be made in book-now-pay-later (BNPL). Datetime with timezone.
data.properties.rooms.offers.ratePlan id*
Long		 Required Used to identify the Agoda rate plan.
name
Object
(Not applicable for all partners.)		 Optional Name of the special rate plan. Rate plan name in english and in requested locale (translated) as an addition key. Eg — {"en-us":"RC Name"}
description
Object
(Not applicable for all partners.)		 Optional Description of the special rate plan, max character length is 2000. Rate plan description in english and in requested locale (translated) as an addition key. Eg — {"en-us":"RC Desc"}
inclusions
String
(Not applicable for all partners.)		 Optional Inclusions that are applicable for the special rate plan, max character length is 2000.
exclusions
String
(Not applicable for all partners.)		 Optional Exclusions that are applicable for the special rate plan, max character length is 2000.
checkInTime
Object
(Not applicable for all partners.)		 Optional Check-In time at hotel that are applicable for the special rate plan.
checkoutTime
Object
(Not applicable for all partners.)		 Optional Check-out time at hotel that are applicable for the special rate plan.
data.properties.rooms.offers.ratePlan.checkInTime
(Not applicable for all partners.)		 startTime
String		 Optional Start time of check-in for the special rate channel. Returned only if applicable.
endTime
String		 Optional End time of check-in for the special rate channel. Returned only if applicable.
data.properties.rooms.offers.ratePlan.checkoutTime
(Not applicable for all partners.)		 startTime
String		 Optional Start time of check-out for the special rate channel. Returned only if applicable.
endTime
String		 Optional End time of check-out for the special rate channel. Returned only if applicable.
data.properties.rooms.offers.pricing bookingRates*
Array[Object]		 Required Array of bookable price rows, typically one per requested/chargeable currency.
display*
Object		 Required Partner-facing display pricing.
data.properties.rooms.offers.pricing.bookingRates currency*
String		 Required Booking currency.
price*
PriceWithSTRAndMSPObject		 Required

All prices in this object per book (PB). Mostly the same fields as in PriceObject. It also contains strikeThroughRate and minSellRate details.

  • price.inclusiveAmount — Total inclusive amount for the basis (room + tax + fees + mandatory surcharges).
  • price.exclusiveAmount — Exclusive amount per basis, excluding taxes but includes room charge and mandatory surcharges.
  • price.tax — Tax breakdown per basis.
  • price.fees — Fees breakdown per basis.
surcharge
Object		 Optional All surcharges in this object.
partnerPricing*
Object		 Required Partner-specific commercial and interco financial fields.
data.properties.rooms.offers.pricing.bookingRates.surcharge included*
Array[SurchargeObject]		 Required

Surcharges included in booking per book (mandatory surcharges). Mandatory surcharges will be charged in addition to room price at time of booking creation.

  • included.price.inclusiveAmount — Surcharge inclusive amount per book.
  • included.price.exclusiveAmount — Surcharge exclusive amount per book.
  • included.price.tax — Surcharge tax breakdown per book.
  • included.price.fees — Surcharge fees breakdown per book.
data.properties.rooms.offers.pricing.display sellAllInRates*
Array[Object]		 Required All-in display rows (PER_BOOK): base + tax + fees + both included and excluded surcharges for full "all-in" display.
perBasis*
Array[Object]		 Required Display rates by basis as per partner contract (e.g. PER_BOOK (PB), PER_ROOM_PER_NIGHT (PRPN), PER_ROOM (PR), PER_NIGHT (PN)).
dailyRates
Array[Object]		 Optional Per-night display rates (always PER_NIGHT (PN)).
data.properties.rooms.offers.pricing.display.sellAllInRates currency*
String		 Required Display currency.
price*
PriceWithSTRAndMSPObject		 Required

All prices in this object PER_BOOK basis. Mostly the same fields as in PriceObject. It also contains strikeThroughRate but does not contain minSellRate.

  • price.inclusiveAmount — Total inclusive amount for the basis (room + tax + fees + inclusive/mandatory surcharges + excluded surcharges).
  • price.exclusiveAmount — Exclusive amount per basis, excluding taxes but includes room charge and mandatory surcharges.
  • price.tax — Tax breakdown per basis.
  • price.fees — Fees breakdown per basis.
promotions
Array[PromotionsObject]		 Optional Promotion applicable at display rate.
surcharge
Object		 Optional All surcharges in this object (as PER_BOOK basis). Includes both included (mandatory) and excluded surcharges.
partnerPricing*
Object		 Required Partner-specific commercial and interco financial fields.
data.properties.rooms.offers.pricing.display.sellAllInRates.surcharge included*
Array[SurchargeObject]		 Required

Included surcharges in booking PER_BOOK basis (mandatory surcharges). Mandatory surcharges will be charged in addition to room price at time of booking creation.

  • included.price.inclusiveAmount — Surcharge inclusive amount PER_BOOK basis.
  • included.price.exclusiveAmount — Surcharge exclusive amount PER_BOOK basis.
  • included.price.tax — Surcharge tax breakdown PER_BOOK basis.
  • included.price.fees — Surcharge fees breakdown PER_BOOK basis.
excluded*
Array[SurchargeObject]		 Required

Excluded surcharges in booking PER_BOOK basis (excluded surcharges). Excluded surcharges will be charged at the time of property visit in property currency.

  • excluded.price.inclusiveAmount — Surcharge inclusive amount PER_BOOK basis.
  • excluded.price.exclusiveAmount — Surcharge exclusive amount PER_BOOK basis.
  • excluded.price.tax — Surcharge tax breakdown PER_BOOK basis.
  • excluded.price.fees — Surcharge fees breakdown PER_BOOK basis.
data.properties.rooms.offers.pricing.display.perBasis basis*
String		 Required Rate Type / Rate basis for perBasis pricing (multiple options available).
rates*
Array[Object]		 Required All rates included in this object (per rate basis).
data.properties.rooms.offers.pricing.display.perBasis.rates currency*
String		 Required Display currency.
price*
PriceWithSTRAndMSPObject		 Required

All prices in this object per rate basis. Mostly the same fields as in PriceObject. It also contains strikeThroughRate but does not contain minSellRate.

  • price.inclusiveAmount — Total inclusive amount for the basis without surcharges (room + tax + fees).
  • price.exclusiveAmount — Exclusive amount per basis, excluding taxes and fees.
  • price.tax — Tax breakdown per basis.
  • price.fees — Fees breakdown per basis.
promotions
Array[PromotionsObject]		 Optional Promotion applicable at display rate.
data.properties.rooms.offers.pricing.display.dailyRates date
Date		 Optional Stay date (date-only YYYY-MM-DD).
rates
Array[Object]		 Optional All rates included in this object (but per-night basis).
data.properties.rooms.offers.pricing.display.dailyRates.rates currency*
String		 Required Display currency.
price*
PriceObject		 Required

All prices in this object per-night basis.

  • price.inclusiveAmount — Total inclusive amount per-night basis without surcharges (room + tax + fees).
  • price.exclusiveAmount — Exclusive amount per-night basis, excluding taxes and fees.
  • price.tax — Tax breakdown per-night basis.
  • price.fees — Fees breakdown per-night basis.
partnerPricing*
Object		 Required Partner-specific commercial and interco financial fields.
data.properties.rooms.offers.policies cancellation
Object		 Optional Cancellation policy for the offer.
feeWaivers
Array[Object]		 Optional FeeWaiver policy for the offer (for CA hotels only).
data.properties.rooms.offers.policies.cancellation freeCancellation*
Object		 Required Free cancellation details.
code
String		 Optional Cancellation policy in code format. E.g. 1D1N_100P.
description
Object		 Optional Cancellation policy in english text format and in requested locale (translated). Note: If it is an external provider, this Policy translated will not be able to offer. Eg — {"en-us":"Risk-free cancellation before the deadline.","es-es":"..."}
parameter
Array[Object]		 Optional Cancellation parameters.
segments
Array[Object]		 Optional Cancellation segments based on date.
data.properties.rooms.offers.policies.cancellation.freeCancellation isAllowed*
Boolean		 Required True if there is Free cancellation for booking in this room.
beforeDateTime
DateTime		 Optional Free cancellation date in the format YYYY-MM-DDTHH:MM:SS+-timezone. This field can only be returned when sending META_SEARCH in features.extra.
data.properties.rooms.offers.policies.cancellation.parameter days
Integer		 Optional Number of days prior to check-in date that cancellation fee will be applied. Except for: 365 Days with 100 Percent = the booking is non-refundable.
charge
String		 Optional There are 3 possible values for "charge" as follows: PERCENTAGE, NIGHT, HOUR.
value
Number		 Optional Charge value.
data.properties.rooms.offers.policies.cancellation.segments dateTime
DateTime		 Optional Datetime with timezone (YYYY-MM-DDTHH:MM:SS+-timezone).
type
String		 Optional From type partner we can infer if it is ONWARD or BEFORE. Possible values: ONWARD, BEFORE.
rates
Array[Object]		 Optional All rates included in this object (with different currencies).
data.properties.rooms.offers.policies.cancellation.segments.rates currency*
String		 Required Requested currency.
price*
PriceObject		 Required Price breakdown for this segment.
partnerPricing*
Object		 Required Partner-specific commercial and interco financial fields.
data.properties.rooms.offers.policies.feeWaivers
(For CA hotels only)		 amount
Object		 Optional Details for total amount of fee waiver.
expiry
Object		 Optional Details for expiry time of fee waiver.
leadTime
Object		 Optional Details for total lead time for fee waiver.
cutOffDateTime
DateTime		 Optional Absolute latest date-time (with timezone) until which the regulatory fee-waiver can apply. It is computed from the booking date. In DateTime with timezone format.
maxPenalty
Object		 Optional Object representing a capped penalty rule attached to the fee-waiver configuration.
data.properties.rooms.offers.policies.feeWaivers.amount value
Number		 Optional Numerical value.
unit
String		 Optional Unit out of possible values — PERCENTAGE.
data.properties.rooms.offers.policies.feeWaivers.expiry value
Number		 Optional Numerical value.
unit
String		 Optional Unit out of possible values — HOUR.
data.properties.rooms.offers.policies.feeWaivers.leadTime value
Number		 Optional Numerical value.
unit
String		 Optional Unit out of possible values — HOUR.
data.properties.rooms.offers.policies.feeWaivers.maxPenalty amount
Number		 Optional Numeric value of the cap penalty.
regulatoryCurrency
String		 Optional Regulatory country currency.
data.properties.rooms.offers.benefits id*
Integer		 Required Benefit ID. Eg — free wifi, free breakfast.
template
Object		 Optional Benefit text template in english and in requested locale (translated) as an addition key. Eg — {"en-us":"Free {0}","th-th":"Free {0}"}
templateValues
Object		 Optional Object containing actual values to be replaced in benefit template above.
data.properties.rooms.offers.benefits.templateValues unit
Object		 Optional Benefit unit in english and in requested locale (translated) as an addition key. It provides unit in which the parameter should be shown. Like in case of any amount, it can be currency like USD or INR. Eg — {"en-us":"NIGHT","th-th":"NIGHT"}
parameters
Array[Object]		 Optional Benefit parameters to be added in the above benefit template. Eg — For Free Wifi: template → "Free {0}", parameters.position → Is 0 as shown in template, parameters.value → "Wifi".
data.properties.rooms.offers.benefits.templateValues.parameters position
Integer		 Optional Position of the parameter as specified in the template.
value
String		 Optional Value of the parameter to be replaced in template, when convert template to actual benefit text.
data.properties.rooms.offers.additionalInfo dmcId
Integer		 Optional Supplier Id for the offer returned. Enabled for specific partners only. Contact technical team to get this column.
isPromoEligible
Boolean		 Optional Whether this rate is eligible for promotional pricing or promo campaigns.
expirationDateTime
DateTime		 Optional When this offer/price expires. Datetime with timezone.
channelIds
Array[Integer]		 Optional Provide all the rate-channel IDs that have been applied to the offer. Contact technical team to get this column.
rateChannel
String		 Optional Provide details for the rate channel for the offer. Like Retail, B2B or stacked Channels. Contact technical team to get this column.
channelDiscountSummary
Object		 Optional Offer-level summary of all rate-channel that have been applied to this price. Contact technical team to get this column.
isAmendable
Boolean		 Optional Provides if this offer's booking allowed to be amended after booking. Contact technical team to get this column.
dealTagging
String		 Optional Flag that this offer can't be forward distributed further. Contact technical team to get this column.
campaignDiscountAmount
Number		 Optional Total discount from campaigns/promocodes that has already been applied to the affiliate price for the offer. Contact technical team to get this column.
data.properties.rooms.offers.additionalInfo.channelDiscountSummary channelDiscountBreakDown
Array[Object]		 Optional Array containing elements of discounting channel that contributed to the final price.
data.properties.rooms.offers.additionalInfo.channelDiscountSummary.channelDiscountBreakDown channelId
Integer		 Optional Channel ID that gave this discount.
discountPercent
Number		 Optional Percentage discount from that specific channel.
data.properties.rooms.offers.offerContext userContext*
Object		 Required Parent Objects hold information specific on the user segment that each offer can be exposed to.
saleContext*
Object		 Required Parent Objects hold information specific on the offer segment that each offer can be exposed to.
data.properties.rooms.offers.offerContext.userContext channels*
Array[Enum]		 Required

On which channels, these offers can be exposed. (We are calling it channel, not platform, because in future there will be more enums here like wholesale.)

Enum values: MOBILE_WEB, DESKTOP_WEB, MOBILE_APP
userGroups*
Array[Enum]		 Required

To which user groups these offers can be exposed.

Enum values: LOGGED_OUT, LOGGED_IN, PREMIUM, CROSS_SELL
userCountries*
Object		 Required Parent Objects hold information specific on the country segment that each offer can be exposed to.
data.properties.rooms.offers.offerContext.userContext.userCountries countries*
Array[String]		 Required A list of UPPERCASE string indicate country code. Not supported in phase 1. Since B2B allows only one country in request.
mode
Enum		 Required

Enum values: ALLOW, BLOCK

This field indicates whether the country specified in the country field above is permitted to sell the offer. If the value displayed is "ALLOW," it means the offer can be sold to that country. Conversely, if the value displayed is "BLOCK," it indicates that the offer can be sold to all countries except the specified country.

This flag design supports the identification of international segments that can sell the offer to all countries except the country associated with the hotel. Will not be supported in first phase; can be ignored.
data.properties.rooms.offers.offerContext.saleContext packageTypes*
Array[Enum]		 Required

Can it be sold only with package offers or any.

Enum values: PACKAGED, NON_PACKAGED
distributionTypes*
Array[Enum]		 Required

Can be sold for direct distribution or forward-distribution.

Enum values: DIRECT, FORWARD. Can be ignored in first phase; added for future use cases.
forwardDistributionPartners
Array[Enum]		 Optional On which forward distribution partners, if applicable, these offers can be exposed. Enum values: GOOGLE, NAVER, ANY.
adTypes*
Array[Enum]		 Required On which advertising types, if applicable, these offers can be exposed. Enum values: STANDARD, STRATEGIC.
data.definitions surcharges
Array[Object]		 Required All returned surcharge ids (across entire response) with localized names at one place.
taxes
Array[Object]		 Required All returned tax ids (across entire response) with localized names at one place.
fees
Array[Object]		 Required All returned fee ids (across entire response) with localized names at one place.
promotions
Array[Object]		 Required All returned promotion ids (across entire response) with localized names at one place.
data.definitions.surcharges id
Integer		 Optional Surcharge id.
name
Object		 Optional Surcharge name in english and in requested locale (translated) as an addition key. Eg — {"en-us":"Green Tax","es-es":"..."}
data.definitions.taxes id
Integer		 Optional Tax id.
name
Object		 Optional Tax name in english and in requested locale (translated) as an addition key. Eg — {"en-us":"Sales tax","es-es":"Sales tax"}
data.definitions.fees id
Integer		 Optional Fee id.
name
Object		 Optional Fee name in english and in requested locale (translated) as an addition key. Eg — {"en-us":"Sales tax","es-es":"Sales tax"}
data.definitions.promotions id
Integer		 Optional Promotion Id.
name
Object		 Optional Promotion name in english and in requested locale (translated) as an addition key. Eg — {"en-us":"","es-es":""}
type
Object		 Optional Promotion type.
supplierPromoType
Object		 Optional Promotion supplier promo type.
data.definitions.promotions.type id
Integer		 Optional Promotion type id.
name
Object		 Optional Promotion type in english and in requested locale (translated) as an addition key. Eg — {"en-us":"Early Saver"}
data.definitions.promotions.supplierPromoType id
Integer		 Optional Promotion supplier promo id.
name
Object		 Optional Promotion supplier promo in english and in requested locale (translated) as an addition key. Eg — {"en-us":"..."}

surcharge object

Element Attribute Required Field Description
included / excluded id*
Integer		 Required Surcharge ID. Match localized labels in data.definitions.surcharges.
isMargin*
Boolean		 Required true — margin applied. false — no surcharge margin.
price*
PriceObject		 Required

Surcharge price breakdown:

  • price.inclusiveAmount — inclusive amount
  • price.exclusiveAmount — exclusive amount
  • price.tax — tax breakdown
  • price.fees — fees breakdown
partnerPricing*
Object		 Required Partner-specific commercial and financial fields for this surcharge (booking/display currency).
property
Object		 Optional Excluded surcharges only. Amounts quoted in hotel local / accommodation currency (pay at property).
property
(only for excluded surcharges)		 currency*
String		 Required Property / accommodation currency for the excluded surcharge.
price*
PriceObject		 Required Same structure as price above, in property currency.
partnerPricing*
Object		 Required Partner commercial and financial fields for the property-currency slice.

price object

Element Attribute Required Field Description
price inclusiveAmount
Number		 Optional Total inclusive amount for the rate basis.
exclusiveAmount
Number		 Optional Exclusive amount (excluding taxes and fees).
tax
Object		 Optional Tax breakdown for this price.
fees
Object		 Optional Fees breakdown for this price.
price.tax amount
Number		 Optional Total tax amount.
breakdown
Array[Object]		 Optional Itemized tax lines. Returned when TAX_DETAIL is in features.extra.
price.tax.breakdown[] id
Integer		 Optional Tax identifier. Resolve name via data.definitions.taxes.
amount
Number		 Optional Tax amount for this line.
percent
Number		 Optional Tax percentage for this line.
isBase
Boolean		 Optional true if this component is a base component in the pricing model.
isTaxable
Boolean		 Optional true if this component is subject to further taxation in the model.
price.fees amount
Number		 Optional Total fee amount.
breakdown
Array[Object]		 Optional Itemized fee lines. Returned when TAX_DETAIL is in features.extra.
price.fees.breakdown[] id
Integer		 Optional Fee identifier. Resolve name via data.definitions.fees.
amount
Number		 Optional Fee amount for this line.
percent
Number		 Optional Fee percentage for this line.
isBase
Boolean		 Optional true if this component is a base component in the pricing model.
isTaxable
Boolean		 Optional true if this component is subject to further taxation in the model.

Used where strikethrough / min-sell constraints are not needed—for example SurchargeObject.price, pricing.display.dailyRates.rates[].price, and cancellation penalty segments.rates[].price. For booking/display sell rows with marketing or MSP fields, use PriceWithSTRAndMSPObject instead.

strikeThroughRate and minSellRate objects under price

Element Attribute Required Field Description
price inclusiveAmount*
Number		 Required Total inclusive amount for the rate basis.
exclusiveAmount*
Number		 Required Exclusive amount (excluding taxes and fees).
tax*
Object		 Required Tax breakdown for this price.
fees*
Object		 Required Fees breakdown for this price.
strikeThroughRate
Object		 Optional Marketing strikethrough pricing. Returned when CROSSEDOUT_DETAIL is in features.extra.
minSellRate
Object		 Optional Minimum selling price constraint when exposed (typically on bookingRates).
price.tax amount*
Number		 Required Total tax amount.
breakdown
Array[Object]		 Optional Itemized tax lines. Returned when TAX_DETAIL is in features.extra.
price.tax.breakdown[] id
Integer		 Optional Tax identifier. Resolve name via data.definitions.taxes.
amount
Number		 Optional Tax amount for this line.
percent
Number		 Optional Tax percentage for this line.
price.fees amount*
Number		 Required Total fee amount.
breakdown
Array[Object]		 Optional Itemized fee lines. Returned when TAX_DETAIL is in features.extra.
price.fees.breakdown[] id
Integer		 Optional Fee identifier. Resolve name via data.definitions.fees.
amount
Number		 Optional Fee amount for this line.
percent
Number		 Optional Fee percentage for this line.
price.strikeThroughRate inclusiveAmount
Number		 Optional Original sell inclusive price (before discount).
savingAmount
Number		 Optional Absolute savings vs current sell price.
price.minSellRate inclusiveAmount
Number		 Optional Minimum selling price partners may display or sell at.

Same core fields as PriceObject, plus strikeThroughRate and minSellRate. minSellRate is not returned on all display paths (e.g. some sellAllInRates / perBasis rows).

partnerPricing object

Element Attribute Required Field Description
partnerPricing taxDueSupplierAmount
Number		 Optional Tax amount Agoda owes the supplier. Returned for eligible partnership configurations only.
estimatedCommissionAmount
Number		 Optional Estimated commission for the partner on this price slice. Eligible partnerships only.
marginAmount
Number		 Optional Margin amount on this price slice. Eligible partnerships only.
marginWithPfAmount
Number		 Optional Margin including processing fee. Specific partners only (e.g. B.com).
taxOnMarginAmount
Number		 Optional Tax on margin. Specific partners only (e.g. PCLN).
payableAmount
Number		 Optional Net payable amount for the partner for this price slice. Eligible partnerships only.
processingFeeAmount
Number		 Optional Processing fee for this offer/price slice. Eligible partnerships only.
referenceAmount
Number		 Optional Reference amount for reconciliation or display rules. Eligible partnerships only.
partnerPricing.agxAgpMetadata agxReferenceCommissionAmount
Number		 Optional Reference commission in AGX/AGP programs. Eligible partnerships only.
isAgxFreeTrial
Boolean		 Optional AGX free-trial flag.
isAgxNetRateReduction
Boolean		 Optional AGX net-rate reduction flag.
isAgpFreeTrial
Boolean		 Optional AGP free-trial flag.
isAgpNetRateReduction
Boolean		 Optional AGP net-rate reduction flag.

Appears on booking/display rate rows, surcharges, excluded-surcharge property blocks, and cancellation penalty rates. Most fields are returned only when enabled for your Site ID—confirm with your Agoda integration contact which fields apply.

promotions object

Element Attribute Required Field Description
promotions[] id
Integer		 Optional Promotion ID. Resolve localized name via data.definitions.promotions.
isAmountIncluded
Boolean		 Optional true when the promotion amount is already included in the displayed price.
savingAmount
Number		 Optional Promotion savings amount for this rate.
isCodeEligible
Boolean		 Optional true when a special promotion campaign applies to this room/rate.
type
Object		 Optional Promotion type: id and localized name (e.g. {"en-us":"Early Saver"}).
supplierPromoType
Object		 Optional Supplier promotion classification: id and localized name.

Returned on display pricing when PROMOTION_DETAIL is in features.extra—for example pricing.display.sellAllInRates[].promotions and pricing.display.perBasis.rates[].promotions.

Search 2.0 error handling

  • Error response example:
{
  "meta": {
    "status": "FAILURE",
    "unavailable": []
  },
  "errors": [
    {
      "code": "INVALID_FORMAT",
      "message": "Mandatory field(s) is/are missing.",
      "details": {
        "hint": "Check API documentation."
      }
    }
  ]
}

Error response schema

Element Attribute Required Field Description
meta status*
String		 Required Outcome of the search operation. Values: SUCCESS, FAILURE. On error responses, value is FAILURE.
unavailable
Array[Integer]		 Optional Property IDs that were requested but are unavailable (may be empty).
errors[] code
String		 Optional Machine-readable error code. See error codes table below.
message
String		 Optional Human-readable error message.
details
Object		 Optional Additional context (for example hint, or JSON path details for INVALID_FORMAT).

Error codes

code HTTP Status Description
INVALID_FORMAT 400 Mandatory field missing or invalid format. details may include JSON path hints (e.g. $.criteria.propertyIds[0]).
INVALID_SITE_ID 401 Authentication failed — Site ID.
INVALID_API_KEY 401 Authentication failed — API key.
RATE_LIMIT_EXCEEDED 429 Rate limit exceeded.
TECHNICAL_ERROR 500 Unexpected server error.

Updated about 23 hours ago

Did this page help you?