Booking Engine API

Last updated: March 23, 2026

Overview

The HotelBee Booking Engine API allows third-party applications to integrate with HotelBee's booking system. This API enables you to:

• Retrieve room type catalogs, availability, and pricing
• Search for available rooms across date ranges
• Create reservations directly in HotelBee
• Validate promo codes for discounts
• Compare OTA channel prices
• Power a guest portal with self-service check-in, invoice viewing, and order history

This is a RESTful API that returns JSON responses and uses standard HTTP response codes.

Base URL

All API requests should be made to:

https://app.hotelbee.co/api/booking-engine

Authentication

The Booking Engine API uses two authentication methods depending on the endpoint type.

Public Booking Engine Authentication

All public booking engine endpoints require API key authentication. API credentials are stored in a dedicated rest_api CouchDB database per property.

Include these headers with every request:

• Authorization (string, required): Bearer {api_key_token} — your API key (contact support@hotelbee.co to obtain)
• Property (string, required): Your property name (without the _hb suffix)
• Username (string, required): Username associated with your API key
• Content-Type (string, required for POST): application/json for POST requests

Example Authentication Headers

{
  "Authorization": "Bearer your-api-key-here",
  "Property": "myhotel",
  "Username": "booking_engine"
}

Guest Portal Authentication

Guest portal endpoints (except login and some public ones) require an additional JWT token obtained via the /guest-portal/login endpoint.

• X-Guest-Token (string, required): JWT token obtained from /guest-portal/login
• Property (string, required): Your property name (without the _hb suffix)

Alternatively, the guest token can be sent via the Authorization: Bearer {token} header instead of X-Guest-Token.

Token Details:

• Expiry: 7 days
• Claims: { clientId, property, type: "guest_portal" }

Error Handling

The API uses standard HTTP status codes:

• 200 OK — Request successful
• 400 Bad Request — Missing required data or validation error
• 401 Unauthorized — Authentication failed
• 404 Not Found — Resource or property not found
• 500 Internal Server Error — Server error

Error responses use this format:

{
  "error": "Description of what went wrong"
}

Public Endpoints

Get Availability

Retrieves room availability and pricing for a given date range. Use this to show available room types and their daily rates on your booking widget.

GET /availabilities — Fetches daily room availability and pricing for a date range. Auth required (API key).

Query Parameters

• startDate (string, required): Start date in YYYY-MM-DD format
• endDate (string, required): End date in YYYY-MM-DD format

Example Request

curl -X GET "https://app.hotelbee.co/api/booking-engine/availabilities?startDate=2026-04-01&endDate=2026-04-05" \
  -H "Authorization: Bearer your-api-key" \
  -H "Property: myhotel" \
  -H "Username: booking_engine"

Response 200 — Success

{
  "startDate": "2026-04-01",
  "endDate": "2026-04-05",
  "roomtypes": {
    "roomtype_2026-01-15T10:00:00Z": {
      "2026-04-01": {
        "price": 100,
        "includedCapacity": 2,
        "capacity": [
          { "name": "Adults", "price": 25 },
          { "name": "Children", "price": 15 }
        ]
      },
      "2026-04-02": {
        "price": 100,
        "includedCapacity": 2,
        "capacity": [
          { "name": "Adults", "price": 25 },
          { "name": "Children", "price": 15 }
        ]
      }
    }
  },
  "rates": {
    "rate_2026-01-20T08:00:00Z": {
      "roomtype_2026-01-15T10:00:00Z": {
        "2026-04-01": {
          "price": 90,
          "includedCapacity": 2,
          "capacity": [
            { "name": "Adults", "price": 20 }
          ]
        }
      }
    }
  },
  "roomtypeQuantities": {
    "roomtype_2026-01-15T10:00:00Z": 5
  }
}

Response 400 — Missing Parameters

{
  "error": "startDate and endDate are required"
}

Response Fields

• startDate (string): Requested start date
• endDate (string): Requested end date
• roomtypes (object): Map of room type ID → date → pricing (base rate pricing per day)
• rates (object): Map of rate ID → room type ID → date → pricing (rate-specific pricing per day)
• roomtypeQuantities (object): Map of room type ID → available room count

Pricing Object

• price (number): Base price per night for included capacity
• includedCapacity (integer): Number of guests included in the base price
• capacity (array): Extra guest charge tiers (name + price per additional guest)

