Skip to main content

Data Models

This document describes the key data models used throughout Bundleport APIs. For complete schemas, see the API Reference.

Hotel​

Represents a hotel property.

interface Hotel {
  code: string;                    // Bundleport hotel code
  name: string;                    // Hotel name
  descriptions?: HotelDescription[]; // Multi-language descriptions
  category?: string;               // Category code
  starRating?: number;             // 1-5 stars
  location: Location;             // Address and coordinates
  amenities?: Amenity[];           // Hotel amenities
  media?: Media[];                 // Images and videos
  contact?: Contact;               // Contact information
  providerCode?: string;           // Supplier identifier
  providerHotelCode?: string;      // Supplier-specific code
  destinationCode?: string;        // Destination code
  boardCodes?: string[];           // Available board types
  rooms?: RoomData[];              // Available room types
}

Room​

Represents a room type.

interface Room {
  code: string;                    // Bundleport room code
  name: string;                    // Room name
  descriptions?: Text[];           // Multi-language descriptions
  maxOccupancy: number;            // Maximum guests
  bedType?: string;                // Type of bed
  sizeSqM?: number;                // Room size in square meters
  images?: RoomImage[];            // Room images
  occupancy?: Occupancy;            // Occupancy details
  beds?: Bed[];                    // Bed configuration
  providerCode?: string;          // Supplier identifier
  providerRoomCode?: string;       // Supplier-specific code
}

Option​

Represents a bookable hotel option from a search.

interface Option {
  optionRefId: string;             // Unique identifier for this option
  hotel: Hotel;                    // Hotel information
  rooms: RoomOption[];             // Room options with pricing
  price: Price;                    // Total price
  cancelPolicy?: CancelPolicy;     // Cancellation policy
  supplier: SupplierInfo;          // Supplier details
}

RoomOption​

A specific room option within an Option.

interface RoomOption {
  description: string;             // Room description
  boardCode: string;               // Board type (RO, BB, HB, FB, AI)
  price: Price;                    // Room price
  cancelPolicy?: CancelPolicy;     // Room-specific cancellation policy
  occupancyRefId: number;          // Reference to occupancy configuration
}

Price​

Pricing information.

interface Price {
  currency: string;                // ISO 4217 currency code (EUR, USD, etc.)
  net: number;                     // Net price (your cost)
  suggested?: number;              // Suggested selling price
  binding?: boolean;               // Is price binding (guaranteed)?
  breakdown?: PriceBreakdown;       // Detailed price breakdown
}

PriceBreakdown​

Detailed price components.

interface PriceBreakdown {
  base: number;                    // Base room price
  taxes?: number;                  // Taxes
  fees?: number;                   // Fees
  supplements?: Supplement[];      // Additional charges
  discounts?: Discount[];         // Applied discounts
}

Occupancy​

Guest configuration.

interface Occupancy {
  adults: number;                  // Number of adults
  children?: number;               // Number of children
  childrenAges?: number[];          // Ages of children (required if children > 0)
  total: number;                   // Total guests (adults + children)
}

Stay​

Date range for hotel stay.

interface Stay {
  checkIn: string;                 // Check-in date (YYYY-MM-DD)
  checkOut: string;                 // Check-out date (YYYY-MM-DD)
  nights?: number;                  // Number of nights (calculated)
}

Destination​

Location where hotels are located.

interface Destination {
  code: string;                     // Destination code
  name: string;                    // Destination name
  type: string;                    // Type: city, region, airport, etc.
  location?: Location;              // Geographic location
  parent?: string;                  // Parent destination code
  children?: string[];              // Child destination codes
  texts?: Text[];                   // Multi-language descriptions
}

Location​

Geographic location and address.

interface Location {
  address?: string;                 // Street address
  city?: string;                   // City name
  state?: string;                   // State or province
  countryCode?: string;            // ISO 3166-1 alpha-2 country code
  postalCode?: string;             // Postal/ZIP code
  latitude?: number;               // Latitude coordinate
  longitude?: number;              // Longitude coordinate
}

CancelPolicy​

Cancellation policy details.

interface CancelPolicy {
  refundable: boolean;             // Can be cancelled for free?
  cancelPenalties?: CancelPenalty[]; // Penalty rules
  description?: string;            // Human-readable description
}

