Skip to main content
Use this pageChatGPTClaudeCursor · OpenAPI · MCP

Booking Flow Overview

This article explains the Bundleport hotel booking experience from a product perspective. For endpoint-level details, see the REST API reference.

Overview​

Bundleport presents a single shopping and booking journey across multiple hotel providers. Travellers (or agency agents) start by exploring availability, refine options, lock prices, and finally confirm reservations. Throughout the journey, Bundleport keeps a consistent experience regardless of the upstream provider, while clients choose which touchpoint (REST, MCP, etc.) to integrate with.

All transactional hotel operations use the Hotels API at /connect/hotels/v1/. For static catalog data (hotel information, destinations, rooms, boards, categories), use the Content API at /content/hotels/v1/.

Booking Flow Stages​

  1. Availability Search

    • Goal: Provide a curated list of stay options for the requested destination, dates, occupancies, and policy preferences.
    • Endpoint: POST /connect/hotels/v1/availability
    • Key behaviors: Fans out across settings.connectionCodes in parallel and concatenates options. Does not cross-dedupe the same hotel across connections. Optional criteria.resultFilters (e.g. cheapestOnly) trim the payload after suppliers reply.
    • Data surfaced: Hotel descriptions, room types, board plans, cancellation policies, total price, and provider sourcing metadata.

  2. Prebooking Quote

    • Goal: Confirm that a specific option can still be sold at the advertised conditions.
    • Endpoint: POST /connect/hotels/v1/prebooking
    • Key behaviors: Re-validates rates, surcharges, and policies with the source provider, catching price drifts, inventory expiration, or payment method restrictions before the shopper commits.
    • Data surfaced: Repriced totals, updated cancellation rules, payment requirements (merchant, card-on-file, pay-at-hotel), and warnings when conditions change.

  3. Book

    • Goal: Secure the reservation with the selected provider and collect all booking references.
    • Endpoint: POST /connect/hotels/v1/booking
    • Key behaviors: Sends holder, rooms[].paxes, optional paymentCard; persists references. For BOOK_STATUS_TYPE_ON_REQUEST, poll booking detail.
    • Data surfaced: booking = BookingDetail (status is BOOK_STATUS_TYPE_*, reference.bookingID, billingProviderCode, price, remarks, rooms). Not hotel, holder, or stay dates on the response.

  4. Post-Booking Operations

    • Get Booking Details: POST /connect/hotels/v1/bookingdetail — same BookingDetail as book. Poll while BOOK_STATUS_TYPE_ON_REQUEST.
    • List Bookings: POST /connect/hotels/v1/bookinglist — filter by dates or references (bookingID / clientReference / providerReference).
    • Cancel: POST /connect/hotels/v1/cancel — returns cancelReference (not a nested booking or penalty object).

Request Design Considerations​

  • Customer experience first: Align filters and sorting with the traveler’s intent (e.g., rate fences, board inclusion, flexible vs. non-refundable).
  • Inventory freshness: Quote immediately before booking when working with dynamic inventory to avoid stale pricing or oversold rooms.
  • Payment strategy: Decide whether you operate as merchant of record, pass thru provider payments, or mix both; Bundleport supports each model but downstream contracts dictate the right choice.
  • Reference hygiene: Persist reference.bookingID, clientReference, and rooms[].confirmationReference.
  • Operational metadata: Use clientReference and remarks on the book request. There is no free-form campaign metadata field on BookingDetail.

How Provider Integrations Respond​

Bundleport abstracts over many partner APIs (direct contracts, bedbanks, wholesalers). Providers vary in content depth, payment models, and booking SLAs. Bundleport normalizes:

  • Catalogs: Hotel/room naming, amenity descriptions, board codes, and policies.
  • Commercial logic: Pricing fields, rate rules, promotions, surcharges, mandatory fees.
  • Lifecycle states: Search tracing (SEARCH_TRACING_STATUS_*), quote STATUS_TYPE_*, booking BOOK_STATUS_TYPE_*.

Clients can mix providers without changing their customer journey; the platform handles provider-specific quirks behind the scenes.

Response Anatomy​

Every response surfaces both customer-facing data and operational telemetry:

  • Customer payloads: Option lists, repriced quotes, confirmations, or cancellation receipts.
  • Operational metadata: Tracking IDs, warnings (e.g., unmapped content), and optional tracing data that summarize provider response quality.
  • Audit and compliance: Optional debug/audit payloads capture raw provider transactions when you need deep investigations or regulatory proof.

Use warnings to detect catalog gaps (e.g., missing room mappings) early, and rely on tracing data to enforce provider SLAs.

Content Data​

For static catalog data (hotel descriptions, destinations, room types, boards, categories), use the Content API at /content/hotels/v1/.... This API provides access to:

  • Hotel catalog browsing and search
  • Destination information
  • Room type details
  • Board (meal plan) options
  • Hotel categories
  • Provider metadata

Use the Content API to build your hotel catalog, power autocomplete features, and enrich search results. All transactional operations (search, booking, cancellation) remain in the Hotels API at /connect/hotels/v1/....

Best Practices​

  • Prebooking before Book: Always call POST /connect/hotels/v1/prebooking immediately before POST /connect/hotels/v1/booking to reduce failed bookings and surprise price deltas when inventory moves quickly.
  • Scope searches thoughtfully: Limit to known hotel lists or apply business rules to control downstream call costs and stay within provider rate limits. Use the Content API to preload hotel catalogs.
  • Persist identifiers: Store reference.bookingID, clientReference, and rooms[].confirmationReference.
  • Enable audits on demand: Turn on debug/audit traces when onboarding new providers or investigating incidents; disable when not needed to reduce payload size.
  • Monitor connection health: Track warning codes, tracing statuses, and availability hit rates per connectionCode.

With these practices, Bundleport delivers a consistent product journey while letting you swap or combine providers, tailor payment models, and retain full visibility into downstream performance.