Search for hotels near a city using GET /v1/reference-data/locations/hotels/by-city with cityCode (IATA city code) and optional radius, radiusUnit, hotelSource params to get a list of hotelId values.
Fetch available rates by calling GET /v3/shopping/hotel-offers with hotelIds (comma-separated, up to 20 per call), checkInDate, checkOutDate, adults, roomQuantity; each result contains offers[] with rate, room type, and cancellation policy.
Select an offer and call GET /v3/shopping/hotel-offers/{offerId} to confirm current availability and price immediately before booking — rates are dynamic and the list-level price may be stale.
Create the booking by POSTing to /v1/booking/hotel-orders with data.type='hotel-order', data.hotelOffers[0].offer.id, data.guests[] (name, contact), and data.payment (method and card details or virtual card token).
Parse the response for data.associatedRecords to get the hotel confirmation number; store both the Amadeus booking id and the hotel's own reference.
Handle guarantee vs deposit semantics: check offers[].policies.guarantee and offers[].policies.deposit in the offer response before booking to know whether a card charge is immediate.
Known gotchas
Hotel content in Amadeus Self-Service is sourced from aggregators; rate parity is not guaranteed and the same property may appear under different hotelId values with different pricing.
Cancellation policy objects have varying structures depending on the hotel source — always parse policies.cancellations[].deadline in UTC and convert to local hotel time for display to users.
The hotel offer step (v3/shopping/hotel-offers) may return offers with type='ROOM' but without a guarantee policy field, meaning the hotel accepts without prepayment; confirm this before telling a user no charge will occur.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp