Opening Hours

The POS Hub platform manages opening hours through a hierarchical system that allows for flexible configuration at different levels while maintaining consistency across integrations. This guide explains how business hours are structured, how they cascade through the system, and how changes are synchronized with connected marketplaces in real time.

Overview

Opening hours in POS Hub follow a hierarchical structure that provides both flexibility and consistency.

How Hours Are Determined:

1. Menu Level Override: If a menu has serviceAvailability defined, it overrides all location-level hours
2. Location Service-Specific: If no menu override, check for location.availability.delivery or location.availability.collection
3. Location Business Hours: If no service-specific hours, fall back to location.businessHours for both delivery and collection

Key Rule: Menu serviceAvailability always takes priority over location hours. If menu hours are not set, then location service-specific hours are used, and if those don't exist, location business hours are used as the fallback.

Key Principles:

• Location-level hours are the foundation: Business hours should always be set at the location level
• Automatic POS updates: Location hours are automatically updated by connected POS applications
• Menu-level overrides: Menus can override location hours for specific use cases
• Real-time synchronization: Changes flow to connected marketplaces automatically
• Service-specific hours: Delivery and collection can have different hours than general business hours

Important Notes:

• Location business hours should always be configured, even if menu-level overrides are used
• POS applications automatically update location-level hours when changes occur in the POS system
• Menu-level serviceAvailability overrides location businessHours during menu publish and real-time flows
• Changes to opening hours trigger automatic synchronization with connected marketplaces

Location-Level Hours

Location-level hours serve as the base configuration for all operations at a location. These hours are automatically maintained by POS applications and provide the default availability for all menus unless overridden.

Business Hours

The businessHours field defines the general operating hours for the location. This represents when the location is open for business, regardless of service type.

Location Entity Structure:

{
  "id": "location-123",
  "name": "Downtown Restaurant",
  "businessHours": [
    {
      "weekday": "MONDAY",
      "timePeriods": [
        {
          "startTime": "09:00",
          "endTime": "22:00"
        }
      ]
    },
    {
      "weekday": "TUESDAY",
      "timePeriods": [
        {
          "startTime": "09:00",
          "endTime": "22:00"
        }
      ]
    }
  ]
}

Service-Specific Hours

In addition to general business hours, locations can define service-specific availability for delivery and collection (pickup) services. These allow different operating hours for different service types.

Location Entity with Service-Specific Hours:

{
  "id": "location-123",
  "name": "Downtown Restaurant",
  "businessHours": [
    {
      "weekday": "MONDAY",
      "timePeriods": [
        {
          "startTime": "09:00",
          "endTime": "22:00"
        }
      ]
    }
  ],
  "availability": {
    "delivery": [
      {
        "weekday": "MONDAY",
        "timePeriods": [
          {
            "startTime": "11:00",
            "endTime": "21:30"
          }
        ]
      }
    ],
    "collection": [
      {
        "weekday": "MONDAY",
        "timePeriods": [
          {
            "startTime": "10:00",
            "endTime": "21:00"
          }
        ]
      }
    ]
  }
}

Service-Specific Hours Behavior:

• availability.delivery: Hours when delivery service is available (may be more restrictive than general hours)
• availability.collection: Hours when collection/pickup service is available
• If service-specific hours are not set, the service uses businessHours as the default
• Service-specific hours cannot extend beyond general business hours

Automatic Updates:

• POS applications automatically update location hours when changes occur in the POS system
• Updates flow through the catalog import process to maintain synchronization
• Changes trigger real-time updates to connected marketplaces

Menu-Level Overrides

Menus can override location-level hours by defining custom serviceAvailability. This is useful when you need different operating hours for specific menus (e.g., a breakfast menu with different hours than the main menu).

When to Use Menu-Level Overrides

Menu-level overrides are appropriate when:

• A menu has significantly different hours than the location's general hours
• You need to create time-specific menus (breakfast, lunch, dinner)
• A menu should only be available during certain periods
• You want to temporarily restrict a menu without changing location hours

Important: Menu-level overrides should be used sparingly. In most cases, location-level hours should be sufficient.

How Menu Overrides Work

When a menu has serviceAvailability defined, it overrides the location's businessHours during:

1. Menu Publishing: When a menu is published to a marketplace, menu-level hours take precedence
2. Real-Time Flows: When availability changes are sent to marketplaces, menu hours override location hours
3. Menu Display: Marketplaces display menu-specific hours when available

Menu Entity with Custom Availability:

{
  "id": "menu-breakfast",
  "name": "Breakfast Menu",
  "locationId": "location-123",
  "serviceAvailability": [
    {
      "weekday": "MONDAY",
      "timePeriods": [
        {
          "startTime": "07:00",
          "endTime": "11:00"
        }
      ]
    },
    {
      "weekday": "TUESDAY",
      "timePeriods": [
        {
          "startTime": "07:00",
          "endTime": "11:00"
        }
      ]
    }
  ]
}

Override Behavior:

• Menu serviceAvailability completely replaces location businessHours for that menu
• If a menu doesn't have serviceAvailability, it inherits location hours
• Menu overrides apply to all fulfillment types (delivery, pickup, dine-in) unless further restricted
• Category and item-level availability can further restrict menu availability

Enabling Custom Menu Availability

When creating a menu through the UI, you can enable custom availability by checking the "Enable Custom Menu Availability" option. This allows you to set menu-specific hours that override the location's default hours.

For detailed information on creating menus with custom availability, see Create Menu.

Service Availability Structure

The ServiceAvailability type is used throughout the platform to define operating hours. It provides a flexible structure for representing complex scheduling scenarios.

Schema Definition