Use Cases

• Display a date-range availability calendar
• Show pricing per night per room type
• Calculate total stay cost including extra guest charges
• Check room availability before creating a reservation

Get Room Types

Retrieves the complete room type catalog including details, amenities, images, bed types, services, and booking engine rates.

GET /roomtypes — Fetches all room types with full details, services, and rates. Auth required (API key).

Example Request

curl -X GET https://app.hotelbee.co/api/booking-engine/roomtypes \
  -H "Authorization: Bearer your-api-key" \
  -H "Property: myhotel" \
  -H "Username: booking_engine"

Response 200 — Success

[
  {
    "id": "roomtype_2026-01-15T10:00:00Z",
    "name": "Deluxe Room",
    "description": "Spacious room with sea view",
    "capacity": [
      { "name": "Adults", "price": 25 },
      { "name": "Children", "price": 15 }
    ],
    "maxCapacity": 4,
    "includedCapacity": 2,
    "price": 100,
    "images": [
      "https://storage.blob.core.windows.net/hotel/room1.jpg"
    ],
    "amenities": ["WiFi", "AC", "Mini Bar"],
    "meals": ["breakfast"],
    "bedtypes": [
      {
        "id": "bedtype_001",
        "name": "Double Bed",
        "capacity": 2,
        "quantity": 1
      }
    ],
    "bookingEngineServices": [
      {
        "id": "service_spa_001",
        "name": "Spa Access",
        "code": "SPA001",
        "calculationType": "per_night",
        "frequency": "nightly",
        "price": 25,
        "taxData": [
          {
            "taxId": "tax_001",
            "isIncluded": false,
            "tax": { "rate": 20, "category": "VAT" }
          }
        ]
      }
    ],
    "rates": [
      {
        "id": "rate_spring_001",
        "name": "Spring Rate",
        "roomTypes": ["roomtype_2026-01-15T10:00:00Z"],
        "meals": ["breakfast"],
        "maxCapacity": 4,
        "includedCapacity": 2,
        "minimumNights": 1,
        "maximumNights": 30,
        "minimumAdvance": 0,
        "maximumAdvance": 365,
        "availableTo": "all",
        "services": [
          {
            "serviceId": "service_spa_001",
            "isPriceIncluded": true,
            "isInvoiceItem": false,
            "service": {}
          }
        ],
        "lunchCalculation": null
      }
    ]
  }
]

Response Fields

• id (string): Unique room type identifier
• name (string): Room type display name
• description (string): Room type description
• capacity (array): Extra guest charge tiers
• maxCapacity (integer): Maximum guest capacity
• includedCapacity (integer): Guests included in base price
• price (number): Default base price
• images (array): Image URLs
• amenities (array): List of amenity names
• meals (array): Included meal plans
• bedtypes (array): Bed configurations with capacity
• bookingEngineServices (array): Optional add-on services with pricing and tax data
• rates (array): Booking engine rates (only rates with bookingEngineRate: true)

Rate Object Fields

• minimumNights (integer): Minimum stay length required
• maximumNights (integer): Maximum stay length allowed
• minimumAdvance (integer): Minimum days in advance to book
• maximumAdvance (integer): Maximum days in advance to book
• availableTo (string): Who can book this rate (e.g., "all")
• services (array): Services included/available with this rate

Get Configuration

Retrieves all booking engine configuration including branding, footer, language settings, property metadata, terms, and payment methods.

GET /config — Fetches booking engine configuration and branding. Auth required (API key).

Example Request

curl -X GET https://app.hotelbee.co/api/booking-engine/config \
  -H "Authorization: Bearer your-api-key" \
  -H "Property: myhotel" \
  -H "Username: booking_engine"

Response 200 — Success

