Menu Structure

The POS Hub platform provides a powerful and flexible menu management system that supports everything from simple product catalogs to complex restaurant menus with extensive customization options. This guide explains the key components and relationships within the menu structure.

Overview

The menu system is built around a hierarchical structure that provides flexibility for different business models while maintaining consistency across integrations.

Core Principles:

Hierarchical Organization: Menus contain categories, categories contain items
Flexible Customization: Use selections to represent custom modifier groups, modiders and rules
Rich Metadata: Comprehensive support for images, nutritional data

Important Notes:

All menu components are location-specific
Changes to menu structure require republishing to take effect on connected marketplaces
Parent-child relationships (variants) must maintain referential integrity
Service availability cascades from menu level down to individual items

The menu is the top-level container that represents a complete offering for a specific location. Each menu defines the overall structure, availability, and fulfillment options.

Key Properties:

Location Association: Each menu belongs to a specific location
Fulfillment Types: Defines how items can be ordered (delivery, pickup, dine-in)
Service Availability: Sets overall operating hours and availability patterns
Branding Elements: Menu name, description, and imagery

Example Menu Structure:

json

{
  "id": "menu-001",
  "name": "Main Restaurant Menu",
  "description": "Our complete selection of dishes and beverages",
  "locationId": "location-123",
  "imageUrl": "https://example.com/menu-hero.jpg",
  "fulfillmentTypes": ["DELIVERY", "PICKUP", "DINE_IN"]
}

Important Notes:

Menus are location-specific and cannot be shared across locations
Fulfillment types defined at menu level apply to all items unless overridden
Menu changes require republishing to sync with connected marketplaces

Service availability controls when the entire menu or specific services are accessible to customers.

Availability Levels:

Menu-wide: Overall operating hours for the location
Service-specific: Different hours for delivery vs pickup
Category-level: Specific availability for menu sections (breakfast, lunch, dinner)
Item-level: Individual item availability overrides

Implementation Example:

json

{
  "serviceAvailability": [
    {
      "weekday": "MONDAY",
      "timePeriods": [
        {
          "startTime": "09:00",
          "endTime": "22:00"
        }
      ]
    }
  ],
  "availability": {
    "delivery": [
      {
        "weekday": "MONDAY",
        "timePeriods": [
          {
            "startTime": "11:00",
            "endTime": "21:30"
          }
        ]
      }
    ]
  }
}

Caveats:

Availability cascades down the hierarchy (menu → category → item)
More restrictive availability at lower levels takes precedence
Timezone handling must be consistent with location settings
Temporary closures require updating availability, not disabling the menu

For detailed information on how opening hours work, including location-level hours, menu-level overrides, and real-time synchronization, see Opening Hours.

Items

Menu items are the core products that customers can order. They represent individual dishes, beverages, or products with their own pricing, descriptions, and customization options.

Basic Item Structure:

json

{
  "id": "item-margherita-pizza",
  "name": "Margherita Pizza",
  "description": "Classic pizza with tomato sauce, mozzarella, and fresh basil",
  "type": "PRODUCT",
  "menuId": "menu-001",
  "categories": ["category-pizza", "category-vegetarian"],
  "price": 1299,
  "showOnline": true,
  "position": 1,
  "imageUrl": "https://example.com/margherita.jpg"
}

Item Types:

PRODUCT: Standard menu item (most common)
VARIANT: A item that is a VARIANT of another PRODUCT

Key Properties:

Categories: Array of category IDs the item belongs to
Pricing: Base price with optional in-store pricing
Media: Images and rich descriptions
Availability: Online visibility and service-specific availability
Metadata: Nutritional information, allergens, restrictions

Important Notes:

Items must be assigned to at least one category to appear in menus
Price is stored in the smallest currency unit (cents for USD)
Images significantly impact customer engagement and should be high quality
Item names and descriptions should be clear and appetizing

Item Variants

VARIANT products allow you to create a family of related items that share common characteristics but differ in specific attributes like size, flavor, or preparation style. This creates a hierarchical structure where one parent item has multiple child variants.

VARIANT Structure Implementation:

Parent Item (type: "PRODUCT"):

json

{
  "id": "latte-parent",
  "type": "PRODUCT",
  "name": "Latte",
  "description": "Rich espresso with steamed milk",
  "parentId": null,
  "showOnline": true,
  "price": 0 // Parent typically has no price
}

Child Variants (type: "VARIANT"):

json

[
  {
    "id": "latte-small",
    "type": "VARIANT",
    "name": "Small Latte",
    "parentId": "latte-parent",
    "price": 450,
    "showOnline": true
  },
  {
    "id": "latte-medium",
    "type": "VARIANT",
    "name": "Medium Latte",
    "parentId": "latte-parent",
    "price": 525,
    "showOnline": true
  },
  {
    "id": "latte-large",
    "type": "VARIANT",
    "name": "Large Latte",
    "parentId": "latte-parent",
    "price": 600,
    "showOnline": true
  }
]

Key VARIANT Features:

Inheritance: Child variants inherit properties from parent (description, images, nutritional info)
Independent pricing: Each variant can have its own price and tax configuration
Individual availability: Enable/disable specific variants independently
Shared categorization: All variants typically belong to the same categories as parent
Unified presentation: Customers see one product with multiple options

Common VARIANT Use Cases:

Use Case	Parent Product	Variants
Size Options	Pizza	Personal, Regular, Large, Family
Flavor Variants	Ice Cream	Vanilla, Chocolate, Strawberry
Preparation Styles	Steak	Rare, Medium-Rare, Medium, Well-Done
Material Options	T-Shirt	Cotton, Polyester, Blend
Strength Levels	Coffee	Mild, Medium, Strong

When to Use Variants:

Fundamentally different products that share a category (Beef Burger vs Veggie Burger)
Items requiring separate inventory tracking
Products with significantly different ingredients or preparation methods
Complex pricing structures that vary greatly between options

Important Notes:

Parent items typically have price: 0
All variants should belong to the same categories as their parent
Variants inherit properties from parent unless explicitly overridden
Deleting a parent item will orphan its variants

Caveats:

Parent-child relationships must maintain referential integrity
Variants cannot have their own child variants (no nested hierarchy)
Category assignments should be consistent across the variant family

Selections

Selections provide a powerful way to define what modifier groups, modifiers and nested groups should be present on the item, and allow you to customise the the rules of what and how modifiers can be selected on a per item bases, reducing the need to create many modifier and modifier gorups.

Selection Features:

Flexible pricing: Each selection can have independent pricing
Individual availability: Enable/disable specific selections without affecting others
Position control: Define display order of selections
Inventory tracking: Selections are mapped to modifier groups and modifiers entities which will exists as part of the menu

Selection Implementation Example:

json

{
  "id": "specialty-coffee-001",
  "name": "Burger Meal",
  "description": "Amazing Burger Meal",
  "type": "PRODUCT",
  "selections": [
    {
      "modifierGroupsId": "select-burger-001",
      "modifiers": [
        {
          "modifierId": "mod-chicken-burger-001",
          "price": 599
        },
        {
          "modifierId": "mod-beef-burger-001",
          "price": 599
        },
        {
          "modifierId": "mod-veggie-burger-001",
          "price": 699
        }
      ]
    }
  ]
}

Menu Structure ​

Overview ​

Menu ​

Menu Availability ​

Categories ​

Items ​

Item Variants ​

Selections ​

Overview

Menu

Menu Availability

Categories

Items

Item Variants

Selections