Order API

Last updated: March 17, 2026 — Verified against codebase

Overview

The HotelBee Order API allows third-party applications to integrate with HotelBee's POS system. This API enables you to:

• Retrieve product catalogs and categories
• Send orders directly to HotelBee POS points
• Integrate with table management and room service systems

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

Authentication

Authentication is required for all API endpoints. 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": "pos_system"
}

API Credential Structure

API keys are stored as documents in a rest_api database:

{
  "_id": "api_key_pos_system",
  "key": "your_secret_api_key_token",
  "vendor": "pos"
}

The vendor field determines which endpoint handlers are used:

• "pos" — Standard POS system integration
• "onlineMenu" — Online menu / self-ordering integration

ID Format

Important: IDs returned by this API are in millisecond timestamp format (JavaScript Date.now() style).

Internally, HotelBee stores document IDs as {resource}_{ISO8601}Z (e.g., products_2026-03-17T14:32:45.123Z). The API automatically converts these to milliseconds for external consumption and converts back when receiving them.

Rate Limiting

The API currently does not enforce rate limiting, but we recommend limiting requests to a reasonable frequency. If you need to make high-volume requests, please contact support.

Error Handling

The API uses standard HTTP status codes:

• 200 OK — Request successful (GET operations)
• 201 Created — Resource created (POST operations)
• 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"
}

Endpoints

Get All Product Categories

Retrieves all product categories configured in your HotelBee account. Use this endpoint to organize products and build your menu structure.

GET /productCategories — Fetches all product categories for the authenticated property. Auth required.

Response Fields

• id (integer): Unique category identifier (millisecond timestamp)
• name (string): Category display name
• description (string): Optional category description

Example Request

curl -X GET https://app.hotelbee.co/api/productCategories \
  -H "Authorization: Bearer your-api-key" \
  -H "Property: myhotel" \
  -H "Username: pos_system"

Response 200 — Success

[
  {
    "id": 1675706008255,
    "name": "Food",
    "description": ""
  },
  {
    "id": 1684780033273,
    "name": "Drinks",
    "description": ""
  },
  {
    "id": 1705757825253,
    "name": "Wine",
    "description": ""
  }
]

Response 400 — Missing Property

{
  "error": "Property Missing"
}

Response 404 — Property Not Found

{
  "error": "Property Not Found"
}

Use Cases

• Build a menu selection interface
• Filter products by category
• Organize your ordering system by food/drink types

Get All Products

Retrieves the complete product catalog including pricing, categories, and availability across POS points.

Note: This endpoint routes to different handlers based on your API credential's vendor field:

• vendor: "pos" — Returns products formatted for POS integration
• vendor: "onlineMenu" — Returns products formatted for online menu (may include additional headers: Pospoint, Unit)

GET /products — Fetches all products with pricing and availability information. Auth required.

Additional Headers (Online Menu vendor only)

• Pospoint (string, optional): Filter products by POS point ID
• Unit (string, optional): Filter by unit ID

Response Fields

• id (integer): Unique product identifier (millisecond timestamp) — use this when creating orders
• name (string): Product name
• description (string): Product description (may be null)
• code (string): Internal product code (may be null)
• barcode (string): Product barcode (may be null)
• measureUnit (string): Unit of measurement for sale (e.g., "Cope", "Piece")
• purchaseUnit (string): Unit of measurement for purchase
• price (number): Default sale price (float, 2 decimal places)
• cost (number): Product cost (for internal use)
• category (object): Product category with id and name
• pospoints (array): POS points where product is available, each with custom pricing
• posplaces (array): Kitchen/preparation locations
• taxes (array): Applicable tax rates with rate, category, and included flag

Tax Object Structure

Each item in the taxes array:

• rate (number): Tax percentage (e.g., 10.0 for 10%)
• category (string): Tax category name (e.g., "VAT", "City Tax")
• included (boolean): Whether tax is already included in the product price

POS Points Object Structure

Each item in the pospoints array:

• id (integer): POS point identifier (millisecond timestamp)
• name (string): POS point name (e.g., "Restaurant", "Bar")
• price (number): Price specific to this POS point

Example Request

curl -X GET https://app.hotelbee.co/api/products \
  -H "Authorization: Bearer your-api-key" \
  -H "Property: myhotel" \
  -H "Username: pos_system"

Response 200 — Success