{
  "branding": {
    "hotelTitle": "Hotel Riviera",
    "showHotelTitle": true,
    "logo": "https://storage.blob.core.windows.net/hotel/logo.png",
    "headerColor": "#1a237e",
    "buttonColor": "#ff6f00",
    "backgroundImage": "https://storage.blob.core.windows.net/hotel/bg.jpg",
    "font": "Roboto",
    "showPropertyAddress": true
  },
  "footer": {
    "enabled": true,
    "text": "© 2026 Hotel Riviera",
    "links": [],
    "contactEmail": "info@hotelriviera.com",
    "contactPhone": "+355 69 123 4567",
    "aboutUsText": "A luxury seaside hotel...",
    "locationLink": "https://maps.google.com/?q=..."
  },
  "language": {
    "enabledLanguages": ["en", "sq", "it"],
    "defaultLanguage": "sq",
    "showFlags": true
  },
  "propertyMeta": {
    "name": "Hotel Riviera",
    "address": "Rruga e Plazhit",
    "city": "Durrës",
    "region": "Albania",
    "zip": "2001",
    "country": "AL",
    "email": "info@hotelriviera.com",
    "website": "https://hotelriviera.com",
    "phone": "+355 69 123 4567"
  },
  "terms": {
    "cancellationTerms": [],
    "bookingTerms": [],
    "confirmationMessage": [],
    "showCancellationSummary": true
  },
  "paymentMethods": [
    {
      "id": "method_card_001",
      "name": "Credit Card",
      "method": "card",
      "instructions": "We accept Visa and Mastercard"
    },
    {
      "id": "method_bank_001",
      "name": "Bank Transfer",
      "method": "bank",
      "instructions": "Transfer to IBAN: AL00..."
    }
  ],
  "guestPortalInformation": {
    "locationLink": "https://maps.google.com/?q=...",
    "wifiName": "HotelRiviera_WiFi",
    "wifiPassword": "welcome2026",
    "goodToKnow": "Breakfast is served 7-10am in the main restaurant"
  }
}

Response Fields

• branding (object): UI branding settings (logo, colors, fonts, background)
• footer (object): Footer content (contact info, about text, links)
• language (object): Language settings (enabled languages, default, flags)
• propertyMeta (object): Hotel property details (name, address, contact)
• terms (object): Booking and cancellation terms
• paymentMethods (array): Active payment methods (filtered to bank, cash, card only)
• guestPortalInformation (object): Guest portal information (WiFi, location, notes)

Important Notes

• Payment Methods: Only methods with isActive: true and method type in [bank, cash, card] are returned
• Branding: Use these values to style your booking engine UI to match the hotel's brand

Get Currencies

Retrieves all active currencies and identifies the default currency for the property.

GET /currencies — Fetches active currencies and default currency. Auth required (API key).

Example Request

curl -X GET https://app.hotelbee.co/api/booking-engine/currencies \
  -H "Authorization: Bearer your-api-key" \
  -H "Property: myhotel" \
  -H "Username: booking_engine"

Response 200 — Success

{
  "currencies": [
    {
      "id": "currency_001",
      "currency": "ALL",
      "currencyName": "Albanian Lek",
      "rate": 1.0,
      "active": true
    },
    {
      "id": "currency_002",
      "currency": "EUR",
      "currencyName": "Euro",
      "rate": 0.0089,
      "active": true
    }
  ],
  "defaultCurrency": {
    "id": "currency_001",
    "currency": "ALL",
    "currencyName": "Albanian Lek",
    "rate": 1.0,
    "active": true
  }
}

Response Fields

• currencies (array): All active currencies with exchange rates
• defaultCurrency (object): The property's default currency

Currency Object

• id (string): Currency identifier
• currency (string): ISO 4217 currency code (e.g., "ALL", "EUR", "USD")
• currencyName (string): Full currency name
• rate (number): Exchange rate relative to default currency
• active (boolean): Whether currency is active

Create Reservation

Creates a new reservation in HotelBee. This is the core endpoint for booking rooms through the booking engine.

POST /reservations — Creates a new reservation with room assignment and optional payment. Auth required (API key). Content-Type: application/json.

Request Parameters

• checkIn (string, required): Check-in date in YYYY-MM-DD format
• checkOut (string, required): Check-out date in YYYY-MM-DD format
• roomTypes (array, required): Array of room type bookings (at least one required)
• clientDetails (object, required): Guest contact information
• specialRequests (string, optional): Special requests or notes
• selectedPaymentMethod (object, optional): Payment method selection
• cardDetails (object, conditional): Required if payment method is card
• discount (object, optional): Discount to apply (from promo code validation)

roomTypes[] Object

• roomTypeId (string, required): Room type ID (from /roomtypes endpoint)
• rateId (string, optional): Rate ID (from /roomtypes rates array)
• adults (integer, required): Number of adults
• children (integer, optional): Number of children
• quantity (integer, required): Number of rooms of this type
• services (array, optional): Selected add-on services ([{ serviceId }])

