--- title: "Get booking options" method: POST path: "/experiences/tours/{id}/booking-options" tags: ["Tours"] --- # Get booking options `POST /experiences/tours/{id}/booking-options` ## Request - Base URL: `https://api.liteapi.travel/v3.0` - URL: `https://api.liteapi.travel/v3.0/experiences/tours/{id}/booking-options` - Auth: API key in header `X-API-Key` ## Overview Resolve priced booking options, time slots, and required guest inputs for a selected tour date and participant mix. ## When to Use - **Option/slot pickers** - Show available variants and start times for a date - **Live pricing** - Display slot totals (`pricing.totals.net` / `priceSummary.netPrice`) - **Checkout forms** - Collect `bookingQuestionSchema` before proceeding to payment ## What You Get - **Booking options** - `optionId`, title, and `bookingQuestionSchema` - **Time slots** - `dateTime`, `isAvailable`, and slot-level pricing (`unitNet` / `totalNet` / `totals.net` / `priceSummary.netPrice`, plus `totals.commission`) - **Participant mapping** - Uses `ticketCategory` keys from availability (e.g. `adult`, `child`) ## Quick Start POST a body with `language`, `currency`, `date` (`YYYY-MM-DD`), and `participants` to `/experiences/tours/{id}/booking-options`. Use slot `pricing.totals.net` as `selection.price.amount` on prebook, and for checkout handoff. ## Option-level `price` `options[].price.amount` reflects the lowest available slot price for the requested mix. Checkout uses the chosen slot's `pricing.totals.net`. ## Error codes Product-operation codes are listed below. Shared authentication/access/rate-limit middleware can return common codes such as 401, 40301 or 4290. HTTP status and error code are separate; do not parse message text. | Code | Meaning | | --- | --- | | 71001 | invalid experience request | | 71002 | experience not found | | 71003 | experiences provider request failed | | 71004 | experiences provider request timed out | | 71005 | experience request is unauthorized | | 71006 | experience request is forbidden | | 71007 | experiences service is temporarily unavailable | | 71099 | failed to retrieve experiences | ## Path parameters - `id` string, required ## Request body - BookingOptionsRequest - `language` string, required: ISO language code for localized content. - `currency` string, required: ISO 4217 currency code for prices. - `date` string, date, required: Tour date to price, `YYYY-MM-DD`. - `participants` object, required: Participant counts keyed by ticket category (age band), e.g. `adult`, `child`. Keys are lowercase and must match a `ticketCategory` returned by `GET /experiences/tours/{id}/availability` for this tour. An array (e.g. `[{"category":"adult","count":2}]`) is rejected, and uppercase keys (e.g. `ADULT`) are rejected - use the exact lowercase category strings from availability. - `addons` object[]: Optional add-ons to price alongside the tour, from `GET .../availability` `addons[].id`. - `id` integer, required - `quantity` integer, required ## Response `200` Booking options with canonical bookingQuestionSchema - BookingOptionsEnvelope - `data` BookingOptionsResponse, required - `tourId` integer, required - `date` string, date, required - `currency` string, required - `options` BookingOptionResponse[], required - `optionId` integer, required - `tourId` integer - `title` string - `description` string - `meetingPoint` string, nullable - `dropOff` string, nullable - `duration` number - `durationUnit` string - `language` object: Languages this option is conducted/supported in. - `tourLanguage` string[]: Live guide language(s), e.g. `en`. - `audioLanguage` string[]: Audio guide language(s), when offered. - `bookletGuideLanguage` string[]: Printed/booklet guide language(s), when offered. - `services` object: Provider-sourced service flags; exact upstream semantics aren't formally published. Based on the `flags` filter values used elsewhere, `prt`/`stl`/`wlc` likely correspond to private/skip-the-line/wheelchair-accessible respectively — treat as indicative, not guaranteed. - `prt` boolean - `stl` boolean - `wlc` boolean - `coordinates` TourCoordinatesResponse - `lat` number, double - `long` number, double - `coordinatePrecision` string, nullable: Precision/confidence of `coordinates`, when the provider supplies it. - `unlimitedAvailability` boolean - `nextAvailableDate` string: Next date/time this option can be booked, when the tour has no availability on the requested date. - `openingHours` TourOpeningHoursResponse[] - `from` string - `to` string - `bookingQuestionSchema` BookingQuestionFieldResponse[], required - `fieldId` string, required: Stable provider-neutral canonical field ID. - `scope` 'booking' | 'participant', required - `type` 'text' | 'date' | 'select' | 'group' | 'pickup_location', required - `label` string, required - `required` boolean, required - `maxLength` integer, nullable - `options` BookingQuestionOptionResponse[] - `label` string, required: Human-readable option text shown in a dropdown or radio group. - `value` string, required: Machine value submitted as the booking question answer when this option is selected. - `fields` BookingQuestionFieldResponse[]: Required and non-empty when type is group or pickup_location. - `pickup` BookingPickupPresentationResponse: Provider-neutral pickup UI metadata. Booking answers remain address/latitude/longitude and never submit area/choice IDs. - `mode` 'area' | 'location' | 'map', required: area = pick a real point inside allowed area bounds; location = select an exact predefined pickup point; map = free map/address search fallback. - `summary` string - `description` string - `transportationModes` string[], required - `areas` BookingPickupAreaResponse[], required: Allowed pickup regions for mode=area. Not selectable answers. - `id` string, required: UI-only pickup area identity; not a provider ID and not submitted with booking answers. - `label` string, required - `address` string, required - `coordinates` BookingPickupCoordinatesResponse, required - … - `bounds` BookingPickupBoundsResponse, required - … - `choices` BookingPickupChoiceResponse[], required: Exact predefined pickup points for mode=location. - `id` string, required: UI-only canonical pickup choice identity; not a provider ID and not submitted with booking answers. - `label` string, required - `address` string, required - `coordinates` BookingPickupCoordinatesResponse, required - … - `slots` ExperienceBookingOptionSlot[]: Priced time slots for this option. Use pricing.totals.net for checkout. - `dateTime` string, date-time - `vacancies` integer - `isAvailable` boolean - `unavailabilityReason` string, nullable: Why the slot is unavailable when isAvailable is false. Official provider groups: no_availability, not_enough_spots, invalid_request, others. Legacy responses may also include sold_out. - `minParticipants` integer: Minimum participants required for this slot; present even when unavailable. - `maxParticipants` integer: Maximum participants allowed for this slot. - `pricing` ExperienceSlotPricing: All slot pricing fields reflect your price for this booking. - `participants` ExperienceParticipantLine[] - `ticketCategoryId` integer - `ticketCategory` string - `minAge` integer: Minimum age for this ticket category, from availability. - `maxAge` integer: Maximum age for this ticket category, from availability. - `independentlyBookable` boolean: Whether this ticket category can be booked on its own without a required adult, from availability. - `quantity` integer - `unitNet` number, double: Price per unit. unitNet × quantity may differ from totalNet by a cent due to rounding. - `totalNet` number, double: Price for this line. Sum of totalNet reconciles to totals.net. - `currency` string - `groups` ExperienceGroupLine[] - `groupCategoryId` integer - `groupTicket` ExperienceGroupTicketLine - … - `additionalPax` ExperienceAdditionalPaxLine - … - `addons` ExperienceAddonLine[] - `addonCategoryId` integer - `quantity` integer - `unitNet` number, double: Price per add-on unit. - `totalNet` number, double: Price for the add-on line. - `currency` string - `priceSummary` ExperienceSlotPriceSummary - `netPrice` number, double: The slot's total price (same value as totals.net). - `currency` string - `totals` ExperienceSlotTotals - `net` number, double, required: The slot's total price. Use as selection.price.amount on prebook. - `commission` number, double: Your earnings on this slot, when applicable. - `currency` string, required - `price` object: The price for the requested mix, based on the lowest available slot. Prefer the chosen slot's `pricing.totals.net` for `selection.price.amount` on prebook. - `amount` number: Lowest available price for this option and participant mix. - `currency` string ## Other responses - `400`: Invalid discovery query, tour id or booking-options input. Code 71001. - `401`: Authentication failed. Shared API-key middleware uses code 401; product handlers can use their operation-specific unauthorized code listed on the endpoint. - `403`: Access denied. Shared access middleware uses common codes; product-specific forbidden codes are listed on the endpoint. - `404`: Tour or requested discovery resource not found. Code 71002. - `413`: Booking-options request body exceeds the 1 MiB limit. Code 71001. - `429`: Shared Dispatcher request limit exceeded. Code 4290; this is not an Experiences operation code. - `500`: Discovery operation failed. Code 71099. Shared middleware can return other common codes. - `502`: Experiences discovery dependency failed. Code 71003. - `503`: Experiences discovery is temporarily unavailable. Code 71007. - `504`: Experiences discovery dependency timed out. Code 71004. --- [API](https://skmtc.dev/liteapi/apis/api-experiences.md) - [All operations](https://skmtc.dev/liteapi/apis/api-experiences/llms.txt) - [OpenAPI document](https://skmtc.dev/liteapi/apis/api-experiences/revisions/40074513d3a2?raw)