[
  {
    "id": 1675706456113,
    "name": "Soup",
    "description": null,
    "code": null,
    "barcode": null,
    "measureUnit": "Cope",
    "purchaseUnit": "cope",
    "price": 250,
    "cost": 1,
    "category": {
      "id": 1675706008255,
      "name": "Food"
    },
    "pospoints": [
      {
        "id": 1675706073618,
        "name": "Restaurant",
        "price": 250
      }
    ],
    "posplaces": [
      {
        "id": 1675706088872,
        "name": "Kitchen"
      }
    ],
    "taxes": [
      {
        "rate": 20.0,
        "category": "VAT",
        "included": true
      }
    ]
  },
  {
    "id": 1684780085546,
    "name": "Cola",
    "description": null,
    "code": null,
    "barcode": null,
    "measureUnit": null,
    "purchaseUnit": null,
    "price": 200,
    "cost": 24,
    "category": {
      "id": 1684780033273,
      "name": "Drinks"
    },
    "pospoints": [
      {
        "id": 1675706073618,
        "name": "Restaurant",
        "price": 200
      }
    ],
    "posplaces": [
      {
        "id": 1675706088872,
        "name": "Kitchen"
      }
    ],
    "taxes": []
  }
]

Important Notes

• Price Format: Prices are returned as floats with 2 decimal places
• Product Availability: Check the pospoints array to see where each product can be sold
• Pricing by POS Point: Products may have different prices at different POS points. Use pospoints[].price matching your pospointId
• Tax Handling: Check the included flag on each tax. If true, tax is already in the price. If false, tax must be added on top
• Null Values: Many fields may be null if not configured. Handle these appropriately
• Category Filter: Only products with a valid category are returned

Create Order

Sends a new order to HotelBee's POS system. Orders are routed to the appropriate kitchen/preparation location based on the products and POS point.

Note: This endpoint routes to different handlers based on your API credential's vendor field:

• vendor: "pos" — Standard POS order creation
• vendor: "onlineMenu" — Online menu order (requires tableId or roomId)

POST /createOrder — Creates a new order in the HotelBee POS system. Auth required. Content-Type: application/json.

Request Parameters (POS Vendor)

• products (array, required): Array of products in the order (at least one required)

- id (integer, required): Product ID in millisecond format (from /products endpoint) - price (number, required): Price per unit (should match POS point pricing) - quantity (number, required): Quantity ordered (must be > 0) - note (string, optional): Special instructions for this product

• pospointId (integer, required): POS point ID in millisecond format (from /products pospoints array)
• note (string, optional): General order notes

Additional Parameters (Online Menu Vendor)

• tableId (string, conditional): Table identifier (required if no roomId)
• roomId (integer, conditional): Room ID for room service (required if no tableId)

Online Menu Requirement: Either tableId OR roomId must be provided. Room service orders validate that an active check-in reservation exists for the specified room.

Validation Rules

POS Vendor:

• pospointId is required (error: "pos id missing")
• Each product must have an id (error: "product id missing")
• Each product ID must exist in the catalog (error: "product {id} not found")
• Each product must have a valid price (error: "product {id} invalid price")
• Each product must have a valid quantity (error: "product {id} invalid quantity")

Online Menu Vendor:

• pospointId is required (error: "POS Point ID Missing")
• Either tableId or roomId required (error: "Table ID or Room Id Missing")
• Room service: reservation must exist (error: "No reservation found")
• Room service: reservation must be checked in (error: "No checkin reservation found")

Example Request

curl -X POST https://app.hotelbee.co/api/createOrder \
  -H "Authorization: Bearer your-api-key" \
  -H "Property: myhotel" \
  -H "Username: pos_system" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "id": 1675706456113,
        "price": 250,
        "quantity": 2,
        "note": "Extra hot"
      },
      {
        "id": 1684780085546,
        "price": 200,
        "quantity": 1,
        "note": "No ice"
      }
    ],
    "pospointId": 1675706073618,
    "note": "Guest has food allergies"
  }'

Standard POS Order Body

{
  "products": [
    {
      "id": 1675706456113,
      "price": 250,
      "quantity": 1,
      "note": "Extra hot"
    },
    {
      "id": 1684780085546,
      "price": 200,
      "quantity": 1,
      "note": "No ice"
    }
  ],
  "pospointId": 1675706073618,
  "note": "VIP guest - priority service"
}

Online Menu — Table Order Body

{
  "products": [
    {
      "id": 1675706456113,
      "price": 250,
      "quantity": 2
    }
  ],
  "pospointId": 1675706073618,
  "tableId": "table_5"
}

Online Menu — Room Service Order Body

{
  "products": [
    {
      "id": 1675706456113,
      "price": 250,
      "quantity": 2
    }
  ],
  "pospointId": 1675706073618,
  "roomId": 1710800000000,
  "note": "Deliver at 7:30 AM"
}