clientDetails Object

• firstName (string, required): Guest first name
• lastName (string, required): Guest last name
• email (string, required): Guest email address
• phone (string, optional): Phone number
• city (string, optional): City
• country (string, optional): Country code (e.g., "AL", "US")
• addressLine (string, optional): Street address
• zip (string, optional): Postal code
• state (string, optional): State/province
• company (string, optional): Company name

cardDetails Object (required when payment method is card)

• number (string, required): Card number
• expMonth (string, required): Expiry month (e.g., "12")
• expYear (string, required): Expiry year (e.g., "2028")
• cvv (string, required): CVV/CVC code
• holderName (string, required): Name on card

Example Request

curl -X POST https://app.hotelbee.co/api/booking-engine/reservations \
  -H "Authorization: Bearer your-api-key" \
  -H "Property: myhotel" \
  -H "Username: booking_engine" \
  -H "Content-Type: application/json" \
  -d '{
    "checkIn": "2026-04-01",
    "checkOut": "2026-04-05",
    "roomTypes": [
      {
        "roomTypeId": "roomtype_2026-01-15T10:00:00Z",
        "rateId": "rate_spring_001",
        "adults": 2,
        "children": 1,
        "quantity": 1,
        "services": [
          { "serviceId": "service_spa_001" }
        ]
      }
    ],
    "clientDetails": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "phone": "+355 69 123 4567",
      "country": "US"
    },
    "specialRequests": "Non-smoking room preferred",
    "selectedPaymentMethod": {
      "id": "method_bank_001",
      "name": "Bank Transfer",
      "method": "bank"
    }
  }'

Response 200 — Success

{
  "reservationId": "reservations_2026-03-24T14:30:00Z",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "PENDING"
}

Response 400 — Validation Error

{
  "error": "checkIn, checkOut, and roomTypes are required"
}

Other possible errors:

• "card_details_required" — Payment method is card but no card details provided
• "room_not_available" — Requested rooms cannot be assigned (no availability)

Reservation Processing Flow

When a reservation is successfully submitted:

1. Input Validation: checkIn, checkOut, and roomTypes are validated
2. Availability Check: Loads availability for the date range and verifies rooms exist
3. Client Resolution: Finds existing client by email or creates a new client record
4. Room Assignment: Assigns specific rooms from available pool (removes from availability as assigned)
5. Price Calculation: Calculates daily prices including extra guest charges based on capacity tiers
6. Service Processing: Adds selected services with tax calculations
7. Discount Application: Applies percentage or fixed discount if provided
8. Card Vault: Stores card details securely if card payment selected
9. Reservation Created: Document stored with status PENDING and auto-generated UUID
10. Event Emission: Downstream event emitted for channel manager sync and notifications

Important Notes

• UUID: The uuid in the response is used for guest portal login
• Client Deduplication: If a client with the same email exists, the existing record is used
• Race Condition Protection: Final availability check is performed before confirming the reservation
• Card Security: Card details are stored in a secure vault, not in the reservation document

Validate Promo Code

Validates a promotional code and returns the discount details if valid.

POST /promocode/validate — Validates a promo code and returns discount info. Auth required (API key). Content-Type: application/json.

Request Parameters

• code (string, required): The promotional code to validate

Example Request

curl -X POST https://app.hotelbee.co/api/booking-engine/promocode/validate \
  -H "Authorization: Bearer your-api-key" \
  -H "Property: myhotel" \
  -H "Username: booking_engine" \
  -H "Content-Type: application/json" \
  -d '{"code": "SUMMER10"}'

Response 200 — Valid Code

{
  "valid": true,
  "discount": {
    "type": "percentage",
    "value": 10
  }
}

Response 200 — Invalid Code

{
  "valid": false
}

Discount Types

• percentage: Percentage discount (value between 0-100)
• total: Fixed amount discount (subtracted from total)

Important Notes

• Pass the returned discount object directly to the POST /reservations endpoint
• Discount type normalization: internal types "fixed" and "total" are both returned as "total"
• Percentage values are clamped between 0 and 100

Search Clients

Searches for existing clients by email prefix. Useful for auto-filling guest details during booking.

GET /clients/search — Searches clients by email prefix. Auth required (API key).

Query Parameters

• q (string, required): Email search prefix (minimum 2 characters)

Example Request

