Skip to main content

Use Cases

These patterns reflect real certification-style flows: multi-room parties, price changes, unclear booking outcomes, supplier tracing, and cancellation logic. They are written without naming specific suppliers—use the connectionCodes assigned to your account.

Base URL: https://api.bundleport.com (or https://test-api.bundleport.com for sandbox).
Paths: /connect/hotels/v1/availability, /prebooking, /booking, /bookinglist, /bookingdetail, /cancel.

1. Multi-room family search and book​

Goal: Two rooms with different occupancies—e.g. room 1: two adults + one child (8); room 2: one adult.

Flow: Search with two entries in criteria.occupancies (one per room). Each entry lists paxes with ages. After the user picks an option, quote with optionRefId, then book with a rooms array: each room has occupancyRefId matching the room index from the search (typically 1, 2, …) and paxes aligned to that room.

{
  "criteria": {
    "checkIn": "2025-12-15T00:00:00Z",
    "checkOut": "2025-12-17T00:00:00Z",
    "occupancies": [
      {
        "paxes": [
          { "name": "John", "surname": "Doe", "age": 35 },
          { "name": "Jane", "surname": "Doe", "age": 33 },
          { "name": "Alex", "surname": "Doe", "age": 8 }
        ]
      },
      {
        "paxes": [
          { "name": "Chris", "surname": "Doe", "age": 40 }
        ]
      }
    ],
    "currency": "EUR",
    "language": "en",
    "nationality": "US"
  },
  "settings": {
    "connectionCodes": ["YOUR_SANDBOX_CONNECTION"]
  }
}

Pitfall: Guest counts in book must match the option’s occupancy shape from search/quote.

2. Price change between search and book​

Goal: Detect a price or policy change after the initial search and only book after the user accepts the latest quote.

Flow:

  1. Run search and show options.
  2. On “Continue”, call quote (/prebooking) with optionRefId.
  3. Compare quote price and cancelPolicy to what you showed earlier. If a warning such as PRICE_CHANGED appears (or net/gross differs beyond tolerance), stop and prompt the user.
  4. On acceptance, call book with the same freshly quoted context (do not reuse stale UI state).

This is the default production pattern: never skip quote before POST /booking.

3. Recovery after an unclear booking result (timeout / disconnect)​

Goal: HTTP timeout or network error after POST /booking—avoid double booking.

Flow:

  1. Generate a unique clientReference before each book attempt and persist it.
  2. If the response is missing or ambiguous, call POST /connect/hotels/v1/bookinglist with filters that include clientReference and the stay window (and your org’s list criteria).
  3. If a booking exists for that reference → treat as success; sync your DB.
  4. If none exists → safe to retry only after confirmation, or escalate with requestId / X-Request-ID.

See Create a booking — Timeouts and recovery.

4. Debugging supplier behaviour with audit traces​

Goal: Understand why search or book behaved unexpectedly (mapping, timeout, supplier error code).

Flow: Set settings.auditTransactions: true on the failing call. Inspect auditData.transactions in the response (and tracing.accessSpans for per-connection status). Use settings.testMode: true in sandbox when your account supports it.

Security: Do not log full audit payloads in production analytics or commit them to git. Redact PII and card data. See Sandbox & testing.

5. Cancellation with penalties and deadlines​

Goal: Show the user accurate penalties before cancelling.

Flow:

  1. From search/quote/book responses, read cancelPolicy (refundable, cancelPenalties[] with deadline, hoursBefore, value, currency).
  2. Deadlines are often in supplier or hotel local time—display both UTC and local where possible and add buffer before cut-off.
  3. Call POST /connect/hotels/v1/cancel with the booking reference Bundleport returned. If the response includes fees, persist them for finance.

Patterns by industry (short)​

PatternIdea
Agency / TMCSame search → quote → book; store bookingID, supplier reference, and clientReference; use booking list for reconciliation and reporting.
B2CCache Content API for static display; Booking API for live price; quote on checkout.
Meta-aggregatorRely on Bundleport’s multi-supplier aggregation; monitor warnings and tracing for partial failures.

Cross-cutting checklist​

  • Quote immediately before every book.
  • clientReference unique per attempt; use booking list for recovery.
  • X-Request-ID or settings.requestId on every call for support.
  • Webhooks for async confirmation when ON_REQUEST or slow suppliers—see Webhooks and ON_REQUEST flow.
  • Rate limits — monitor headers; see Rate limits.

Next steps​