Response 201 — Created

{
  "message": "success"
}

The order has been successfully created and sent to the kitchen/preparation area.

Response 400 — Bad Request

{
  "error": "Property Missing"
}

Response 404 — Validation Error

{
  "error": "pos id missing"
}

Other possible error messages:

• "product id missing" — A product in the array has no id
• "product {id} not found" — Product ID does not exist in catalog
• "product {id} invalid price" — Price is missing or not a valid number
• "product {id} invalid quantity" — Quantity is missing or not valid

Order Processing Details

When an order is successfully submitted:

1. Order Created: A new order document is stored with status: "OPEN", customerId: "SelfService" (fixed value for API orders), createdBy: "API_{username}" (your API username), and a timestamp generated in the hotel's timezone.
2. Tax Calculation: Taxes are calculated automatically based on product tax configuration. The system handles both included and excluded taxes.
3. ID Conversion: Product and POS point IDs are converted from millisecond format back to internal CouchDB format.
4. Order Routing: The order is routed to kitchen/preparation based on product posplaces.
5. Staff Notification: Kitchen staff see the order on their HotelBee POS terminals.
6. Real-time Event: Online menu orders publish a THIRD_PARTY_NEW_ORDER event for real-time notification.

Best Practices

• Price Verification: Always use the price from the /products endpoint's pospoints array matching your pospointId
• Product Validation: Verify products exist and are available at the selected POS point before submitting
• Error Handling: Implement retry logic with exponential backoff for 500-level errors
• Tax Awareness: Check the included flag on product taxes to understand whether prices include tax
• ID Format: Always use millisecond timestamp IDs from the API responses, never construct IDs manually

Get Online Menu Settings

Available only for vendor: "onlineMenu" API credentials.

Retrieves the online menu configuration for the property.

GET /settingsOnlineMenu — Fetches online menu settings. Auth required.

Example Request

curl -X GET https://app.hotelbee.co/api/settingsOnlineMenu \
  -H "Authorization: Bearer your-api-key" \
  -H "Property: myhotel" \
  -H "Username: onlinemenu_user"

Response 200 — Success

Returns the online menu settings document with currency, tax configuration, and display options.

Response 400 — Missing Property

{
  "error": "Property Missing"
}

Integration Workflow

Typical Integration Steps

1. Get Credentials: Contact support@hotelbee.co with your property name and use case
2. Fetch Categories: Get product categories to organize your menu (GET /productCategories)
3. Fetch Products: Retrieve the full product catalog (GET /products)
4. Build UI: Create your ordering interface with products and categories
5. Submit Orders: Send orders to HotelBee as they are placed (POST /createOrder)
6. Handle Errors: Check error responses and implement appropriate retry logic

Recommended Caching Strategy

To optimize performance and reduce API calls:

• Categories: Cache for 24 hours (rarely change)
• Products: Cache for 1-4 hours (pricing and availability may change)
• Refresh Strategy: Implement background refresh or allow manual refresh

Integration Example

JavaScript/Node.js:

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

// Fetch products
async function getProducts() {
  const response = await fetch(`${API_BASE}/products`, { headers });
  if (!response.ok) throw new Error(`Failed: ${response.status}`);
  return await response.json();
}

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

Testing Your Integration

Before going live:

1. Test with a small set of products
2. Verify orders appear correctly in HotelBee POS
3. Test error scenarios (invalid products, missing fields)
4. Confirm pricing matches between your system and HotelBee
5. Test tax calculations (included vs excluded taxes)
6. For online menu: Test both table orders and room service orders

API Limitations

• Create only: The API only supports creating new orders. Order modifications and cancellations must be done through the HotelBee POS interface
• No real-time updates: Product catalog changes are not pushed. Poll the /products endpoint periodically
• No order status: Order status tracking is not available via API
• Single property per credential: Each API credential is scoped to one property

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: What is the difference between POS and Online Menu vendor types?

A: POS vendor creates standalone orders. Online Menu vendor requires a tableId or roomId and validates room service orders against active reservations.

Q: Can I integrate with multiple properties?

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

Q: What format are the IDs in?

A: All IDs are JavaScript millisecond timestamps. Use them exactly as returned by the API.

Q: How are taxes handled?

A: Each product has a taxes array. Check the included boolean: if true, tax is already in the price; if false, add the tax percentage on top.

Q: What happens if my request fails?

A: The order is not created. You can safely retry the request with the same data. 5xx errors are safe to retry; 4xx errors require fixing the request.