Skip to main content

Best Practices

This page is a checklist of principles. Step-by-step payloads and code samples live in each operation (Search, Quote, Book, List, Content) and in Use cases.

Booking flow​

  1. Default path: Search → Quote (/prebooking) → Book. Prefer this for every provider unless you have an explicit supplier rule that allows skipping quote.
  2. Optional skip (Hotelbeds / HBDS only): if the option has no remark RATE_TYPE containing RECHECK, the rate is bookable without a recheck — you may book from search with that optionRefId. If RECHECK is present, quote first. Do not apply this skip to providers that always require a price check (for example Expedia Rapid). Details: Quote — When you can skip.
  3. On quote, detect price and policy changes and reconfirm with the customer before calling book.
  4. Decide priceDelta explicitly (percentage tolerance). Omitting it or sending 0 means strict matching — Bundleport does not inject a platform default. See Book — priceDelta.
  5. Store bookingID, clientReference, and supplier references as returned.

Idempotency and recovery​

  • Set a unique clientReference before each book attempt.
  • If the HTTP result is unclear (timeout, disconnect), or an error carries recommended_action: verify_booking_then_restart, list bookings filtered by clientReference before retrying book. See Book — Timeouts and recovery.
  • Send X-Request-ID or settings.requestId on every call for support correlation.

Partial failures and tracing​

  • A 200 response can still include warnings and tracing.status PARTIAL. Inspect tracing.accessSpans per connectionCodes entry.
  • Use auditTransactions: true only for targeted debugging; redact and avoid logging full payloads in production (Error handling).

Timeouts​

  • Set settings.timeout per operation (milliseconds). Practical floors:
    • Search: ≥ 8000 (prefer 10000–15000 when fan-out spans many connections).
    • Book: ≥ 92000, or omit to use the connection ceiling (~2 minutes). Values below 90000 on book are raised to that floor.
  • Your HTTP client must outlive settings.timeout by a few seconds; cutting the socket earlier leaves possible confirmations without a reference on your side.
  • See Performance & availability.

ON_REQUEST and async confirmation​

  • If book returns ON_REQUEST, show a pending state, poll booking detail with backoff, and/or rely on webhooks. See ON_REQUEST.

Content vs live calls​

  • Cache Content API responses (destinations, hotels, boards) with TTLs appropriate to your product.
  • Use hotel filter / list endpoints to narrow availability payloads. Details: Content overview.

Trim availability payloads​

  • For broad searches (hundreds of hotels), set criteria.resultFilters to drop options the UI will never render. Common combinations: cheapestOnly: true (one rate per hotel), refundableFilter: REFUNDABLE_FILTER_ONLY_REFUNDABLE, boardCodes: ["AD"]. Details: Result filters.
  • This is post-processing, so it shrinks the response but does not save supplier latency or quota — narrow the request first via hotels, destination or connectionCodes, then add resultFilters for the final cut.

Errors and retries​

  • Prefer errors[].additionalData.recommended_action / retryable when present — they tell you whether to restart availability, requote, verify the booking, or back off. See Error handling — Buyer action hints.
  • Retry 5xx and 429 with backoff; do not blindly retry book without reconciliation, and never reuse a failed optionRefId after allotment / “do not retry”.
  • Follow Error handling and Error codes.

Security and limits​

Sandbox​

Next steps​