Key Concepts

This guide explains the key concepts and terminology used throughout Bundleport's documentation. Understanding these concepts will help you build effective integrations.

Availability and Rates

Availability

Availability refers to hotel inventory that is available for booking on specific dates with specific occupancy requirements. When you search for hotels, you're querying availability across multiple suppliers.

• Real-time: Availability is checked in real-time with suppliers
• Date-specific: Availability is tied to check-in and check-out dates
• Occupancy-specific: Availability depends on number of adults/children
• Supplier-dependent: Different suppliers may have different availability

Rate

A rate is the price for a specific hotel room, board type, and occupancy configuration. Rates can vary based on:

• Dates: Different prices for different check-in dates
• Occupancy: Prices change with number of guests
• Board type: Room-only vs. breakfast included vs. all-inclusive
• Advance booking: Early booking discounts or last-minute pricing
• Supplier: Different suppliers may offer different rates for the same hotel

Rate Plan

A rate plan is a set of pricing rules for a specific room type. It includes:

• Base price
• Cancellation policies
• Payment requirements
• Booking restrictions
• Special conditions

Price Types

Type	Description
Net	The price you pay to the supplier (your cost)
Suggested	Recommended selling price (includes your margin)
Binding	Final price that cannot change (guaranteed)

Occupancy

Occupancy defines how many people will stay in a room and their composition.

Adults and Children

• Adults: Number of adult guests (typically 18+)
• Children: Number of children (ages specified separately)
• childrenAges: Array of ages for each child (required for pricing and policies)

Example

{
  "occupancies": [
    {
      "adults": 2,
      "children": 1,
      "childrenAges": [8]
    }
  ]
}

Standard vs Maximum Occupancy

• Standard occupancy: The typical occupancy for a room type
• Maximum occupancy: The maximum allowed occupancy (may require extra beds/supplements)

Board Types (Meal Plans)

Board refers to the meal plan included with the room. Common board codes:

Code	Name	Description
RO	Room Only	No meals included
BB	Bed & Breakfast	Breakfast included
HB	Half Board	Breakfast + dinner included
FB	Full Board	All meals included (breakfast, lunch, dinner)
AI	All Inclusive	All meals + drinks + snacks included

Board Selection

When searching, you can:

• Filter by specific board types
• See all available boards for each hotel
• Compare prices across different board types

Cancellation Policies

Cancellation policies define the rules and penalties for canceling a booking.

Policy Components

• Free cancellation deadline: Date/time before which cancellation is free
• Penalty types: How the penalty is calculated
  • NIGHTS: Charge for specific number of nights
  • PERCENT: Percentage of total booking value
  • IMPORT: Fixed amount in currency
• Non-refundable: Cannot be canceled for free (penalty always applies)

Example Policy

{
  "cancelPolicy": {
    "refundable": true,
    "cancelPenalties": [
      {
        "penaltyType": "PERCENT",
        "value": 50,
        "deadline": "2025-06-10T00:00:00Z"
      },
      {
        "penaltyType": "NIGHTS",
        "value": 1,
        "deadline": "2025-06-12T00:00:00Z"
      }
    ]
  }
}

Interpretation:

• Cancel before June 10: Free
• Cancel between June 10-12: 50% penalty
• Cancel after June 12: 1 night penalty

Booking Lifecycle

A booking goes through several states:

State	Description
PENDING	Booking request submitted, awaiting confirmation
CONFIRMED	Booking confirmed by supplier
ON_REQUEST	Supplier needs to confirm availability
CANCELLED	Booking has been cancelled
MODIFIED	Booking details have been changed

Multi-Supplier Concepts

Supplier / Provider

A supplier (also called provider) is a hotel inventory source:

• Bedbanks (Hotelbeds, GTA, etc.)
• Wholesalers
• Direct hotel connections
• GDS systems

Access ID

An access ID identifies a specific supplier connection configured in your Bundleport account. You use access IDs to:

• Specify which suppliers to query in a search
• Filter results by supplier
• Track which supplier provided each option

Normalization

Normalization is the process of converting supplier-specific data into Bundleport's standard format:

• Hotel codes mapped to Bundleport codes
• Room types standardized
• Board codes unified
• Pricing formats consistent
• Cancellation policies normalized

Deduplication

When the same hotel appears from multiple suppliers, Bundleport deduplicates by:

• Identifying the same hotel across suppliers
• Consolidating options
• Applying business rules to select the best option
• Presenting a single result to your application

Content vs Transactional Data

Content (Static/Semi-Static)

• Hotel information (name, description, amenities)
• Room types and descriptions
• Destinations and locations
• Boards and categories
• Update frequency: Daily or on-demand sync
• Use case: Display in search results, hotel detail pages

Transactional (Dynamic)

• Availability and pricing
• Booking confirmations
• Cancellation status
• Update frequency: Real-time per request
• Use case: Search, quote, book operations

Option Reference ID

An optionRefId is a unique identifier for a specific hotel option returned from a search. It represents:

• A specific hotel
• A specific room type
• A specific board type
• A specific price
• A specific supplier

You use optionRefId to:

• Quote the option (recheck pricing)
• Book the option
• Reference in subsequent operations

Important: optionRefId is only valid for a limited time (typically 4-5 minutes). Always quote immediately before booking.

Request Tracing

Tracing provides visibility into how your request was processed:

• Status: Overall request status (OK, ERROR, PARTIAL)
• Access spans: Per-supplier response details
  • Which suppliers were queried
  • Response status from each
  • Number of hotels returned
  • Processing time
• Warnings: Non-fatal issues (unmapped hotels, missing content, etc.)

Use tracing to:

• Debug integration issues
• Monitor supplier performance
• Identify data quality problems
• Optimize supplier selection

Next Steps

• Glossary - Complete list of terms
• Error Codes - All error codes explained
• Connect Hotels Overview - Start using the API