curl -X GET "https://app.hotelbee.co/api/booking-engine/clients/search?q=john@" \
  -H "Authorization: Bearer your-api-key" \
  -H "Property: myhotel" \
  -H "Username: booking_engine"

Response 200 — Success

{
  "clients": [
    {
      "id": "client_001",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "phone": "+355 69 123 4567",
      "city": "New York",
      "country": "US",
      "addressLine": "123 Main St",
      "zip": "10001",
      "state": "NY",
      "company": "Acme Corp"
    }
  ]
}

Use Cases

• Auto-complete guest details during the booking flow
• Pre-fill returning guest information

Get OTA Prices

Retrieves pricing from OTA channels (e.g., Booking.com, Expedia) via Channex integration. Use this to display price comparisons.

GET /ota-prices — Fetches OTA channel prices for comparison. Auth required (API key).

Query Parameters

• startDate (string, required): Start date in YYYY-MM-DD format
• endDate (string, required): End date in YYYY-MM-DD format
• roomTypeId (string, optional): Filter to a specific room type

Example Request

curl -X GET "https://app.hotelbee.co/api/booking-engine/ota-prices?startDate=2026-04-01&endDate=2026-04-05" \
  -H "Authorization: Bearer your-api-key" \
  -H "Property: myhotel" \
  -H "Username: booking_engine"

Response 200 — Success (Channex configured)

{
  "available": true,
  "channels": [
    {
      "channelId": "ch_001",
      "channelName": "Booking.com",
      "channel": "booking_com",
      "channelGroup": "otas",
      "roomTypes": [
        {
          "roomTypeId": "roomtype_2026-01-15T10:00:00Z",
          "roomTypeName": "Deluxe Room",
          "ratePlanName": "Standard Rate",
          "currency": "EUR",
          "rates": {
            "2026-04-01": 120.50,
            "2026-04-02": 120.50,
            "2026-04-03": 125.00,
            "2026-04-04": 125.00
          },
          "totalPrice": 491.00,
          "nightlyAverage": 122.75,
          "nights": 4
        }
      ]
    }
  ]
}

Response 200 — Channex not configured

{
  "available": false,
  "channels": []
}

Important Notes

• Requires Channex: This endpoint only works if the property has an active Channex integration
• Caching: Channel data is cached for 1 hour, rate plans for 1 hour, restrictions for 15 minutes
• Price Multipliers: OTA prices include channel-specific price adjustments (increase/decrease by % or fixed amount)
• Room Type Mapping: Internal room types are matched to Channex room types via channexId

Guest Portal Endpoints

The Guest Portal provides a self-service interface for guests to view their reservations, invoices, orders, and perform online check-in.

Authentication: Guest portal endpoints that require auth need both the API key headers AND a guest JWT token obtained from /guest-portal/login.

Public endpoints (no guest token required): /guest-portal/information, /guest-portal/things-to-do, /guest-portal/services, /guest-portal/pospoints

Guest Portal Login

Authenticates a guest using their reservation UUID and last name. Returns a JWT token for subsequent guest portal requests.

POST /guest-portal/login — Authenticates a guest and returns a JWT token. Auth required (API key only — no guest token needed). Content-Type: application/json.

Request Parameters

• uuid (string, required): Reservation UUID (from reservation confirmation)
• lastName (string, required): Primary guest's last name (case-sensitive match)

Example Request

curl -X POST https://app.hotelbee.co/api/booking-engine/guest-portal/login \
  -H "Authorization: Bearer your-api-key" \
  -H "Property: myhotel" \
  -H "Username: booking_engine" \
  -H "Content-Type: application/json" \
  -d '{"uuid": "a1b2c3d4-e5f6-7890", "lastName": "Doe"}'

Response 200 — Success

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "client": {
    "_id": "client_001",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phone": "+355 69 123 4567"
  }
}

Response 401 — Invalid Credentials

{
  "error": "Invalid UUID or last name"
}

Important Notes

• Token Expiry: The JWT token is valid for 7 days
• Token Usage: Include the token as X-Guest-Token header or Authorization: Bearer {token} in subsequent guest portal requests
• UUID Source: The UUID is returned in the POST /reservations response and typically included in the confirmation email

Get Guest Profile

Retrieves the authenticated guest's profile information.

GET /guest-portal/me — Returns the authenticated guest's client profile. Auth required (API key + guest token).

Example Request

