LockTrip Hotels

Searches LockTrip destinations (cities, regions, landmarks, or specific hotels) by free-text `query`. Returns `locations[]`, each with `id`, `name`, `country`, `type` (CITY/REGION/HOTEL/AIRPORT/POI), and `fullName`. Pass a chosen location's `id` to `hotel_search` as its `regionId` to search hotels in that area. No authentication required. This is the first step of the booking flow.

Starts an asynchronous hotel-availability search and returns a `searchKey` (plus `sessionId`, `status`, `totalHotels`). Required: `startDate` and `endDate` (both YYYY-MM-DD), `rooms[]` (each `{adults, childrenAges?[]}`, 1-4 adults per room), `nationality` (2-letter ISO country code), and EITHER `regionId` (from `search_location`) OR `latitude`+`longitude`; `currency` (3-letter) is strongly recommended. Before calling, collect the missing trip details from the user (exact check-in date, number of nights to derive `endDate`, number of rooms/adults, and nationality) instead of guessing. No authentication required. Pass the returned `searchKey` to `get_search_results` (poll it), and reuse the SAME `searchKey` for `get_hotel_rooms` and `prepare_booking`.

Returns the hotel results for a running search identified by `searchKey` (from `hotel_search`). Results stream in asynchronously, so POLL this tool until the returned `searchStatus` equals `COMPLETED` (it is `IN_PROGRESS` while results are still loading). Supports `page` (0-indexed on BOTH the request and the response echo — page 0 is the first page and comes back as page 0), `size` (use a large value like 5000 to get all), `filters` (minPrice/maxPrice/starRatings/amenities/mealTypes/hotelName/minDiscountScore), `sortBy` (PRICE_ASC/PRICE_DESC/RATING_DESC/DISTANCE/VALUE_DESC), and `currency`. Returns `hotels[]` (each with `hotelId`, `name`, `starRating`, `minPrice`, `originalPrice`, `currency`, `discountScore`, `reviewScore`, `hasFreeCancellation`, `isRefundable`, etc.), plus `totalCount` and `hasMore`. `discountScore` is LockTrip's value score for the offer: an estimated % below the hotel's usual public price (the figure locktrip.com shows as "X% off"). Higher means better value; 20 or more is a strong deal; 0 or missing means no score. A low price is not the same as good value, so to find the best-value hotels use `sortBy` VALUE_DESC (highest discountScore first) or `filters.minDiscountScore` (e.g. 20), and weigh it with `starRating` and `reviewScore`. No authentication required. Pass a chosen `hotelId` together with the SAME `searchKey` to `get_hotel_rooms`.

Lists the bookable room packages for one hotel. Required: `hotelId` (from `get_search_results`), the SAME `searchKey` from `hotel_search`, plus `startDate`, `endDate`, `rooms[]`, `nationality`, and `regionId` (re-supply the same values used in `hotel_search`); `currency` is recommended. Returns `packages[]`, each with a `quoteId` (the priced, bookable offer — format `packageId_hotelId`), a `packageId` (the same string as the `quoteId`; truncate it at the underscore before sending it to `check_cancellation_policy`), `roomName`, `mealType`, `price`, `pricePerNight`, `totalNights`, `amenities`, and `isRefundable`. No authentication required. Pass a chosen `quoteId` to `prepare_booking` (and to `confirm_booking` for B2B). To inspect cancellation terms first, pass `quoteId.split('_')[0]` (the bare package UUID, WITHOUT the `_hotelId` suffix) to `check_cancellation_policy` — handing it the full `quoteId` fails with a misleading SESSION_EXPIRED even on a live session.

Returns detailed cancellation terms for one or more room packages before booking. Required: `searchKey`, `hotelId`, and `packageIds[]` — pass the package UUID WITHOUT the `_hotelId` suffix, i.e. `quoteId.split('_')[0]`. Passing the full `quoteId` here fails with a misleading SESSION_EXPIRED even on a live session, because the policy lookup matches the bare UUID. Returns `policies[]`, each with `packageId`, `isRefundable`, `freeCancellationUntil`, and `fees[]` (`fromDate`, `amount`, `currency`). `currency` is the supplier's own denomination for that penalty and is OMITTED, never guessed, when the supplier does not state one — so read the amount as unpriced if it is absent rather than assuming your search currency. No authentication required. Informational only — use it to confirm the refund/penalty terms with the user, then continue with `prepare_booking`.