interface CancelPenalty {
  penaltyType: 'NIGHTS' | 'PERCENT' | 'IMPORT'; // Penalty calculation type
  value: number;                    // Penalty amount
  deadline: string;                 // ISO 8601 deadline (before this date)
  currency?: string;               // Currency for IMPORT type
}

Booking​

A confirmed or pending reservation.

interface Booking {
  id: string;                      // Bundleport booking ID
  status: BookingStatus;           // Current status
  reference: BookingReference;     // Booking references
  hotel: Hotel;                    // Hotel information
  stay: Stay;                      // Check-in/check-out dates
  rooms: BookingRoom[];            // Booked rooms
  holder: Holder;                  // Booking holder information
  price: Price;                    // Final price
  cancelPolicy?: CancelPolicy;      // Cancellation policy
  remarks?: string[];              // Booking remarks
  createdAt: string;               // ISO 8601 creation timestamp
  updatedAt: string;               // ISO 8601 last update timestamp
}

type BookingStatus = 
  | 'CONFIRMED'
  | 'PENDING'
  | 'ON_REQUEST'
  | 'CANCELLED'
  | 'MODIFIED'
  | 'FAILED';

BookingReference​

References for a booking.

interface BookingReference {
  bookingID: string;               // Bundleport booking ID
  clientReference?: string;        // Your internal reference
  providerReference?: string;      // Supplier confirmation number
  confirmationNumber?: string;     // Hotel confirmation number
}

BookingRoom​

A room within a booking.

interface BookingRoom {
  description: string;             // Room description
  boardCode: string;               // Board type
  paxes: Pax[];                    // Guest information
  confirmationReference?: string;   // Room-specific confirmation
  price?: Price;                   // Room price
}

Holder​

Booking holder (main guest).

interface Holder {
  name: string;                    // First name
  surname: string;                  // Last name
  email: string;                   // Email address
  phone?: string;                  // Phone number
  nationality?: string;            // ISO 3166-1 alpha-2 country code
}

Pax​

Guest information.

interface Pax {
  name: string;                    // First name
  surname: string;                  // Last name
  age?: number;                     // Age (for children)
  type?: 'ADULT' | 'CHILD';        // Guest type
}

Tracing​

Request processing visibility.

interface Tracing {
  status: 'OK' | 'PARTIAL' | 'ERROR'; // Overall status
  accessSpans: AccessSpan[];        // Per-supplier details
  processTime?: number;            // Processing time in milliseconds
}

interface AccessSpan {
  access: string;                  // Access ID (supplier identifier)
  status: 'OK' | 'ERROR' | 'TIMEOUT';
  hotelsRequested?: number;        // Hotels requested from supplier
  hotelsReturned?: number;         // Hotels returned by supplier
  errorCode?: string;              // Error code if status is ERROR
  errorDescription?: string;       // Error description
  processTime?: number;            // Supplier response time
}

Warning​

Non-fatal issue that doesn't prevent request success.

interface Warning {
  code: string;                    // Warning code
  type: 'INFO' | 'WARNING' | 'ERROR';
  description: string;             // Human-readable description
  field?: string;                  // Related field (if applicable)
}

Error​

Error information.

interface Error {
  code: string;                    // Error code
  type: 'CLIENT' | 'SERVER';       // Error type
  message: string;                  // Human-readable message
  description?: string;            // Detailed description
  details?: Record<string, any>;   // Additional error details
  field?: string;                  // Related field (if applicable)
}

Common Field Types​

Text​

Multi-language text content.

interface Text {
  type?: string;                   // Text type (description, shortDescription, etc.)
  languageCode: string;            // ISO 639-1 language code
  text: string;                    // Text content
}

Media​

Image or video media.

interface Media {
  url: string;                     // Media URL
  mediaType?: 'IMAGE' | 'VIDEO';   // Media type
  caption?: string;                // Caption
  width?: number;                  // Width in pixels
  height?: number;                 // Height in pixels
  orderIndex?: number;             // Display order
  isPrimary?: boolean;             // Is primary image?
}

Amenity​

Hotel or room amenity.

interface Amenity {
  code: string;                    // Amenity code
  name?: string;                   // Amenity name
  type?: string;                   // Amenity type/category
  description?: string;            // Description
}

Next Steps​