curl -X GET https://app.hotelbee.co/api/booking-engine/guest-portal/me \
  -H "Authorization: Bearer your-api-key" \
  -H "Property: myhotel" \
  -H "Username: booking_engine" \
  -H "X-Guest-Token: eyJhbGci..."

Response 200 — Success

{
  "_id": "client_001",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phone": "+355 69 123 4567",
  "referenceTitle": "Mr.",
  "birthdate": "1980-01-15",
  "nationality": "US",
  "company": "Acme Corp",
  "addressLine": "123 Main St",
  "city": "New York",
  "zip": "10001",
  "state": "NY",
  "country": "US",
  "IDType": "Passport",
  "IDNumber": "A12345678",
  "dateOfIssue": "2015-01-01",
  "dateOfExpiry": "2025-01-01"
}

Get Guest Reservations

Retrieves all reservations linked to the authenticated guest, sorted by check-in date.

GET /guest-portal/reservations — Returns all reservations for the authenticated guest. Auth required (API key + guest token).

Example Request

curl -X GET https://app.hotelbee.co/api/booking-engine/guest-portal/reservations \
  -H "Authorization: Bearer your-api-key" \
  -H "Property: myhotel" \
  -H "Username: booking_engine" \
  -H "X-Guest-Token: eyJhbGci..."

Response 200 — Success

[
  {
    "_id": "reservations_2026-03-24T14:30:00Z",
    "uuid": "a1b2c3d4-e5f6-7890",
    "checkin": "2026-04-01",
    "checkout": "2026-04-05",
    "status": "APPROVED",
    "totalPrice": 500.00,
    "invoiceCurrency": "EUR",
    "rooms": [
      {
        "roomId": "room_101",
        "name": "Room 101"
      }
    ],
    "clientsData": [
      {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com"
      }
    ]
  }
]

Important Notes

• clientsData: Only included for APPROVED reservations with future check-in dates (for online check-in eligibility)
• Sorting: Results are sorted by check-in date
• Room Names: Room IDs are resolved to human-readable room names

Get Guest Invoices

Retrieves all invoices linked to the authenticated guest.

GET /guest-portal/invoices — Returns all invoices for the authenticated guest. Auth required (API key + guest token).

Response 200 — Success

[
  {
    "_id": "invoice_001",
    "number": "INV-001",
    "serial": "2026",
    "clientName": "John Doe",
    "date": "2026-04-01",
    "status": "paid",
    "totalPrice": 500.00,
    "invoiceCurrency": "EUR",
    "tableData": [
      {
        "itemName": "Room 101 - Deluxe Room",
        "description": "4 nights (Apr 1 - Apr 5)",
        "quantity": 1,
        "unit": "night",
        "price": 450.00
      },
      {
        "itemName": "Spa Access",
        "description": "4 nights",
        "quantity": 4,
        "unit": "night",
        "price": 25.00
      }
    ]
  }
]

Get Guest Orders

Retrieves all POS orders associated with the guest's reservations.

GET /guest-portal/orders — Returns POS orders for all guest reservations. Auth required (API key + guest token).

Response 200 — Success

[
  {
    "_id": "order_001",
    "totalPrice": 75.50,
    "subtotal": 70.00,
    "status": "completed",
    "createdAt": "2026-04-02T10:30:00Z",
    "reservationId": "reservations_2026-03-24T14:30:00Z",
    "pospointId": "pospoint_001",
    "currency": "EUR",
    "customerName": "Restaurant",
    "products": [
      {
        "productId": "product_001",
        "name": "Coffee",
        "quantity": 2,
        "price": 5.00,
        "note": "Extra hot"
      },
      {
        "productId": "product_002",
        "name": "Club Sandwich",
        "quantity": 1,
        "price": 15.00,
        "note": ""
      }
    ]
  }
]

Important Notes

• Orders are fetched across all reservations linked to the guest
• Product names and POS point currencies are resolved via batch lookups

Online Check-in

Performs online check-in for an eligible reservation. Updates guest details and changes reservation status.

POST /guest-portal/checkin — Performs online check-in and updates guest information. Auth required (API key + guest token). Content-Type: application/json.

Request Parameters

• reservationId (string, required): Reservation ID to check in
• clientsData (object, required): Map of client ID → updated guest details

clientsData[clientId] Object