Prepares a booking for a chosen room offer and returns the final price plus a `preparedBookingId` (also returned as the alias `bookingInternalId`). A prepared booking has NO fixed expiry — what expires is the search session behind its `quoteId`, which surfaces as "This booking is unavailable"; re-run `hotel_search` and re-quote if you see that. Required: `quoteId` (from `get_hotel_rooms`), `searchKey` (the SAME one from `hotel_search` — omitting it is a 400), `rooms[]` (each `{roomIndex (0-based), guests:[{firstName, lastName, title?}], children?}` — one guest entry per adult), and a `contactPerson` (`firstName`, `lastName`, `email`, `phone`); the `searchKey` is required (it warms the cancellation-policy cache the backend needs to book). Collect every guest's first/last name and a contact email + phone from the user before calling. REQUIRES A SESSION: for a guest booking, first call `guest_login` with the user's email and pass the returned token as the `sessionToken` argument. After this, send `preparedBookingId` to `create_checkout` (consumer, recommended) or `get_payment_url` (consumer, Stripe alternative); B2B partners use `confirm_booking`.

Confirms and finalizes a booking using a B2B credit line — PARTNER ACCOUNTS ONLY. Guests cannot use this; ordinary consumers must instead pay via `create_checkout` (recommended) or `get_payment_url`. Required: `bookingInternalId` and `quoteId` (both from `prepare_booking`); `paymentMethod` defaults to `CREDIT_LINE`. REQUIRES A B2B PARTNER SESSION with a credit line; a `guest_login` session has no credit line and is rejected. Returns `accepted` and `message`, plus a `voucherUrl` on success. On `accepted:false`, READ `serviceUnavailable`: if it is absent the credit-line service gave a real verdict (insufficient balance, inactive line) and the answer will NOT change on retry — tell the user and stop; if it is `true` the credit-line service was unreachable, which is a system fault and not a decision about their credit. Even then do NOT blindly retry: the reservation may already have been applied — re-read the booking with `get_booking_details` first. Note also that `accepted:true` means the credit line was charged and the booking accepted, but the supplier reservation is completed asynchronously afterwards.

Lists the authenticated user's existing bookings, filtered by `type`: `UPCOMING` (default), `COMPLETED`, `CANCELLED`, or `PENDING`. Needs a registered LockTrip account session; guest sessions from `guest_login` cannot list bookings. Without a signed-in session, pass the user's `email` instead: LockTrip emails them a sign-in link to their bookings on locktrip.com, and the result has `magicLinkSent: true` (nothing is shown or changed in this chat). Returns `bookings[]` (each with `bookingId`, `bookingReferenceId`, `hotelName`, `checkIn`, `checkOut`, `status`, `roomCount`, `createdAt`, and `totalPrice` + `currency` when the booking records a price) plus `totalCount` (all matching bookings). Optional paging: `page` (0-based) and `size` (max 100); omit both for the full list. Pass a `bookingId` to `get_booking_details` or `cancel_booking`.

Returns the full details of one existing booking: hotel, dates, rooms, guests, contact person, total price, payment status (`PAID`, `PENDING`, or `CREDIT_LINE` for a confirmed booking charged to a partner credit line, settled per statement via `GET /api/b2b/credit-line/statement`), and the cancellation policy (including any cancellation fees and the free-cancellation deadline). Required: `bookingId` (from `list_bookings`). Needs a registered LockTrip account session; guest sessions cannot view booking details. Without a signed-in session, pass the user's `email` instead: LockTrip emails them a sign-in link to their bookings on locktrip.com, and the result has `magicLinkSent: true` (nothing is shown or changed in this chat). Informational only. Use this to read the fee/refund terms BEFORE cancelling, since `cancel_booking` itself does not return a fee preview.

Cancels an existing booking. Required: `bookingId` (from `list_bookings`) and the boolean `confirmed`; optional `reason`. This is a two-step safety flow: calling with `confirmed:false` does NOT cancel and returns only a 'not confirmed' acknowledgement (it does NOT return fees or refund amounts — read those first from `get_booking_details`); call again with `confirmed:true` to actually submit the cancellation. On success the response includes `cancellationFee` + `cancellationFeeCurrency` when the supplier reported a charged fee (absent means none was reported, not zero); refunds are processed separately. When the cancellation is not accepted, `failureReason` is one of `NOT_FOUND`, `AFTER_CHECK_IN`, `NOT_CANCELLABLE_STATUS`, `SUPPLIER_NOT_CONFIRMED` (submitted, under review: do not rebook or retry) or `ERROR` (not processed: the booking was not cancelled; try again later or contact support). Needs a registered LockTrip account session; guest sessions cannot cancel bookings. Without a signed-in session, pass the user's `email` instead: LockTrip emails them a sign-in link to their bookings on locktrip.com, and the result has `magicLinkSent: true` (nothing is shown or changed in this chat). Returns `success` and a `message`. This is a destructive, terminal action — confirm with the user before calling with `confirmed:true`.

