--- title: "1. Create an experience checkout session (PREBOOK)" method: POST path: "/experiences/tours/{id}/prebooks" tags: ["Bookings"] --- # 1. Create an experience checkout session (PREBOOK) `POST /experiences/tours/{id}/prebooks` ## Request - Base URL: `https://api.liteapi.travel/v3.0` - URL: `https://api.liteapi.travel/v3.0/experiences/tours/{id}/prebooks` - Auth: API key in header `X-API-Key` ## Overview Create a temporary hold on the selected tour slot and a Stripe PaymentIntent for checkout. ## When to Use - **Checkout start** — After the user picks option, slot, and participants from booking-options - **Payment setup** — Obtain `transactionId` and `secretKey` for Stripe SDK confirmation - **Hold window** — Reserve inventory for ~10 minutes before book ## What You Get - **Checkout context** — `tourId`, `optionId`, `dateTime`, `language`, `participants`, and pricing echoed back - **Provider refs** — `cartId`, `experienceBookingId`, `providerBookingId`, `status`, `reservationExpiresAt` - **Stripe fields** — `transactionId`, `secretKey`, `paymentTypes: ["TRANSACTION_ID"]` ## Quick Start POST the same `selection` used for display pricing from booking-options with `usePaymentSdk: true`. Confirm payment with Stripe, then call `POST /experiences/bookings`. ## 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 | | --- | --- | | 72001 | selection price mismatch | | 72002 | invalid experience selection | | 72003 | prebook resource not found | | 72004 | experience selection rejected by provider | | 72005 | experience prebook conflicts with the current state | | 72006 | prebook provider request failed | | 72007 | prebook provider request timed out | | 72008 | prebook request is unauthorized | | 72009 | prebook request is forbidden | | 72010 | prebook service is temporarily unavailable | | 72011 | booking currency is not accepted for this selection | | 72099 | failed to create prebook | For 72001, requested/expected are customer SELL totals; do not apply markup or FX again. Inspect the code on HTTP 400, 409 and 422. A generic no-money error must not open price-change consent. ## Path parameters - `id` string, required ## Request body - ExperiencePrebookRequest - `selection` ExperienceSelection, required - `optionId` integer, required: Chosen tour option from booking-options. - `dateTime` string, date-time, required: Chosen slot start time from booking-options (`slots[].dateTime`). - `price` ExperienceSelectionPrice, required - `amount` number, required: The price shown on booking-options (`slots[].pricing.totals.net`, equivalent to `priceSummary.netPrice`). - `currency` string, required: ISO 4217 currency code for the slot price. - `participants` ExperienceSelectionParticipants[], required - `ticketCategory` string, required: Semantic participant key from availability/booking-options (e.g. `adult`, `child`). - `numberOfParticipants` integer, required: Count of participants in this category. - `questions` object: Provider-neutral canonical answers for bookingQuestionSchema. - `answers` ExperienceQuestionAnswer[] - `fieldId` string, required: Canonical field ID from `bookingQuestionSchema`. - `value` unknown, required - `participantAnswers` ExperienceParticipantQuestionAnswers[] - `participantIndex` integer, required - `answers` ExperienceQuestionAnswer[], required - `fieldId` string, required: Canonical field ID from `bookingQuestionSchema`. - `value` unknown, required - `language` string, required: ISO language code used for validate and downstream book cart. - `currency` string, required: ISO 4217 currency code used for validate and downstream book cart. - `clientReferenceId` string: Partner reference echoed in prebook response and stored on the checkout session. - `usePaymentSdk` boolean, required: Phase 1 requires `true` to create a Stripe PaymentIntent. - `voucherCode` string: Optional discount voucher code. When valid the voucher amount is deducted from the Stripe PaymentIntent and charged separately to the agency's stored card at book time. - `payment` object: Optional Stripe metadata (e.g. statement descriptor suffix). - `descriptorSuffix` string ## Response `200` Prebook created with selection context, validate refs, and Stripe checkout fields - ExperiencePrebookResponse - `data` ExperiencePrebookData, required - `prebookId` string, required: LiteAPI checkout session id. Pass to `POST /experiences/bookings`. - `tourId` integer: Provider tour id (from the path parameter). - `optionId` integer: Chosen tour option from the prebook selection. - `dateTime` string, date-time: Chosen slot start time from the prebook selection. - `language` string: Language sent on validate. - `clientReferenceId` string: Partner reference when provided on prebook. - `participants` ExperienceSelectionParticipants[]: Participant mix from the prebook selection. - `ticketCategory` string, required: Semantic participant key from availability/booking-options (e.g. `adult`, `child`). - `numberOfParticipants` integer, required: Count of participants in this category. - `price` number, required: The price used to create the Stripe PaymentIntent for this checkout. - `commission` number: Your earnings on this checkout. - `clientCommission` number: Your earnings on this checkout. - `currency` string, required: Checkout currency. - `cartId` string: Shopping cart id from the provider checkout session. - `experienceBookingId` string: Internal booking identifier from the provider checkout session. - `providerBookingId` string: Provider booking hash from validate (`bookingId` upstream). - `status` string: Validate hold status from the provider (typically `temp`). - `transactionId` string: Stripe PaymentIntent transaction id. Confirm with Stripe SDK, then pass to book. - `secretKey` string: Stripe client secret for PaymentIntent confirmation. - `publishableKey` string, nullable: Stripe publishable key when returned by payment-gateway. - `voucherCode` string: Echoed voucher code when a valid voucher was applied. - `voucherTotalAmount` number: Amount covered by the voucher. Zero when no voucher was applied. - `sellingPriceToUser` number: Amount the end-user actually pays (price minus voucher). Equals `price` when no voucher is applied. - `reservationExpiresAt` string, date-time: UTC expiry of the validate hold (~10 minutes). Create a new prebook after expiry. - `paymentTypes` string[], required: Supported payment methods for book. Phase 1: `TRANSACTION_ID` only. ## Other responses - `400`: Invalid selection/input, selection rejected, or a price change requiring explicit client handling. Codes 72001, 72002 or 72004. - `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`: Requested prebook resource not found. Code 72003. - `409`: State conflict or price-change validation. Inspect error.code. - `413`: Request body exceeds the 1 MiB limit. Code 72002. - `422`: Selection validation failed. The numeric code and detail structure are the same as for HTTP 400. - `429`: Shared Dispatcher request limit exceeded. Code 4290; this is not an Experiences operation code. - `500`: Failed to create prebook. Code 72099. - `502`: Prebook dependency failed or returned unusable monetary information. Code 72006; no price details are returned in the safe fallback. - `503`: Prebook service temporarily unavailable. Code 72010. - `504`: Prebook dependency timed out. Code 72007. --- [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)