• referenceTitle (string, optional): Title (Mr., Mrs., Ms., etc.)
• firstName (string, optional): First name
• lastName (string, optional): Last name
• country (string, optional): Country code
• email (string, optional): Email address
• phone (string, optional): Phone number
• IDType (string, optional): ID document type (Passport, ID Card, etc.)
• IDNumber (string, optional): ID document number
• birthdate (string, optional): Date of birth (YYYY-MM-DD)
• nationality (string, optional): Nationality
• dateOfIssue (string, optional): ID issue date (YYYY-MM-DD)
• dateOfExpiry (string, optional): ID expiry date (YYYY-MM-DD)

Example Request

curl -X POST https://app.hotelbee.co/api/booking-engine/guest-portal/checkin \
  -H "Authorization: Bearer your-api-key" \
  -H "Property: myhotel" \
  -H "Username: booking_engine" \
  -H "X-Guest-Token: eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "reservationId": "reservations_2026-03-24T14:30:00Z",
    "clientsData": {
      "client_001": {
        "referenceTitle": "Mr.",
        "firstName": "John",
        "lastName": "Doe",
        "country": "US",
        "IDType": "Passport",
        "IDNumber": "A12345678",
        "birthdate": "1980-01-15",
        "nationality": "US"
      }
    }
  }'

Response 200 — Success

{
  "success": true,
  "reservation": {
    "_id": "reservations_2026-03-24T14:30:00Z",
    "status": "CHECKIN",
    "checkin": "2026-04-01",
    "checkout": "2026-04-05"
  }
}

Response 400 / 404 — Error

{
  "error": "Reservation not eligible for check-in"
}

Eligibility Rules

• Reservation must have status APPROVED
• Check-in date must be today or in the future

Processing Details

1. Validates reservation eligibility
2. Updates client documents with provided fields
3. Changes reservation status to CHECKIN
4. Emits RESERVATION_STATUS_CHANGED event (triggers channel manager sync, lock system updates)
5. Publishes real-time update via Redis pub/sub

Get Property Information (Public)

Retrieves general property information for the guest portal. No guest token required.

GET /guest-portal/information — Returns guest portal information settings. Auth required (API key only — no guest token needed).

Response 200 — Success

{
  "locationLink": "https://maps.google.com/?q=...",
  "wifiName": "HotelRiviera_WiFi",
  "wifiPassword": "welcome2026",
  "goodToKnow": "Breakfast is served 7-10am in the main restaurant"
}

Get Things To Do (Public)

Retrieves activities and attractions for guests. No guest token required.

GET /guest-portal/things-to-do — Returns activities and attractions. Auth required (API key only — no guest token needed).

Response 200 — Success

[
  {
    "_id": "thing_001",
    "title": "City Walking Tour",
    "description": "A guided tour of the old city center",
    "location": "Old Town Square",
    "category": "tours",
    "images": ["https://storage.blob.core.windows.net/hotel/tour1.jpg"]
  }
]

Get Services (Public)

Retrieves hotel services available for booking. No guest token required.

GET /guest-portal/services — Returns booking-engine-enabled services. Auth required (API key only — no guest token needed).

Response 200 — Success

[
  {
    "_id": "service_spa_001",
    "name": "Spa Access",
    "description": "Full access to spa and wellness facilities",
    "price": 50.00,
    "calculationType": "per_night",
    "frequency": "nightly",
    "images": ["https://storage.blob.core.windows.net/hotel/spa.jpg"]
  }
]

Important Notes

• Only services with bookingEngineEnabled: true are returned
• Uses bookingEnginePrice if set, otherwise falls back to price
• Uses bookingEngineImages if set, otherwise uses default images

Get POS Points (Public)

Retrieves POS points that have online menu enabled. No guest token required.

GET /guest-portal/pospoints — Returns POS points with online menu enabled. Auth required (API key only — no guest token needed).

Response 200 — Success

[
  {
    "_id": "pospoint_001",
    "name": "Restaurant"
  },
  {
    "_id": "pospoint_002",
    "name": "Pool Bar"
  }
]

Important Notes

• Only POS points with hasOnlineMenu: true are returned

Integration Workflow

Booking Engine Integration Steps