ServiceAvailability: {
  weekday: 'MONDAY' | 'TUESDAY' | 'WEDNESDAY' | 'THURSDAY' | 'FRIDAY' | 'SATURDAY' | 'SUNDAY'
  timePeriods: {
    startTime?: string      // 24-hour HH:MM format (e.g., "08:30", "23:00")
    endTime?: string        // 24-hour HH:MM format (e.g., "08:30", "23:00")
    startDate?: string      // YYYY-MM-DD format (e.g., "2023-10-01")
    endDate?: string        // YYYY-MM-DD format (e.g., "2023-10-01")
  }[]
}[]

Weekday Enumeration

Each availability entry must specify a weekday:

• MONDAY
• TUESDAY
• WEDNESDAY
• THURSDAY
• FRIDAY
• SATURDAY
• SUNDAY

Time Periods

Each weekday can have multiple time periods, allowing for scenarios like:

• Split shifts (e.g., 09:00-14:00 and 17:00-22:00)
• Lunch breaks
• Multiple service windows per day

Single Time Period Example:

{
  "weekday": "MONDAY",
  "timePeriods": [
    {
      "startTime": "09:00",
      "endTime": "22:00"
    }
  ]
}

Multiple Time Periods Example:

{
  "weekday": "MONDAY",
  "timePeriods": [
    {
      "startTime": "09:00",
      "endTime": "14:00"
    },
    {
      "startTime": "17:00",
      "endTime": "22:00"
    }
  ]
}

Date-Ranged Availability:

For temporary or seasonal hours, you can specify date ranges:

{
  "weekday": "MONDAY",
  "timePeriods": [
    {
      "startTime": "09:00",
      "endTime": "22:00",
      "startDate": "2024-01-01",
      "endDate": "2024-03-31"
    }
  ]
}

Complete Example

A location with complex hours across the week:

{
  "businessHours": [
    {
      "weekday": "MONDAY",
      "timePeriods": [
        {
          "startTime": "09:00",
          "endTime": "22:00"
        }
      ]
    },
    {
      "weekday": "TUESDAY",
      "timePeriods": [
        {
          "startTime": "09:00",
          "endTime": "14:00"
        },
        {
          "startTime": "17:00",
          "endTime": "22:00"
        }
      ]
    },
    {
      "weekday": "WEDNESDAY",
      "timePeriods": [
        {
          "startTime": "09:00",
          "endTime": "22:00"
        }
      ]
    },
    {
      "weekday": "THURSDAY",
      "timePeriods": [
        {
          "startTime": "09:00",
          "endTime": "22:00"
        }
      ]
    },
    {
      "weekday": "FRIDAY",
      "timePeriods": [
        {
          "startTime": "09:00",
          "endTime": "23:00"
        }
      ]
    },
    {
      "weekday": "SATURDAY",
      "timePeriods": [
        {
          "startTime": "10:00",
          "endTime": "23:00"
        }
      ]
    },
    {
      "weekday": "SUNDAY",
      "timePeriods": [
        {
          "startTime": "10:00",
          "endTime": "21:00"
        }
      ]
    }
  ]
}

Real-Time Synchronization

The POS Hub platform automatically synchronizes opening hours changes with connected marketplaces in real time. This ensures that customers always see accurate availability information.

POS Updates to Location Hours

When a POS application updates business hours:

1. Catalog Import: The POS sends updated hours through the catalog import API
2. Location Update: The location's businessHours or availability fields are updated
3. Change Detection: The system detects changes to availability fields
4. Marketplace Notification: Connected marketplaces are notified of the changes
5. Menu Publish: If menus are configured for auto-publish, they are republished with updated hours

Update Flow:

Menu Changes and Publishing

When menu availability changes:

1. Menu Update: Menu serviceAvailability is modified
2. Publish Trigger: Manual publish or auto-publish interval triggers
3. Override Application: Menu hours override location hours during publish
4. Marketplace Sync: Updated menu with custom hours is sent to marketplace

Publish Behavior:

• Manual publish: Immediately sends menu with current availability
• Auto-publish: Scheduled publishes include latest availability changes
• Menu serviceAvailability always overrides location businessHours during publish
• If menu has no serviceAvailability, location hours are used

Webhook Events

Availability changes can trigger webhook events for real-time integration:

• Location hours updates trigger location change events
• Menu availability changes trigger menu update events
• Marketplace connections receive notifications when hours change

For more information on webhooks, see Webhooks.

Best Practices

Following these best practices ensures reliable opening hours management and proper synchronization with marketplaces.

Always Set Location-Level Hours

Do:

• Configure businessHours at the location level for all locations
• Set service-specific hours (availability.delivery, availability.collection) when needed
• Ensure location hours are accurate and up-to-date

Don't:

• Rely solely on menu-level hours without location hours
• Leave location hours unset or empty

Use Menu-Level Overrides Sparingly

Do:

• Use menu overrides for menus with significantly different hours
• Use overrides for time-specific menus (breakfast, lunch, dinner)
• Document why menu overrides are needed

Don't:

• Override location hours for every menu
• Use menu overrides as a substitute for proper location configuration
• Create menu overrides that duplicate location hours

Timezone Considerations

• All times are specified in the location's timezone
• Ensure the location's timezone field is correctly set
• Marketplaces convert times to their local timezone for display
• Be consistent with timezone settings across all availability configurations

Validation and Testing

• Test menu publishing with custom availability to ensure overrides work correctly
• Verify that marketplace displays show correct hours
• Monitor webhook events to ensure changes propagate correctly
• Validate time period formats (24-hour HH:MM format)

Related Documentation

• Menu Structure: Understanding menu hierarchy and availability cascading
• Create Menu: How to create menus with custom availability
• Menu Publishing: How menu hours are published to marketplaces
• Webhooks: Real-time event notifications for availability changes