How To Code Restaurants

⚠️ Reading rule — always append .md?apiView=SDK to every doc link below. The Wix docs render two views of the same page. The bare / REST view shows id; the ?apiView=SDK view shows _id — and the SDK is what your frontend calls. Reading the REST view by mistake is the most common source of the entity.id-is-undefined bug. Fetch the .md?apiView=SDK form directly; don’t re-discover these with search.

The modules and the client (read this first)

One package for menu display: @wix/restaurants. It exposes three namespaces you read from — one per level of the hierarchy:

The hierarchy is Menu → Sections → Items, wired by id arrays: a menu.sectionIds[] points at its sections, a section.itemIds[] points at its items. You read each level separately and stitch them together (see Assembling the menu).

Auth / client — framework split:

• Astro (Wix-managed): authentication is ambient. Call menus / sections / items directly from server components and backend routes (src/pages/api/*.ts) — no createClient, no OAuthStrategy, no clientId.

  jsCopy

  import { menus, sections, items } from '@wix/restaurants';
  const { menus: menuList } = await menus.listMenus({ onlyVisible: true });

• Non-Astro (Vite/React/Vue/static): build one manual visitor client and reuse it:

  jsCopy

  import { createClient, OAuthStrategy } from '@wix/sdk';
  import { menus, sections, items } from '@wix/restaurants';
  
  const client = createClient({
    modules: { menus, sections, items },
    auth: OAuthStrategy({ clientId: /* the project's PUBLIC OAuth client id */ }),
  });
  // then: await client.menus.listMenus({ onlyVisible: true })

  The clientId is public, not a secret. A mis-wired public env var inlines as undefined and 400s every call.

The shapes you read (field cheat-sheet)

The exact field paths the frontend reads. These are SDK read shapes (?apiView=SDK), so ids are _id. Price is a decimal string.

The features (build the ones the site needs)

Each section below is a self-contained feature — implement only what the site uses. The only ordering is within the assembly (fetch levels before you stitch them).

Listing menus / sections / items (and the _id rule)

Use the list* methods — they take a simple options object and return a plain array, with no query-builder ceremony:

Docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/menus/list-menus.md?apiView=SDK (opens in a new tab) · https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/sections/list-sections.md?apiView=SDK (opens in a new tab) · https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/items/list-items.md?apiView=SDK (opens in a new tab)

✅ PREFER list* over query* for reads. listMenus / listSections / listItems take an options object ({ onlyVisible, paging, menuIds/sectionIds/itemIds }) and are unambiguous. The queryMenus / queryItems methods exist but their argument shape (object-param vs. fluent builder) is a known SDK-doc drift hotspot across Wix packages — avoid them for simple reads. To fetch a specific subset by id, pass the id array to the list method: items.listItems({ itemIds: section.itemIds }).

⚠️ CRITICAL: the entity id is _id, NOT id. The SDK normalizes every entity’s id to _id. menu.id / section.id / item.id are undefined in SDK code. Use _id everywhere — when following sectionIds / itemIds, when building links, and as React keys. (If a field name surprises you, you are probably reading the REST doc view — re-open it with ?apiView=SDK.)

Visibility: pass onlyVisible: true, and note only entities seeded visible: true are returned to a visitor token anyway — a missing section/item usually means it wasn’t seeded visible, not a query bug (ties back to the seed recipe).

Assembling the menu (follow the id arrays — and preserve their order)

The three list* calls return flat, unordered arrays. The display structure and order live in the parent’s id arrays (menu.sectionIds, section.itemIds), so stitch by looking entities up by _id in id-array order — do not render the raw list* order.

⚠️ CRITICAL: order comes from sectionIds / itemIds, NOT from the list* response order. listSections / listItems return entities in arbitrary (creation/internal) order. If you render allSecs / allItems directly, the menu shows “Desserts” before “Starters” and items in a scrambled order. Always map over the parent’s ordered id array and look each child up by _id. .filter(Boolean) after each lookup so a dangling id (a child deleted out from under the menu) is skipped rather than rendering undefined.

Reading the price

Read item.priceInfo.price — a decimal string ("9.50") with no currency symbol. Render it directly, or Number(item.priceInfo.price) if you need arithmetic, and prefix your site’s currency in the UI.

⚠️ CRITICAL: price is under priceInfo.price, not a top-level price field — and there is NO formattedPrice on the SDK type. Two traps here:

• The old top-level item.price is deprecated and reads undefined against seeded data → $NaN on the page. Always read item.priceInfo.price.
• The SDK’s PriceInfo type is { price?: string } only. item.priceInfo.formattedPrice does not type-check (TS2339) — even though the REST response happens to include a formattedPrice, the SDK type omits it, and the frontend calls the SDK. Do not read formattedPrice; format the currency yourself from price (the amount carries no symbol).

Rendering images (only when imagery is on)

Menus are seeded text-only by default, so section.image / item.image are usually absent — guard for that and render a text-only card when missing. image is a bare STRING (the SDK types both Section.image and Item.image as image?: string) — a media identifier, usually a wix:image://…, occasionally an already-absolute URL. It is not an object, so never read image.url (TS2339 — the recipe’s earlier draft got this wrong). Resolve a wix:image:// string through the helper (never put it straight into <img src> — it fails with ERR_UNKNOWN_URL_SCHEME):

⚠️ media.getScaledToFillImageUrl takes FOUR arguments in @wix/sdk — (wixMediaIdentifier, width, height, options). The options object is required (unlike getCroppedImageUrl, whose options? is optional); a 3-arg call fails with TS2554: Expected 4 arguments, but got 3. Pass {} when you have no transform options.

Never hand-build a static.wixstatic.com/.../v1/fit/... URL — the format is easy to get wrong and the image then 403s. Doc: https://dev.wix.com/docs/sdk/core-modules/sdk/media (opens in a new tab)

Conclusion

A correct Restaurants Menus frontend:

• imports menus / sections / items from @wix/restaurants — one package, three read namespaces; no cart / checkout / ecom (menus are display-only; ordering & reservations are separate apps);
• uses _id (never id) as every entity’s id and when following sectionIds / itemIds;
• prefers the list* methods (option-object) over the drift-prone query* builders for reads;
• assembles menu → sections → items in the order of the parent’s sectionIds / itemIds arrays (not the list* response order), .filter(Boolean) to drop dangling ids;
• reads price from item.priceInfo.price (a decimal string, no currency; no formattedPrice on the SDK type) — never the deprecated top-level price;
• treats image as an optional string (never image.url) and resolves wix:image:// values through media.getScaledToFillImageUrl(id, w, h, {}) (4 args), never raw.