Fetches full descriptive details for one hotel: name, address, coordinates (lat/lng), star rating, description, phone, amenities, photos, and reviews. Required: the NUMERIC `hotelId` (the same hotel identifier returned in search results, passed as a number); optional `language`, `includeImages` (set true to fetch extra photos), and `imageLimit` (default 20, max 100). Returns a `hotel` object and optional `additionalImages`. No authentication required. Informational only — use it to enrich what you show the user before they pick a room.

Creates a hosted Stripe (credit-card) checkout link for a prepared booking — an alternative consumer payment rail to `create_checkout` (Revolut). Required: `bookingId` (the `preparedBookingId` from `prepare_booking`), `currency` (3-letter), and `backUrl`; optional `successUrl`. REQUIRES A REGISTERED-ACCOUNT SESSION; a `guest_login` session is REJECTED here (the Stripe rail is not open to guests; use `create_checkout` for a guest instead). Returns a payment `url` and a `sessionId`. Share the `url` with the guest — the booking is confirmed automatically by webhook once payment succeeds. Prefer `create_checkout` unless a Stripe card link is specifically needed.

Creates a hosted Revolut payment link for a prepared booking — the RECOMMENDED way for ordinary consumers (no credit line) to pay. Required: `bookingId` (the `preparedBookingId` from `prepare_booking`) and `currency` (3-letter); optional `backUrl` and `successUrl`. REQUIRES A SESSION: pass the token returned by `guest_login` as the `sessionToken` argument. Returns a `checkoutUrl` (valid ~20 minutes), a `checkoutToken`, and a `message`. Share the `checkoutUrl` with the guest to complete payment — the booking is confirmed automatically by webhook once payment succeeds (do not call `confirm_booking`, which is B2B-only).

Starts a guest checkout from the user's `email` only (no password) and returns a session `token` plus `userId`, `email`, and `isNewUser`; a new email also receives a verification email. Use it when the user wants to book, with the email the user gave for the booking. Pass the returned `token` as the `sessionToken` argument to `prepare_booking` and `create_checkout`. If the email already belongs to a LockTrip account, no guest session is created: LockTrip emails a sign-in link to that address instead, and the result has `magicLinkSent: true` and no `token`. Tell the user to check their email and finish on locktrip.com; do not call `guest_login` again for that email. A guest session can search, prepare a booking, and pay via `create_checkout`, but CANNOT list, view or cancel bookings, use `get_payment_url`, or use `confirm_booking`. No authentication required to call this tool.

Returns the signed-in partner's own credit-line statement: `balance` (the real-time balance due and pending, ALWAYS for the whole credit line, not filtered by the dates), `account` details (name, currency, creditLimit, periodType), and the booking rows whose due date falls between `from` and `to` (default: the current month; at most 93 days). Each row carries `bookingReferenceId`, `hotelName`, `guestName`, dates, `amount`, `currency`, `bucket` (`current` = due, `pending` = not due yet), `dueDate`, `paid`, `outstanding`, `paymentStatus`, `settledBy`, and `lineType` (`booking`, or `cancellation_fee` for a late-cancellation charge). Read-only. Needs a signed-in partner credit-line account session; guest sessions have no credit line. Takes no account identifier: the credit line is always the caller's own.

Lists the signed-in partner's own bank-transfer settlements of the credit line: `settlements[]` (each with `reference`, `status`, `amount`, `currency`, `createdAt`, `expiresAt`, and `receivedAmount`/`receivedAt` once the transfer has arrived), `payable[]` (transfers still awaiting funds), the `bank` details to pay into, and a `notice` that must be shown to the user as given (overpayments are held as credit, not refunded). This is the list of transfers, not per-booking payment state: that is on each row of `get_credit_line_statement`. Read-only. Needs a signed-in partner credit-line account session; guest sessions have no credit line.

Returns the signed-in partner's own monthly statement of account for `period` (YYYY-MM) exactly as it was sent to them: `format` `pdf` (default) returns the PDF as an embedded file, `csv` returns the CSV as text in `csv`. Statements exist only for months already issued; any other month returns RESOURCE_NOT_FOUND. Read-only. Needs a signed-in partner credit-line account session; guest sessions have no credit line.