1. Get Credentials: Contact support@hotelbee.co with your property name
2. Fetch Config: Get branding and settings (GET /config)
3. Fetch Room Types: Retrieve room catalog with amenities and rates (GET /roomtypes)
4. Fetch Currencies: Get supported currencies (GET /currencies)
5. Check Availability: Query date-range availability (GET /availabilities)
6. Build Booking UI: Create your booking flow with room selection, date picker, and guest form
7. Validate Promo Code (optional): Check promo codes (POST /promocode/validate)
8. Search Clients (optional): Auto-fill returning guest details (GET /clients/search)
9. Compare OTA Prices (optional): Show price comparisons (GET /ota-prices)
10. Create Reservation: Submit the booking (POST /reservations)

Guest Portal Integration Steps

1. Guest Login: Authenticate with UUID + last name (POST /guest-portal/login)
2. Load Profile: Show guest details (GET /guest-portal/me)
3. Show Reservations: Display booking history (GET /guest-portal/reservations)
4. Show Invoices: Display billing (GET /guest-portal/invoices)
5. Show Orders: Display POS order history (GET /guest-portal/orders)
6. Online Check-in: Allow self-service check-in (POST /guest-portal/checkin)
7. Property Info: Show hotel info, WiFi, activities (GET /guest-portal/information, /things-to-do, /services)

Recommended Caching Strategy

• Config & Room Types: Cache for 1-4 hours (change infrequently)
• Currencies: Cache for 24 hours
• Availability: Always fetch fresh (real-time inventory)
• OTA Prices: API caches internally (channels: 1hr, rates: 1hr, restrictions: 15min)

Integration Example

JavaScript/Node.js:

const API_BASE = 'https://app.hotelbee.co/api/booking-engine';
const headers = {
  'Authorization': 'Bearer your-api-key',
  'Property': 'myhotel',
  'Username': 'booking_engine',
  'Content-Type': 'application/json'
};

// Check availability
async function getAvailability(startDate, endDate) {
  const url = `${API_BASE}/availabilities?startDate=${startDate}&endDate=${endDate}`;
  const response = await fetch(url, { headers });
  if (!response.ok) throw new Error(`Failed: ${response.status}`);
  return await response.json();
}

// Create reservation
async function createReservation(bookingData) {
  const response = await fetch(`${API_BASE}/reservations`, {
    method: 'POST',
    headers,
    body: JSON.stringify(bookingData)
  });
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error || 'Booking failed');
  }
  return await response.json();
}

// Guest portal login
async function guestLogin(uuid, lastName) {
  const response = await fetch(`${API_BASE}/guest-portal/login`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ uuid, lastName })
  });
  if (!response.ok) throw new Error('Login failed');
  return await response.json();
}

API Limitations

• Reservations are create-only: Modifications and cancellations must be done through the HotelBee PMS interface
• No real-time catalog updates: Room type and rate changes are not pushed. Poll the endpoints periodically
• No payment processing: Card details are stored for the hotel to process manually. No real-time payment gateway integration
• Single property per credential: Each API credential is scoped to one property
• OTA prices require Channex: The /ota-prices endpoint only works with an active Channex integration
• Guest portal scope: Guests can only view their own reservations, invoices, and orders

Support

For API support, technical questions, or to request API credentials:

Email: support@hotelbee.co

Response Time: We typically respond within 24 hours on business days

Common Questions

Q: How do I get API credentials?

A: Contact support@hotelbee.co with your property name and intended use case.

Q: How does the guest portal login work?

A: Guests authenticate with the reservation UUID (sent in their confirmation email) and their last name. This returns a JWT token valid for 7 days.

Q: Can guests check in online?

A: Yes, for APPROVED reservations where the check-in date is today or in the future. The check-in endpoint updates guest details and changes reservation status to CHECKIN.

Q: How are extra guest charges calculated?

A: Each room type has an includedCapacity (guests included in base price) and capacity tiers (extra charges per guest type). If the number of guests exceeds included capacity, extra charges are added per night.

Q: What is the difference between roomtypes pricing and rates pricing?

A: Room types have a default base price. Rates provide alternative pricing that may vary by date, season, or booking conditions (minimum nights, advance booking, etc.). Rates marked with bookingEngineRate: true are available to the booking engine.

Q: How do promo codes work?

A: Validate a code via POST /promocode/validate. If valid, pass the returned discount object to POST /reservations. The discount is applied as either a percentage or fixed amount off the total.

Q: Can I integrate with multiple properties?

A: Yes, you need separate credentials for each property. Include the correct Property header with each request.