Overview

While a SpotOn merchant has a single Catalog of menu items, they are able to configure multiple unique Menus for different ordering channels. Let’s define these terms:

Catalog: An exhaustive list of items and modifiers that can be sold with different attributes in different contexts.
Menu: A subset of catalog items for a particular ordering context, with context-specific attributes.

Within the SpotOn backoffice, a merchant can optionally configure different item availability and pricing for different channels which results in the output of multiple unique menus on the retrieve menus endpoint. For example, a merchant might configure a “Catering” menu that only offers their larger catering items. Or a merchant does not offer their ice cream on the “Delivery” menu because it will melt in transit.

Menu Selection

All of the unique menus a merchant configures will always be available on the menus endpoint, so the first step for retrieving menus will be to configure a selection mechanism for a merchant to choose which menu(s) are applicable to your application.

Retrieve Menus

At present, menu retrieval requires calling two endpoints:

The Retrieve Menus endpoint contains important info about the menu:

Name
Daily Schedule
Schedule Overrides (holidays and custom closures/hours)
Top Level Categories

After you have selected a menu and stored the schedule and categories, you can then retrieve a paginated list of menu items for the individual menu(s) you’re working with.

Menu Items

Category References

Menu Items are returned with category_references to their parent categories. Items can appear in more than one category, and the category_reference is a rich object that contains a price and an item-level schedule that is specific to that category.

For example, a “Margarita” item might have two category_references to the “Cocktails” category and the “Happy Hour” category. Within the “Cocktails” category it would have a $15 price and an item level schedule of 12PM - 4PM and 6PM - 10PM. Within the “Happy Hour” category it would have a price of $7.50 and a schedule of 4PM - 6PM.

Item Groups and Modifier Groups

Menu Items can have two different types of groups on them that behave similarly: Item Groups and Modifier Groups. Item groups contain subitems and Modifier Groups contain modifiers. Modifier groups can be nested under subitems, but item groups will never be nested under modifiers. Groups and their children can appear under multiple menu items with unique values.

Menu Schedules and Item Schedules

SpotOn supports scheduling at both the Menu and Item levels, as well as date-specific overrides. These schedules determine when a Menu (and its Items) can be offered and at what price.

Menu-Level Schedules

Each Menu has a default weekly schedule that defines the standard online ordering hours. You can retrieve these defaults from the GET - Retrieve Menus endpoint under daily_schedule and schedule_overrides.

Menu Override Schedules (Date-Specific)

Merchants can also configure date-specific overrides—often for holidays or special events—that override the default weekly schedule. These overrides might:

Change hours of operation (e.g., shorter hours on a holiday).
Mark the business as entirely closed (is_unavailable).

If the Menu is explicitly closed (e.g., due to a holiday override), the entire Menu should be considered unavailable—regardless of any conflicting item-level schedules.

Item-Level Schedules

Items can optionally have their own schedules, which take precedence over the Menu’s default schedule. This is often used for day-part pricing (breakfast/lunch/dinner) or happy hours.

Category References
Like prices, please remember item-level schedules are scoped per category_reference. Please see category reference example above.

Item Override Schedules (Date-Specific)

Item-level schedules can also have date-specific overrides (often driven by pricing events). For instance:

A holiday promotion for pizzas only on a specific date.
A one-day happy hour pricing event.

Schedule Precedence

In scenarios where multiple schedules or overrides overlap, SpotOn does not strictly enforce “guardrails” to prevent conflicting configurations. However, we recommend following this general precedence:

Menu Override Schedule Closures
If the Menu is marked closed via a date-specific override (is_unavailable), the entire Menu should be hidden—even if there are item-level overrides that suggest availability.
Item-Level Date-Specific Override
If the Menu is open on a particular day/date, then use any date-specific item schedule overrides first.
Item-Level Default Schedule
If the Menu is open and there are no item-level date-specific overrides, use the item’s default schedule.
Menu Override Schedule (Different Hours)
When a Menu override changes the hours without fully closing the Menu, check item-level schedules (and item-level date-specific overrides) first. If none apply, use the Menu override hours.
Normal Menu Schedule
If no overrides or item-level schedules apply, default to the Menu’s standard weekly schedule.

Note: Because merchants can create conflicting overrides (e.g., marking themselves closed on a holiday while also creating a half-off pizza promotion that same day), your integration may need to gracefully handle ambiguous or contradictory data. When in doubt, prioritize preventing orders when the merchant intends to be closed.

Menu Updates

In order to keep your menu sync up to date, SpotOn offers “Menu” webhook notifications for when menus change. If your application is an online ordering use-case, it is required that you refresh your menu in real time based on webhook notifications. Polling might be acceptable for less time sensitive use cases like menu display boards, but we strongly recommend all partners base menu retrieval off of webhook events.

86ing

When items are marked unavailable or hit a quantity of zero in the POS, SpotOn will trigger “Item Availability” events. Item 86’ing is a separate event from menu updates. When an item is made unavailable it applies to ALL menus that contain the item.