BevQ POS menus: missing items, matching, resync, and preserved fields

What this does

Distinguish the POS snapshot viewer from menu-section synchronization. Trace visible items, manual matches, exclusions, prices and stock before retrying a sync.

Before you start

• Select the intended group and location.
• Review the section's POS sources and parent matching policies before changing any item.

Steps

1. Check the POS snapshot timestamp and visible menu/group hierarchy.
2. Check the assigned section sources and exclusions when an item is missing.
3. Distinguish POS Resync from loading the POS snapshot again.
4. Inspect match and stock results separately; a completed sync can leave AI review pending.

Notification recipients do not determine which location changed

A BevQ POS notification delivered under group policy can still describe a location event. Location events remain separated by location; master-section events use parent scope even when their source includes a sample location. Changing who receives a summary does not change the event's owning scope or POS matching authority. Check the location named in the message before investigating its menu. A group recipient list is not evidence that every location changed.

Missing summaries and unclear event origin

The group-policy batch separates known parent and location events before sending. Entries whose origin cannot be established are retained rather than silently attributed to the whole group. Each partition is acknowledged separately when its delivery outcome permits reset; another location's failed send does not erase that partition's pending work. If a summary is missing, provide Support with the affected menu/location and approximate sync time. Do not repeatedly change menu configuration to force an email, and do not interpret a missing email as proof that POS synchronization failed.

POS Menus Resync reloads a snapshot

The POS Menus page's Resync POS button calls the same snapshot-loading function used on entry: it fetches the location's posMenu.json with cache no-store. It does not call the menu-section synchronization endpoint or directly fetch Toast. Last synced comes from the snapshot, not the time you pressed the button. Repeatedly loading an old snapshot does not prove upstream synchronization ran. Compare its timestamp and the integration state before escalating stale data.

Missing snapshot and failed load

A failed HTTP response, invalid JSON, or absent/empty source menus enters the POS viewer's failed-load state: it clears the menu list and timestamp and shows Failed to load POS menus. The page also says No POS sync found yet or file is missing. An otherwise nonempty snapshot whose items are all filtered from visibility can instead normalize to no visible menus. Distinguish transport/missing-file failure from visibility filtering; do not create replacement production items merely to make the page nonempty.

Which POS menus, groups and items are visible?

The POS tree accepts visibility arrays containing POS, MENU, DEFAULT or BOTH, and also an empty array. Missing/null or true visibility is visible. String visibility is trimmed and uppercased before testing; array values are tested literally. Hidden ancestors suppress their descendants. Both rootGroup and nested menuGroups/groups are traversed, duplicate child identifiers are removed, and groups with no visible descendant items disappear. Check ancestor visibility and nested placement when a POS item seems missing.

Assign POS source to an existing or new section

Assign POS Menu to Menu Section lets you choose an existing section or enter a new section name. If both are supplied, the selected existing section wins. Assign enables POS for that section and adds the selected source identifier without duplicating it; it does not replace all previous source assignments. It writes section metadata and item storage in separate operations. Cancel closes the dialog without assignment. If assignment fails, the inspected handler logs the error without a customer-facing error toast; reopening the section is necessary to verify whether a partial write occurred.

Section POS Resync versus POS Resync + BevQ AI

The menu item grid's resync button posts the current group, location and section to syncTabsWithToastHttp with a 120-second client deadline. It requires a successful HTTP result and ok response. POS-only mode reports refreshed synced items; AI-enabled mode reports either all matched or the number still needing BevQ AI review. A successful POS sync is not completed enrichment. A client timeout shows POS resync timed out and does not establish that server-side writes were canceled; inspect the saved section before retrying.

What a manually matched item preserves

During section sync, a prior item marked audit.manuallyMatched is spread over the newly normalized item. That preserves its prior display/catalog fields and can also preserve prior servings and prices; do not promise every manual match receives fresh POS prices. The explicit exception is stock: incoming stock status and quantity overwrite the prior item, because stock is location-specific. This broad preservation branch is different from an ordinary normalized item or a carried-forward automatic reference. Check the saved item's matching mode when a price or display field seems stale.

When an earlier catalog match is carried forward

For an ordinary item without a fresh reference, sync can retain an earlier reference only when that earlier item was not manually unmatched, the catalog reference remains valid, and the reference is not in rejectedMatches. Fresh normalized fields override the earlier item's values while the prior refId/refType and usable match score are retained. The retained reference is marked carriedForwardMatch. This does not guarantee preservation after catalog deletion, an explicit rejection, or a changed POS identity.

Unmatch saves the rejection

Unmatch clears the item's reference and score, marks it manually unmatched, and appends the rejected catalog reference to its audit. After a successful item update it removes group manual-match cache entries; these are separate operations, not an atomic undo. Parent-controlled matches cannot be unmatched at location level. Do not assume unmatching is confined to a temporary preview or that a failed cache cleanup means the item update was undone.

Delete/exclude can affect the whole location

Exclude and remove writes an exclusion keyed by POS item identity beneath the location, then removes the item from the section UI. A parent policy can prohibit deleting matched POS items at location level. Although the exclusion document stores the section ID, the inspected sync loads the location's exclusion document IDs into one set and filters by item identity without a section check. Treat the exclusion as location-wide for this sync path; an item may remain absent from other sections after resync.

POS sizes, prices and missing size data

SIZE_PRICE normalization uses the source size rows and their amounts. Configured size mappings can supply a display name and ounces; calories are scaled from the per-12-ounce value when both inputs exist. Missing size rows produce the visible Size Pricing Strategy - Coming Soon! placeholder rather than a fabricated price. BASE_PRICE and MENU_SPECIFIC_PRICE create a serving only for a numeric price; other pricing strategies do not gain a made-up default serving. Check source pricing and size mapping before manually replacing a missing price.

Permissions and scope

• Controls are subject to parent matching/deletion policies and selected location. Complete role/backend permission enforcement remains under audit.

Mobile

• The POS viewer and item grid have separate layouts at 639 pixels or narrower; mobile screenshots remain outstanding.

What happens next

Verify the saved result in the correct scope and delivery path. A preview or status badge is not proof that every production Player has refreshed.

Warnings

• This source-reviewed guide describes the named paths only. Operational coverage and production visual verification are still in progress.

Related articles