@wix/agent-skills 1.14.0 → 1.15.0

package/skills/wix-headless/references/inline-recipes/how-to-code-members-non-astro.md

@@ -0,0 +1,118 @@
+---
+name: "How to Code Members (non-Astro)"
+description: The frontend contract for member sign-up / log-in / log-out and member-gated surfaces on a **non-Astro** frontend (Vite/React/Vue SPA or static HTML, managed-non-Astro or self-managed) — the manual `OAuthStrategy` handshake off the *same* visitor client non-astro.md already builds (`generateOAuthData → getAuthUrl → parseFromUrl → getMemberTokens → setTokens`, `logout`, `loggedIn()`), token persistence + `renewToken`, the published-site and allow-listed-redirectUri preconditions, defaulting to the Wix login page, reading the current member with `@wix/members`, and the no-`auth.elevate` rule. Specifies the *how* for the non-Astro axis only — read `how-to-code-members-astro.md` for an Astro frontend.
+---
+**RECIPE**: How to Code Member Auth on a **non-Astro** Frontend (manual `OAuthStrategy`, `@wix/members`)
+
+A concise contract for wiring **login / sign-up / logout and member-gated surfaces** into a non-Astro frontend — a Vite/React/Vue SPA or plain static HTML, whether managed-non-Astro or self-managed. **This is the *how* (which calls, which preconditions, which failure modes), not the *what*** — which pages are gated, what the account page shows, and the design come from the request you're fulfilling.
+
+> **⚠️ AXIS GUARD — this recipe is for non-Astro only.** Here you drive the OAuth handshake yourself on the same manual client `non-astro.md` builds for visitors. If the frontend **is** Astro, **stop and read `how-to-code-members-astro.md`** — Astro ships built-in `/api/auth/login` routes and auto-auth, and building the `OAuthStrategy` handshake below on Astro is wrong (and 500s at SSR). Don't cross the streams.
+
+> **One mechanism, not three.** Sign-up, log-in and log-out are the *same* flow — the Wix login page **logs in an existing member or registers a new one** in one step; you never build a separate "sign up" call. Member tokens are the **same shape** as visitor tokens, just `role: member`: login just swaps the token set on the client you already have.
+
+Pinned docs (read before wiring — `curl` the `.md` directly):
+- Wix-managed login via the JS SDK: <https://dev.wix.com/docs/go-headless/self-managed-headless/authentication/members/wix-login-page/wix-managed-login-using-the-js-sdk.md>
+- `OAuthStrategy` reference (member flows, token/session methods): <https://dev.wix.com/docs/sdk/core-modules/sdk/oauth-strategy.md>
+- Handle visitors & members via the JS SDK: <https://dev.wix.com/docs/go-headless/self-managed-headless/authentication/visitors/handle-visitors-using-the-js-sdk.md>
+- Current member (SDK): <https://dev.wix.com/docs/sdk/frontend-modules/members/current-member/introduction> (open with `?apiView=SDK`)
+
+---
+
+## Preconditions — get these right or `getAuthUrl` fails (read first)
+
+- **`clientId` only, never the secret.** Member auth uses the same **public** OAuth client id as the visitor client (`non-astro.md` N6). No `client_secret` in the frontend, ever.
+- **The connected site must be PUBLISHED.** `getAuthUrl` serves the Wix login page; against an unpublished site it fails the redirect with a non-obvious error. Publish before testing login (like the events payment-method precondition).
+- **The `redirectUri` must be in the OAuth app's allowed redirect URIs — exact match, and YOU must register it (it is not automatic).** A mismatch (or a missing entry) is the classic login 4xx — login is dead until it's registered. `wix release` auto-registers the deployed **origin** (`allowedRedirectDomains`), but **not** this member-login **callback** (`allowedRedirectUris`) — that's a separate field and a separate, manual step. Because the callback embeds the deployed origin, it's a **post-deploy** step: register it right after release. **⚠️ Do not conclude `allowedRedirectUris` is read-only/dashboard-only** — the `UpdateOAuthApp` doc may not list it prominently, but a **masked `PATCH`** sets it (the field mask is required or it silently no-ops). **Mechanics: `managed/DEPLOYMENT.md` → "Member login on a non-Astro frontend".** Register both the exact callback (`window.location.origin + '/callback'`) and the `https://*-<host>/callback` wildcard; don't rely on trailing-slash/path variants matching.
+- **Default to the Wix login page** — the sub-type this recipe uses. Three login sub-types exist (Wix login page / custom login page / externally-managed); the Wix page needs **no UI to build** and is deterministic. **If the brief explicitly asks for a custom/branded in-app login form or custom sign-up fields** (full name / username / address / arbitrary fields), **stop and read `how-to-code-members-custom-login.md`** — that path builds the form and drives `client.auth.register`/`login` directly (works on any project type). Use externally-managed only when specifically requested. When no custom form or extra fields are named, the Wix login page below is the default — don't build a custom form unprompted.
+
+---
+
+## Identity vs. profile — two layers, don't conflate them
+
+- **Identity / auth** — *"is this caller a logged-in member?"*, log in, log out. Native to the headless OAuth app. **No app install needed** — everything in "The login flow" and `loggedIn()`-based gating below runs on this layer alone.
+- **Member profile / Members Area** — reading name / photo / roles / badges, an editable my-account page. Served by the **Wix Members Area app**, which **must be installed** (see `SETUP.md`). `@wix/members` `getCurrentMember()` returns data only once that app is present.
+
+If `getCurrentMember()` returns empty/errors on a site where `loggedIn()` is `true`, suspect the **Members Area app isn't installed** — not a code bug.
+
+---
+
+## The login flow — the same client, plus a round-trip
+
+Reuse the one visitor client `non-astro.md` builds (`createClient({ modules, auth: OAuthStrategy({ clientId }) })`) — don't make a second client. Login is three steps across a redirect.
+
+```js
+// 1 · start login (sign-up is the SAME call) — from a "Log in" button
+const redirectUri  = window.location.origin + '/callback';   // MUST be allow-listed, exact match
+const originalUri   = window.location.href;                    // where to send the member back after
+const oAuthData = client.auth.generateOAuthData(redirectUri, originalUri); // PKCE: state + codeVerifier
+localStorage.setItem('wixOAuthData', JSON.stringify(oAuthData));           // survive the redirect
+const { authUrl } = await client.auth.getAuthUrl(oAuthData);
+window.location.href = authUrl;                                // → Wix login page (login or register)
+
+// 2 · on the callback page (/callback)
+const oAuthData = JSON.parse(localStorage.getItem('wixOAuthData'));
+const returned  = client.auth.parseFromUrl();                  // { code, state } or { error }
+if (returned.error) { /* surface returned.errorDescription; do NOT loop back into getAuthUrl */ }
+const tokens = await client.auth.getMemberTokens(returned.code, returned.state, oAuthData);
+client.auth.setTokens(tokens);                                 // subsequent SDK calls now run as the member
+persistTokens(tokens);                                         // see persistence below
+window.location.href = returned.originalUri ?? '/';            // back to where login started
+
+// 3 · logout
+const { logoutUrl } = await client.auth.logout(window.location.href);
+clearPersistedTokens();
+window.location.href = logoutUrl;
+```
+
+Check auth state anywhere: **`client.auth.loggedIn()`** — `false` = anonymous visitor, `true` = logged-in member. Gate a view on it (render the account UI only when `true`; otherwise show a "Log in" control that runs step 1).
+
+---
+
+## Token persistence & renewal — treat member tokens like visitor tokens
+
+Member tokens are the **same token set** the visitor session machinery already handles; login just swaps them in.
+
+- **Persist** the token set (localStorage or a cookie) after `setTokens` so a reload stays logged in. On app boot, if you have a stored set, `client.auth.setTokens(stored)` before first render.
+- **Renew** with `client.auth.renewToken(refreshToken)` (or the SDK's automatic renewal when you re-hydrate via `setTokens`) — same as the visitor refresh flow. A member session expiring is a normal state; refresh, don't force a re-login unless the refresh token is gone.
+- On logout, **clear** the persisted set so the next boot is a clean anonymous visitor.
+
+---
+
+## Read the current member — `@wix/members`, not the dev-preview package
+
+```js
+import { members } from '@wix/members';
+// with the member tokens set on the client:
+const { member } = await client.members.getCurrentMember({ fieldsets: ['FULL'] });
+// member.profile?.nickname, member.profile?.photo, member.loginEmail, member.contactId, member.roles
+```
+
+- **⚠️ The SDK export is `getCurrentMember`, NOT `getMyMember`.** The REST method is named *Get My Member* and the SDK docs page may show `GetMyMember`, but `@wix/members` exports it as **`client.members.getCurrentMember`** — calling `getMyMember(...)` throws `is not a function` at runtime. It's a silent trap: a logged-out smoke test never reaches the call, so it only fails once a real member loads the account page.
+- **⚠️ Use `@wix/members`** (`getCurrentMember` / `getMember` / `updateMember`) — visitor/member auth, production-ready. **Do NOT use `@wix/site-members`** (`wixSiteMembers`, "Current Member") — it's in **Developer Preview** ("not for production"). Only if a profile-privacy toggle is specifically requested.
+- The **photo** is a `wix:image://` identifier — resolve with `media.getScaledToFillImageUrl` (`non-astro.md` N7); never hand-build the CDN URL.
+- **Another member by id → PUBLIC fieldset only**; a **private** profile returns nothing to a member/visitor identity (relevant to any "look up author by id" lookup).
+
+---
+
+## ⚠️ Do NOT `auth.elevate()` — and on a SPA you can't anyway
+
+- **Login** is the **identity** axis (anonymous → a specific member). **`auth.elevate()`** is the **permission** axis (→ app/admin scope). A member reading **their own** data (own orders/bookings/subscriptions, plan-gated content, their profile) is authorized under the **member token, no elevation** — reaching for elevate to "make member data work" is the wrong axis and doesn't help.
+- A pure SPA / static site has **no server, so there is no `auth.elevate` at all** (`non-astro.md` N5). Admin/site-wide reads (everyone's orders, all members) genuinely can't run on this path — that's a real limitation, but **member features don't need it**, so it does not block login / account / gated content. If a feature truly needs an admin read, it needs a server (out of scope for a static SPA).
+
+---
+
+## pricing-plans is a HARD dependency on members
+
+If the site has pricing-plans, **login is required, not optional**. Ordering a plan (`orders.createOnlineOrder(planId)`) orders it **for a logged-in member**; anonymous → the Wix flow forces sign-up. `orders.memberListOrders()` and "my subscription" reads return **nothing** for an anonymous visitor. So the plans grid is public, but the **subscribe** button and the **my-subscription** surface both need the login flow above; a logged-in member calling `orders.createOnlineOrder` needs **no `onBehalf`**. Everywhere else (stores "my orders", bookings "my bookings", events "my registrations"), login is a *soft* add-on — the purchase/RSVP/book action runs fine as an anonymous visitor; only the account view of it needs a member.
+
+---
+
+## Conclusion
+Correct member auth on a non-Astro frontend:
+- reuses the **one visitor `OAuthStrategy` client** and drives the handshake — `generateOAuthData → getAuthUrl → parseFromUrl → getMemberTokens → setTokens`, `logout`, `loggedIn()` — **never** an Astro `/api/auth/*` route;
+- gets the preconditions right up front: **`clientId` only**, **site published**, **`redirectUri` allow-listed exact-match**, **default to the Wix login page**;
+- **persists and renews** member tokens like visitor tokens (`renewToken`), re-hydrating with `setTokens` on boot and clearing them on logout;
+- reads the current member via **`@wix/members` `getCurrentMember`** (not the dev-preview `@wix/site-members`), resolving the photo `wix:image://` URI, expecting PUBLIC-only fields for other members;
+- does **no `auth.elevate`** (wrong axis for own-data reads; unavailable on a serverless SPA anyway);
+- treats **login as required** whenever pricing-plans is present, and as a soft add-on for the "my …" surfaces of the other verticals;
+- needs the **Wix Members Area app installed** only for profile *data* — pure "logged-in vs not" gating runs on the identity layer with no install.

package/skills/wix-headless/references/inline-recipes/how-to-code-portfolio.md

@@ -0,0 +1,132 @@
+---
+name: "How to Code Portfolio"
+description: The frontend read contract for a Wix Portfolio backend — which @wix/portfolio modules, the exact list/query/detail calls, and the failure modes the docs omit (`_id` not `id`, object-param query NOT a builder, cover-image `.url` vs project-item `wix:image://` string). The *how*; which projects/collections to render come from the request.
+---
+**RECIPE**: How to Code a Portfolio Frontend (Wix Portfolio v1 — display-only, no eCommerce)
+
+A contract for the **frontend code** of a portfolio/showcase site. The *how* (modules, calls, fields), not the *what* (which projects to show, the page design, the framework — those come from the request).
+
+> **This recipe is for CODING, not seeding.** It assumes the backend already exists — collections and projects were created by `setup-portfolio.md`. It says nothing about creating data; it only reads and renders it. Portfolio is **display-only**: there is no cart, checkout, or eCommerce — do **not** pull in `@wix/ecom`/`@wix/redirects`.
+
+> **⚠️ Reading rule — append `?apiView=SDK` to every doc link below.** Wix renders two views of each page: the bare/REST view shows `id`; the `?apiView=SDK` view shows **`_id`**. The SDK is what the frontend calls, so the REST view will actively mislead you (reading `project.id` yields `undefined` and detonates every downstream key/route). Always read the SDK view.
+
+---
+
+## The modules and the client (read this first)
+
+**No app-id constant is needed** — Portfolio has no `catalogReference`/eCommerce surface. Everything is a plain read from `@wix/portfolio`.
+
+**Module table** — import only what the site uses:
+
+| Need | Package | Module | Key methods |
+|---|---|---|---|
+| Collections (groupings) | `@wix/portfolio` | `collections` | `listCollections(options?)`, `queryCollections(query, options?)`, `getCollection(id, options?)` |
+| Projects (the showcased work) | `@wix/portfolio` | `projects` | `listProjects(options?)`, `queryProjects(query, options?)`, `getProject(id, options?)` |
+| A project's media items (deeper project-page gallery) | `@wix/portfolio` | `projectItems` | `listProjectItems(projectId, options?)` |
+| Resolve image media strings (covers **and** project items) | `@wix/sdk` | `media` | `getScaledToFillImageUrl(id, w, h, {})` |
+| Build the client (non-Astro only) | `@wix/sdk` | `createClient`, `OAuthStrategy` | — |
+
+- **There is one Portfolio API version (v1)** — no V1-vs-V3 trap like Stores.
+- **`queryX` accepts BOTH an object-param and a builder overload** — `queryProjects({ filter, cursorPaging })` **and** `queryProjects().eq(…).find()` both type-check (unlike Stores/Bookings, whose object-param shape was removed). Either compiles; this recipe prefers a **client-side filter** (see Filtering) so you needn't pick.
+- **Public read — no `auth.elevate`.** Portfolio content is public on the live site, so a visitor client reads collections/projects/items with **no elevation**. (The docs show `auth.elevate(...)` examples — those are for backend/admin jobs; a visitor-facing read does not need them. Elevation is the separate admin axis.)
+
+**Auth / client — the framework split:**
+
+- **Astro (Wix-managed, the default):** auth is **ambient**. Import the modules and call them directly from server components / `src/pages/api/*` — **no `createClient`, no `OAuthStrategy`, no `clientId`.**
+  ```ts
+  import { collections, projects } from '@wix/portfolio';
+  const { collections: cols } = await collections.listCollections();
+  const { projects: projs } = await projects.listProjects();
+  ```
+- **Non-Astro (Vite/React/Vue/static):** build **one** manual visitor client and reuse it. The `clientId` is the app's **public** OAuth id (not a secret; `client_secret` never reaches the frontend).
+  ```ts
+  import { createClient, OAuthStrategy } from '@wix/sdk';
+  import { collections, projects, projectItems } from '@wix/portfolio';
+  const wixClient = createClient({
+    modules: { collections, projects, projectItems },
+    auth: OAuthStrategy({ clientId: import.meta.env.PUBLIC_WIX_CLIENT_ID }),
+  });
+  // then: await wixClient.projects.listProjects()
+  ```
+  A mis-wired public env var inlines as `undefined` and 400s **every** call — after building, confirm the actual `clientId` value is in the bundle.
+
+---
+
+## The features (build the ones the site needs)
+
+Each subsection is self-contained — implement only what the site uses, in any order. Ordering matters only *within* a feature (resolve the collection/project before you filter/render by it).
+
+### Listing the gallery (projects + collections) — and the `_id` rule
+
+The gallery is two reads: **all projects** and **all collections**. Prefer the **`list*` methods** — they take an optional `options` (`{ paging: { limit, cursor }, includePageUrl }`) and need no query object:
+
+```ts
+const { projects: projs = [] } = await projects.listProjects();        // Astro: module; non-Astro: wixClient.projects…
+const { collections: cols = [] } = await collections.listCollections();
+```
+Docs (read `?apiView=SDK`):
+- <https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/list-projects?apiView=SDK>
+- <https://dev.wix.com/docs/api-reference/business-solutions/portfolio/collections/list-collections?apiView=SDK>
+
+**⚠️ CRITICAL — the id field is `_id`, never `id`.** Under `?apiView=SDK`, both `Project` and `Collection` expose **`_id`** (a GUID), `title`, `description`, `slug`, `hidden`, `coverImage`; `Project` also has `collectionIds: string[]` and `details`. Reading `.id` returns `undefined` — every `key={p.id}` and every `/[slug]` route built from it breaks silently. If you find yourself reading `id`, you're looking at the REST doc view.
+
+**⚠️ The list arrays and `_id` are nullable under `strict`.** `listProjects()`/`listCollections()`/`listProjectItems()` return the array as `T[] | undefined` (default it with `= []` as above, or `?? []`), and `_id`/`slug` are `string | null | undefined`. So narrow before you key/route on them (`if (!p._id) continue`, `p.slug === params.slug`) — a bare `.filter`/`.includes(col._id)` won't type-check without the guard.
+
+**⚠️ Only `Collection` has `sortOrder` — `Project` does not.** Sort **collections** by their numeric `sortOrder` for the owner's intended order (`[...cols].sort((a,b) => (a.sortOrder ?? 0) - (b.sortOrder ?? 0))`). **`Project` exposes no `sortOrder`** (reading it is `TS2339`) — render projects in the list-response order, or sort by a field they *do* have (`title`, `_createdDate`) if you need a stable one. Don't sort projects by `sortOrder`.
+
+**⚠️ Respect `hidden`.** An entity with `hidden: true` should not appear publicly. Filter it out client-side (`projs.filter(p => !p.hidden)`) — and remember an *omitted* `hidden` comes back **absent** (proto3), so test `!p.hidden` (absent ⇒ falsy ⇒ shown), never `p.hidden === false`.
+
+### Grouping / filtering by collection
+
+A project links to its collections via **`project.collectionIds: string[]`** (a project can be in several). To show a collection's projects, the **default is a client-side filter** over the already-listed projects (avoids a second round-trip; narrow the nullable `_id` first):
+
+```ts
+const colId = collection._id;
+const inCollection = colId ? projs.filter(p => p.collectionIds?.includes(colId)) : [];
+```
+This avoids the server-filter fragility and one extra round-trip; portfolios are small.
+
+**If you filter server-side, `queryProjects`/`queryCollections` accepts EITHER shape — both compile.** The installed SDK exposes two overloads: an object-param `queryProjects({ filter, cursorPaging, sort })` (e.g. `projects.queryProjects({ cursorPaging: { limit: 100 } })`) **and** a fluent builder `queryProjects().eq('…', …).find()`. Either type-checks — pick one and confirm the filter matches before shipping. (Client-side filtering above sidesteps the choice.)
+- <https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/query-projects?apiView=SDK>
+
+### Project detail page (resolve by slug, then its media)
+
+Detail routes resolve a **`slug`** from the URL (the site is SSR — resolve at request time, no `getStaticPaths`). Resolve the project **client-side from the list** (reliable), then optionally load its media items:
+
+```ts
+const project = projs.find(p => p.slug === params.slug);        // from listProjects()
+const { items } = await projectItems.listProjectItems(project._id);   // media gallery (owner-added)
+```
+- `projectItems.listProjectItems(projectId, options?)` — first arg is the **project `_id`** (positional), not an options object.
+- <https://dev.wix.com/docs/api-reference/business-solutions/portfolio/project-items/list-project-items?apiView=SDK>
+
+Render `project.details` — an array of **`{ label, text }`** pairs (Role, Year, Client…) the seed may have set; it can be `[]`, so guard before mapping.
+
+### Rendering images — ONE `Image` shape, always a media STRING
+
+**⚠️ CRITICAL — `imageInfo` is a bare media STRING, for covers AND project items alike. There is no ready `.url`.** The installed SDK types **one** `Image { imageInfo?: string; focalPoint? }`, reused by `Project.coverImage`, `Collection.coverImage`, **and** `Item.image`. So `coverImage.imageInfo` and `item.image?.imageInfo` are both **strings** (a `wix:image://…` identifier) — reading `.url` on either is a type error (`TS2339: Property 'url' does not exist on type 'string'`). (The *REST* API returns `coverImage.imageInfo` as an object with a populated `url`, but the **SDK** — what the frontend calls — types it as a string; the package wins.) Resolve every portfolio image through the same `@wix/sdk` media helper — never drop a `wix:image://` value straight into `<img src>` (→ `ERR_UNKNOWN_URL_SCHEME`), never hand-build a `static.wixstatic.com` URL from it (→ 403):
+
+```ts
+import { media } from '@wix/sdk';
+
+// cover (project or collection) — optional, guard it
+const coverId = project.coverImage?.imageInfo;                 // string | undefined
+const cover = coverId ? media.getScaledToFillImageUrl(coverId, 1200, 900, {}) : undefined;
+
+// project-item media (same shape, same helper)
+const itemId = item.image?.imageInfo;                          // string | undefined
+const src = itemId ? media.getScaledToFillImageUrl(itemId, 1200, 900, {}) : undefined;
+```
+
+- **`media.getScaledToFillImageUrl` takes FOUR arguments** — `(wixMediaIdentifier, width, height, options)`; the `options` object is **required** (pass `{}`). A 3-arg call fails `TS2554`.
+- **Covers are optional.** A text-only-seeded project/collection has **no** `coverImage` (absent), so the resolved value is `undefined` → render the **themed-block fallback** (`IMAGE_GENERATION.md`), never a broken `<img>`.
+
+---
+
+## Conclusion
+- **Modules:** `collections`, `projects`, `projectItems` from `@wix/portfolio`; `media` + `createClient`/`OAuthStrategy` from `@wix/sdk`. **No** `@wix/ecom`/`@wix/redirects` — portfolio is display-only.
+- **`_id`, never `id`** — read entities under `?apiView=SDK`; `.id` is `undefined`. List arrays are `T[] | undefined` (default `= []`); `_id`/`slug` are nullable — narrow before keying/routing.
+- **Query has both overloads** — `queryProjects({ filter, cursorPaging })` **and** `queryProjects().eq().find()` compile; prefer client-side filtering by `collectionIds`/`slug`.
+- **Only collections have `sortOrder`** (sort collections by it); projects don't — render in list order. **Respect `hidden`** (test `!hidden` — an omitted `hidden` is absent).
+- **One `Image` shape:** `coverImage.imageInfo` and `item.image.imageInfo` are both bare media **strings** (no `.url`) → resolve every image via `media.getScaledToFillImageUrl(id, w, h, {})` (4 args); covers are optional → themed block. Never hand-build wixstatic URLs.
+- **Public read, no `auth.elevate`** — visitor client reads all content; elevation is the separate admin axis.

package/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md

@@ -0,0 +1,124 @@
+---
+name: "How to Code Pricing Plans"
+description: The frontend contract for a Wix Pricing Plans (Plans V3) site — which `@wix/pricing-plans` modules to import, how to list plans for the grid, order a plan for a logged-in member, read the member's own subscriptions, and (the integration) let a member book a Bookings service with their membership. Specifies the *how* (modules + exact calls + the failure modes the docs omit); which plans to render and how the page looks come from the request.
+---
+**RECIPE**: How to Code a Wix Pricing Plans Frontend (Plans V3 + members + the Bookings-membership integration)
+
+A contract for the **frontend code** of a pricing-plans site: showing the plans grid, subscribing (ordering) a plan, a member's "my subscription" surface, and — when the site also has Bookings — booking a service **with** an active membership. **This recipe is the *how* (which modules, which calls, which fields), not the *what*** — which plans to show, how the page looks, and the framework come from the request you're fulfilling.
+
+> **This recipe is for CODING, not seeding.** It assumes a Plans V3 backend already exists (plans created, and — for the integration — bookings services attached to a plan via Benefit Programs; see `setup-pricing-plans.md`). It says nothing about creating plans — only how to read and buy them from frontend code.
+
+> **⚠️ Reading rule — append `.md?apiView=SDK` to every doc link below.** Wix docs render two views: the **bare/REST view shows `id`**, the **`?apiView=SDK` view shows `_id`** — the SDK is what your frontend calls. A surprising field name usually means you're reading the REST view. Discover any shape not pinned here with `SearchWixSDKDocumentation`, not by guessing a URL.
+
+> **⚠️ pricing-plans is a HARD dependency on members.** Ordering a plan and the "my subscription" surface both require a **logged-in member** (browsing the grid is public). So this recipe is always paired with member auth — read the matching **`how-to-code-members-astro.md`** or **`how-to-code-members-non-astro.md`** for the login flow. A logged-in member ordering their own plan needs **no `auth.elevate`** and **no `onBehalf`**.
+
+---
+
+## The modules and the client (read this first)
+
+**⚠️ Two different packages — use the headless one.** The Wix docs surface `checkout.startOnlinePurchase()` / `checkout.createOnlineOrder()` under **`@wix/site-pricing-plans`** — that is the **Wix-site (Velo / `$w` page-code) package**, and `startOnlinePurchase` drives the **Wix Pay frontend UI** that only exists inside a hosted Wix page. **It is NOT the headless path** — do not import `@wix/site-pricing-plans` in a headless frontend. Use **`@wix/pricing-plans`** (the universal/headless SDK), whose `orders.createOnlineOrder` creates the order and leaves payment to a redirect you drive (see *Subscribing*).
+
+| Need | Package | Module / namespace |
+|---|---|---|
+| List / read plans (the grid) | `@wix/pricing-plans` | `plansV3` (Plans V3 — `queryPlans`, `getPlan`) |
+| Order a plan + read a member's orders | `@wix/pricing-plans` | `orders` (`createOnlineOrder`, `memberListOrders`, `memberGetOrder`) |
+| Member login / current member | `@wix/members` + `@wix/sdk` auth | see the members recipe (`getCurrentMember`, `loggedIn()`) |
+| Book a service with a membership (integration) | `@wix/bookings` + `@wix/ecom` (+ `@wix/redirects`) | `bookings` (`createBooking`), ecom `checkout` (`membershipOptions`) — see *Booking with a membership* |
+
+**Never** import `@wix/site-pricing-plans` in headless code, and don't reach for a V1 `plans`-collection query — Plans V3 (`queryPlans` → `pricingVariants`) is the shape the seed creates.
+
+> **⚠️ The read module is `plansV3`, not `plans`.** In the `@wix/pricing-plans` SDK, `queryPlans`/`getPlan` live on the **`plansV3`** namespace (`import { plansV3, orders } from '@wix/pricing-plans'`). Importing `plans` and calling `plans.queryPlans()` fails to type-check (`Property 'queryPlans' does not exist`). `orders` keeps its own namespace.
+
+**Auth / client — framework split** (same split as every other coding recipe):
+- **Astro (Wix-managed):** auth is ambient — call `plansV3` / `orders` directly from server components / `src/pages/api/*`. Member identity rides on the call automatically after login (`how-to-code-members-astro.md`). **No `createClient`, no `OAuthStrategy`, no `clientId`.** A member reading their own orders needs **no `auth.elevate`**.
+- **Non-Astro (Vite/React/Vue/static):** build one manual client and reuse it — the **same** `OAuthStrategy` client the members/visitor flow already builds (don't make a second one). After the member-login handshake sets member tokens on it, `orders.*` runs as that member:
+  ```js
+  import { createClient, OAuthStrategy } from '@wix/sdk';
+  import { plansV3, orders } from '@wix/pricing-plans';
+  const client = createClient({ modules: { plansV3, orders }, auth: OAuthStrategy({ clientId: /* public OAuth id */ }) });
+  ```
+
+> **The connected site must be PUBLISHED** — the Pricing Plans APIs return nothing / error against an unpublished site and don't work in preview (same precondition as member login). Publish before testing.
+
+---
+
+## The features (build the ones the site needs)
+
+Each subsection is self-contained — build only what the site uses.
+
+### Listing plans for the grid (public, and the `_id` rule)
+
+```js
+const { items } = await plansV3.queryPlans()
+  .eq('visibility', 'PUBLIC')
+  .find();                                    // items[] of Plan
+```
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/query-plans.md?apiView=SDK>
+
+- **The grid read is public** — a visitor token lists `PUBLIC` plans; no login needed just to browse.
+- **⚠️ Entity id is `_id`, not `id`** — `plan._id` is what you order by and key React lists on. (`plan.id` is `undefined` in SDK code — you're reading the REST view if you see `id`.)
+- **⚠️ Price lives in `pricingVariants[]`, NOT a top-level `price`.** Read the amount from `plan.pricingVariants[0].pricingStrategies[0].flatRate.amount` (a **decimal string** — parse before math) and the cycle from `plan.pricingVariants[0].billingTerms.billingCycle` (`{ period: "MONTH", count: "1" }`). A free plan has no `flatRate` amount; a one-time plan has different `billingTerms` (see the seed recipe). `plan.currency` is the site's currency — format from it, don't assume USD.
+- **Show only `buyable` plans with a buy button.** `visibility: "PUBLIC"` can still be `buyable: false` (assign-only) — render those without a subscribe action, or filter them out.
+- **Perks** for the plan card are `plan.perks[]` (each `{ _id, description }`) — display-only text. (`queryPlans` returns them; if a summary trims them, `plansV3.getPlan(planId)` returns the full object.)
+
+### Subscribing (ordering) a plan — login-gated
+
+Ordering is a **member** action. Gate the subscribe button on `client.auth.loggedIn()` (non-Astro) / a resolved member (Astro) and bounce anonymous users into the login flow first (members recipe). Then:
+
+```js
+const { order } = await orders.createOnlineOrder(planId);   // planId = plan._id; logged-in member ⇒ no onBehalf
+// order.status: "DRAFT" (payment not yet made) | "ACTIVE" (free plan — already applied)
+```
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/orders/create-online-order.md?apiView=SDK>
+
+- **⚠️ A logged-in member needs no `onBehalf`** — the order is created on their behalf from the member identity. `onBehalf.memberId` is only for an app/admin identity ordering *for* someone (and needs elevation) — don't reach for it in a normal member flow.
+- **⚠️ `DRAFT` ≠ subscribed.** `createOnlineOrder` **orders but does not pay** — a paid plan comes back `status: "DRAFT"` and is not active until payment completes. Do not show "you're subscribed" off the `createOnlineOrder` return for a paid plan.
+- **Free plan:** returns `status: "ACTIVE"` (`lastPaymentStatus: "NOT_APPLICABLE"`) directly — no payment step; render success immediately. **Branch on the plan being free** (no `flatRate` amount / total `0`) to skip the redirect below.
+- **⚠️ Paid plan — the payment redirect handoff is the one piece not pinned by the docs for headless.** The all-in-one `startOnlinePurchase` that completes payment is the **site-package** method (above), unavailable headless; the headless `createOnlineOrder` returns a `DRAFT` order carrying a `wixPayOrderId`, and the member must be sent to a hosted payment flow to complete it. **⚠️ VERIFY IN A LIVE BUILD:** confirm the exact headless redirect — whether you pass the order to `@wix/redirects` `createRedirectSession({ paymentCheckout: { … } })`, or a pricing-plans-specific redirect — before shipping the paid path. Do not assert a specific call here until a real build confirms it. (The `origin`/`postFlowUrl` allowlist + `https`-host rules from `how-to-code-a-store.md`/`how-to-code-bookings.md` apply to whatever redirect is used.) The **free-plan** path above is fully client-only and needs no redirect.
+- **⚠️ SCOPE — the frontend's job ends at `createOnlineOrder` + the payment redirect. STOP THERE.** Do **NOT** try to *complete or activate* the purchase from code: don't connect a payments provider (`payments/v1/wix-payments-account/connect`), don't `PATCH`/update-plan to force a state, don't call mark-as-paid, and don't hunt for an "admin way to activate the order" or to "enable payments for a $0 order." Payment completing (a paid order flipping `DRAFT → ACTIVE`) happens **out-of-band** on Wix's hosted flow / by the merchant configuring payments — it is **not** a frontend step, and chasing it is a rabbit hole (it burns the run and ships nothing extra). A **free** plan already returns `ACTIVE` with no payment; a **paid** plan is `DRAFT` until the member pays through the redirect. If the site has **no payment provider configured**, that's a **site-setup precondition** (like the events paid-ticket precondition) — surface it, don't try to fix it in code.
+
+### The member's "my subscription" surface — login-gated
+
+```js
+// the logged-in member's own orders:
+const res = await orders.memberListOrders();       // filtered: orders.memberListOrders({ planIds, orderStatuses, paymentStatuses, limit, offset })
+// ⚠️ member-scoped reads are memberListOrders / memberGetOrder — there is NO `orders.listOrders`/`getOrder` (those are the admin `managementListOrders`/`managementGetOrder`, server/elevate only).
+// ⚠️ filter args are TOP-LEVEL limit/offset, NOT a nested `paging` object.
+// each order: { _id, planId, subscriptionId, status, lastPaymentStatus, startDate, endDate, currentCycle, planName, pricing, planPrice }
+```
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/orders/introduction.md?apiView=SDK>
+
+- **⚠️ Login required — returns nothing for an anonymous visitor.** Gate this surface behind auth; don't render "my subscription" for a logged-out user.
+- **"Currently active" = `status === "ACTIVE"` AND now is within `startDate`…`endDate`.** A `CANCELED` order can still be within its paid period until `endDate`; `autoRenewCanceled: true` means it won't renew but may still be active now. Don't treat `CANCELED` as "no access" without checking the date window.
+- Same **no-`auth.elevate`** rule: a member reading their own orders is authorized under the member token. Listing *all* members' orders is the admin/elevate axis (server-only) — not this.
+
+### Booking a service with a membership (the integration — only when the site also has Bookings)
+
+This is the payoff of the seed's STEP 2: a member who holds a plan that **covers** a service books it **with the membership** instead of paying per booking. Build the normal Bookings flow from **`how-to-code-bookings.md`** (list services → pick a slot → collect the form → `createBooking` → ecom cart/checkout); the membership is a **delta on that flow**, not a separate path:
+
+1. **Require login** — membership payment resolves against the member identity (a covered service booked anonymously just falls back to pay-per-booking).
+2. **On `createBooking`, set `selectedPaymentOption: "MEMBERSHIP"`** (instead of `ONLINE`/`OFFLINE`). Enum values: `ONLINE`, `OFFLINE`, **`MEMBERSHIP`** (pay with a pricing plan), `MEMBERSHIP_OFFLINE`. Doc: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md?apiView=SDK>
+3. **The booking still rides the ecom checkout** (Bookings is an ecom catalog, appId `13d21c63-b5ec-5912-8397-c3a5ddb27a97`) — the membership is applied **on the checkout**, not on the booking object. The eligible plan surfaces on the **ecom Checkout** entity's `membershipOptions`:
+   - `membershipOptions.eligibleMemberships[]` — the member's plans that can cover the line item (each `{ _id, appId, name, credits }`).
+   - apply one via `checkout.updateCheckout(...)` setting `membershipOptions.selectedMemberships.memberships = [{ _id, appId, lineItemIds: [<booking line item id>] }]`. When the membership covers the full price, `payNow` drops to `0`.
+   Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/checkout/get-checkout.md?apiView=SDK>
+4. **⚠️ Do NOT call `confirmBooking`** — for a membership payment Wix **auto-confirms** the booking on redemption (the same "no confirmBooking" rule as `how-to-code-bookings.md`; the membership drives confirmation).
+
+- **⚠️ Eligibility / coverage is a LIVE read, never a hardcoded plan→service map.** A new eligible plan, or a service newly added to a plan's coverage in the backoffice, **must be honored with no code change** — so never freeze the seed-time `{ planId → serviceIds }` map into the frontend. **Preferred:** read `checkout.membershipOptions.eligibleMemberships` — the plans that can cover *this* line item, computed server-side from live coverage. (It's tagged "reserved for internal use" in the schema, so **VERIFY IN A LIVE BUILD** whether a headless member token reads it client-side.) **Fallback if that field comes back empty for a member token:** list the member's active orders (`orders.memberListOrders`, `status: ACTIVE` within the date window) and match each `planId` against the plan's **live** Benefit-Program coverage (query the program's items — the same API `setup-pricing-plans.md` STEP 2 wrote to — at request time; do **not** read a coverage map baked into code). Set `selectedPaymentOption: "MEMBERSHIP"` + `selectedMemberships` from whichever read succeeds.
+- **⚠️ A `MEMBERSHIP` booking on a service the plan does NOT cover fails at checkout** (unless `skipSelectedPaymentOptionValidation`, which needs elevation — don't use in a member flow). Only offer "book with membership" for services actually covered by one of the member's active plans; otherwise fall back to the normal paid booking (`how-to-code-bookings.md`).
+- **Credit/session plans:** for a limited (non-unlimited) plan, `eligibleMemberships[].credits.remaining` matters — `0` remaining is not eligible. An unlimited plan (seed `price:"0"`) has no credit ceiling.
+
+### Out of scope (do not build these)
+- **Completing/activating payment from code** — connecting a payments account, marking orders paid, forcing an order `ACTIVE`, "activating" a subscription server-side. Payment is the member's hosted-flow step or a merchant dashboard/config task, never frontend code (see the SCOPE callout under *Subscribing*).
+- **Configuring which services a plan covers** — that coverage is wired at seed time via Benefit Programs (`setup-pricing-plans.md` STEP 2); the frontend only *reads/uses* it, it doesn't create or edit it.
+- **Cancelling / pausing / refunding a subscription, and dunning/renewal management** — post-purchase lifecycle beyond a read-only "my subscription" view is the hosted member area / dashboard, not this build.
+- **Offline orders** (`createOfflineOrder` / mark-as-paid) — a merchant/admin flow, not a member-facing frontend one.
+
+---
+
+## Conclusion
+A correct Pricing Plans frontend:
+- imports **`@wix/pricing-plans`** (`plansV3`, `orders`) — **never** `@wix/site-pricing-plans` (its `startOnlinePurchase` is Wix-site page-code, not headless);
+- lists the grid publicly with **`plansV3.queryPlans().eq('visibility','PUBLIC')`**, reads **`plan._id`** and price from **`pricingVariants[].pricingStrategies[].flatRate.amount`** (decimal string) — never a top-level `price` — and only shows a buy button on `buyable` plans;
+- treats **subscribe and my-subscription as login-gated** (the hard members dependency), orders with **`orders.createOnlineOrder(planId)`** (no `onBehalf`, no elevate), renders free plans as `ACTIVE` immediately, and drives paid plans through a payment redirect (**exact headless redirect to be confirmed in a live build**) — and **stops at the redirect**: no payments-account connect, no order activation / mark-as-paid from code (see *Out of scope*);
+- for the Bookings integration, books a covered service by setting **`selectedPaymentOption: "MEMBERSHIP"`** on `createBooking`, applies the membership on the **ecom checkout** (`membershipOptions`), never calls `confirmBooking`, and falls back to matching the member's active-order `planId`s to the service's coverage when the checkout eligibility field isn't readable client-side.

package/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md

@@ -0,0 +1,188 @@
+---
+name: "How to Code Restaurant Orders"
+description: The frontend cart/checkout contract for a Wix Restaurants Online-Ordering site — which SDK modules to import, how to read the ordering operation + fulfillment methods, the exact restaurant add-to-cart shape (appId = Orders app, options = operationId+menuId+sectionId, NOT variantId), and checkout via eCommerce. Specifies the *how* (modules + exact calls + failure modes); which menu/items to sell come from the request.
+---
+**RECIPE**: How to Code a Wix Restaurants Ordering Frontend (Online Orders + eCommerce cart)
+
+A contract for the **frontend code** that lets a visitor **order** from a Wix Restaurants menu: reading the ordering operation and fulfillment methods, adding a menu item to the eCommerce cart with the restaurant `catalogReference`, and checking out. **This recipe is the *how* (which modules, which calls, which fields), not the *what*** — which menu/items to sell and how the page looks come from the request you're fulfilling.
+
+> **This recipe is for CODING ordering, not seeding it.** It assumes the backend already exists — a Restaurants **Menus** backend (menu → sections → items) **and** the Restaurants **Orders** app installed and configured (an `ENABLED` operation with fulfillment methods, every menu ordering-enabled). See `setup-restaurants.md` + `setup-restaurant-orders.md` for the backend. This recipe says nothing about creating any of it — only how to read and purchase from frontend code.
+
+> **Reading (displaying) the menu is a SEPARATE recipe — pair this with it.** `how-to-code-restaurants.md` covers listing menus/sections/items, assembling the hierarchy in `sectionIds`/`itemIds` order, reading `item.priceInfo.price`, and rendering images. That recipe is **display-only** (no cart). **This** recipe adds the **ordering** layer on top: it consumes the same `menus`/`sections`/`items` reads and needs each rendered item's `_id`, its section's `_id`, and the menu's `_id` to build a cart line. Don't duplicate the menu-reading here — read it there, order it here.
+
+> **⚠️ 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` cart bug. Fetch the `.md?apiView=SDK` form directly; don't re-discover these with search.
+
+---
+
+## The modules and the client (read this first)
+
+**Restaurants Orders app id** (a constant you need for the cart's `catalogReference.appId`):
+`9a5d83fd-8570-482e-81ab-cfa88942ee60`
+
+**⚠️ This is the ORDERS app id, NOT the Stores app id.** A restaurant menu item added to the cart must carry `appId: '9a5d83fd-…'` (Orders). Using the Stores id (`215238eb-…`) — muscle memory from `how-to-code-a-store.md` — makes eCommerce resolve the line against the wrong catalog and the add fails. Menu items are **not** Stores products.
+
+| Need | Package | Module (namespace) |
+|---|---|---|
+| Menus / sections / items (display) | `@wix/restaurants` | `menus` / `sections` / `items` — see `how-to-code-restaurants.md` |
+| The ordering operation (for `operationId`) | `@wix/restaurants` | `operations` |
+| Fulfillment methods (pickup/delivery to show) | `@wix/restaurants` | `fulfillmentMethods` |
+| Cart (add / get / checkout) | `@wix/ecom` | `currentCart` |
+| Redirect to hosted checkout | `@wix/redirects` | `redirects` |
+
+**Auth / client — framework split:**
+- **Astro (Wix-managed):** authentication is ambient. Call `operations` / `fulfillmentMethods` / `currentCart` directly from server components and backend routes (`src/pages/api/*.ts`) — **no `createClient`, no `OAuthStrategy`, no `clientId`.**
+  ```js
+  import { operations, fulfillmentMethods } from '@wix/restaurants';
+  import { currentCart } from '@wix/ecom';
+  const { operations: ops } = await operations.listOperations();
+  ```
+- **Non-Astro (Vite/React/Vue/static):** build one manual visitor client and reuse it:
+  ```js
+  import { createClient, OAuthStrategy } from '@wix/sdk';
+  import { menus, sections, items, operations, fulfillmentMethods } from '@wix/restaurants';
+  import { currentCart } from '@wix/ecom';
+  import { redirects } from '@wix/redirects';
+
+  const client = createClient({
+    modules: { menus, sections, items, operations, fulfillmentMethods, currentCart, redirects },
+    auth: OAuthStrategy({ clientId: /* the project's PUBLIC OAuth client id */ }),
+  });
+  // then: await client.operations.listOperations(), await client.currentCart.addToCurrentCart({...})
+  ```
+  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)
+
+These are **SDK read shapes** (`?apiView=SDK`), so entity ids are **`_id`**. Prices/fees are decimal **strings**. The cart-add body (under *Adding a menu item to the cart*) is a separate **write** shape; the `_id` rule applies to read **entities**, not to method-return wrappers (note `checkoutId`).
+
+```jsonc
+// operations.listOperations()  →  { operations: [...] }   (no arguments)
+operation = {
+  _id,                        // → cart options.operationId   (NOT .id → undefined)
+  name, default,              // the auto-created ordering operation has default: true
+  onlineOrderingStatus,       // "ENABLED" when the site is taking orders
+  fulfillmentIds,             // ids of the fulfillment methods attached to this operation
+  defaultFulfillmentType,     // "PICKUP" | "DELIVERY"
+}
+
+// fulfillmentMethods.listFulfillmentMethods()  →  { fulfillmentMethods: [...] }
+fulfillmentMethod = {
+  _id, type,                  // "PICKUP" | "DELIVERY"
+  name, enabled,              // show only enabled:true to the visitor
+  fee, minOrderPrice,         // decimal STRINGS ("0", "5") — no currency symbol
+  pickupOptions,              // present when type PICKUP
+  deliveryOptions,            // present when type DELIVERY (deliveryTimeInMinutes, deliveryArea, …)
+}
+
+// item (from items.listItems — see how-to-code-restaurants.md)
+item = { _id, name, priceInfo: { price } }   // price is a decimal STRING; _id → cart catalogItemId
+
+// currentCart.getCurrentCart()  →  { lineItems: [...] }
+lineItem = { quantity, price: { amount }, image }   // amount is the string price; image is wix:image:// → resolve
+
+// currentCart.createCheckoutFromCurrentCart({ channelType })  →  { checkoutId }   // a STRING — NOT { checkout }, NOT _id
+// redirects.createRedirectSession({ ecomCheckout: { checkoutId }, callbacks })  →  { redirectSession: { fullUrl } }
+```
+
+---
+
+## The features (build the ones the site needs)
+
+Each subsection is a **self-contained feature** — implement only what the site uses. The only ordering is *within* a feature (read the operation before you build a cart line that references it).
+
+### Reading the ordering operation (and the `_id` rule)
+
+Get the operation so you have the **`operationId`** every cart line needs. `listOperations()` takes **no arguments** and returns a plain array.
+
+```js
+const { operations: ops = [] } = await operations.listOperations();
+const op = ops.find((o) => o.onlineOrderingStatus === 'ENABLED') ?? ops.find((o) => o.default) ?? ops[0];
+const operationId = op._id;
+```
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/operations/list-operations.md?apiView=SDK>
+
+**⚠️ `list*` return the array as OPTIONAL — default it (`= []`) or the strict build fails.** `listOperations()` / `listFulfillmentMethods()` / `listItems()` type the returned array as `T[] | undefined`, so destructuring `{ operations: ops }` and calling `ops.find(...)` directly errors under `strict` / `astro check` (`'ops' is possibly 'undefined'`, TS18048) — a build-breaker on managed Astro. Default it in the destructure (`{ operations: ops = [] }`) or guard with `?? []`.
+
+**⚠️ CRITICAL: the entity id is `_id`, NOT `id`.** `operation.id` / `item.id` / `section.id` are `undefined` in SDK code. Feeding `operation.id` into `options.operationId` (or `item.id` into `catalogItemId`) sends an empty string and the add-to-cart fails. Use `_id` everywhere. (A surprising `id` field means you're reading the REST doc view — re-open with `?apiView=SDK`.)
+
+**Read the operation once and reuse `operationId`** for every add-to-cart on the page — don't call `listOperations()` per line item.
+
+### Reading fulfillment methods (pickup / delivery to show)
+
+List the methods to render the visitor's pickup/delivery choices (fee, minimum, type). Show only `enabled: true`.
+
+```js
+const { fulfillmentMethods: methods = [] } = await fulfillmentMethods.listFulfillmentMethods();
+const offered = methods.filter((m) => m.enabled);
+```
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/fulfillment-methods/list-fulfillment-methods.md?apiView=SDK> (default the array `= []` — see the optional-array note above)
+
+**⚠️ `listFulfillmentMethods` takes an OPTIONS object, not a query builder.** It accepts an optional `{ paging }` object and returns a `Promise` of `{ fulfillmentMethods }` directly — do **not** chain `.find()`/`.eq()` on it (that's the `queryProducts` builder pattern from stores; it does not apply here). `fee` and `minOrderPrice` are decimal **strings** — render them with your currency, and `Number(...)` only if you need arithmetic. Which method the buyer actually uses (and the delivery time slot) is chosen on the **hosted checkout**; listing here is for display, not a required pre-checkout step.
+
+### Adding a menu item to the cart — the restaurant `catalogReference`
+
+This is the one shape that differs materially from a Stores cart. Build a line item whose `catalogReference` names the **Orders app** and carries **`operationId` + `menuId` + `sectionId`** in `options`.
+
+```js
+await currentCart.addToCurrentCart({
+  lineItems: [{
+    quantity,
+    catalogReference: {
+      catalogItemId: item._id,                              // the MENU ITEM's _id
+      appId: '9a5d83fd-8570-482e-81ab-cfa88942ee60',        // the ORDERS app id (not Stores)
+      options: {
+        operationId,                                        // from listOperations()
+        menuId,                                             // the _id of the menu the item is shown in
+        sectionId,                                          // the _id of the section the item is shown under
+      },
+    },
+  }],
+});
+```
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/add-to-current-cart.md?apiView=SDK>
+
+**⚠️ CRITICAL: `options` MUST carry `operationId`, `menuId`, AND `sectionId` — all three.** A restaurant line item is identified by *where in the menu it was ordered from*, not by a variant. Omitting any of the three makes eCommerce unable to resolve the item against the Restaurants catalog — the add fails or the line can't be checked out. This is the restaurant analog of the store's mandatory `variantId`, and it fails the same quiet way.
+
+**⚠️ CRITICAL: there is NO `variantId` here.** `options.variantId` is a **Stores** concept — menu items have no variants in this flow. Don't copy the store recipe's `variantId` resolution; a restaurant line uses `operationId`/`menuId`/`sectionId` instead. (Menu item *modifiers* — "extra cheese" — are a separate concern and out of scope for the basic order flow.)
+
+**⚠️ Thread `sectionId` and `menuId` from the render, not a lookup.** When you assemble the menu (menu → sections → items, per `how-to-code-restaurants.md`), each item is rendered **inside** a known section and menu — capture that `section._id` and `menu._id` at render time and pass them to the add-to-cart handler alongside `item._id`. Re-deriving an item's section afterward is unnecessary and error-prone; you already have it in the render context.
+
+Optional: `options.onlineOrderingPageUrl` (e.g. `"/online-ordering"`) lets the buyer click the cart line to return to the item — include it only if your site has such a page.
+
+### Checkout
+
+Create a checkout from the current cart, then redirect the buyer to the hosted checkout (identical to the storefront flow — restaurant orders ride on the same eCommerce checkout).
+Docs: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/create-checkout-from-current-cart.md?apiView=SDK> · <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/get-current-cart.md?apiView=SDK>
+
+```js
+const checkout = await currentCart.createCheckoutFromCurrentCart({ channelType: currentCart.ChannelType.WEB });
+const session = await redirects.createRedirectSession({
+  ecomCheckout: { checkoutId: checkout.checkoutId },   // checkout.checkoutId — NOT checkout._id
+  callbacks: { postFlowUrl: `${origin}/`, thankYouPageUrl: `${origin}/` },
+});
+window.location.href = session.redirectSession.fullUrl; // the hosted-checkout URL (fulfillment + time slot chosen here)
+```
+
+**⚠️ `createCheckoutFromCurrentCart` returns `checkout.checkoutId`** (a string), **not** `checkout._id`. Reading `checkout._id` (over-applying the `_id` rule) throws *"Cannot read properties of undefined (reading '_id')"* — the silent checkout crash. The `_id` rule is for read **entities**, not method-return wrappers.
+
+**⚠️ CRITICAL: `origin` for `postFlowUrl`/`thankYouPageUrl` MUST be the `https://` published host — derive it from `window.location.origin`, NEVER `new URL(request.url).origin`.** The Headless redirect allowlist registers the site's **`https://`** host and treats `http://<same host>` as a different, unlisted origin. If you build the redirect session in a **server route** (`src/pages/api/*`), `new URL(request.url).origin` resolves to `http://` behind Wix's TLS-terminating proxy → the buyer's return redirect **403s** with *"… isn't listed as an allowed redirect domain."* Pass `window.location.origin` from the client into the route (or force the scheme to `https`). Doc: <https://dev.wix.com/docs/go-headless/getting-started/setup/manage-urls/add-allowed-redirect-domains>.
+
+**⚠️ LIVE PAID CHECKOUT PRECONDITION.** A visitor can add to cart and reach the hosted checkout with just this code, but **completing a paid order** needs the site to have a **premium plan and a configured payment method**. That's site provisioning, not a frontend bug — if checkout can't collect payment, the setup is incomplete, not the code.
+
+### Reading the price and the cart
+
+Menu item price is **`item.priceInfo.price`** — a decimal **string** with no currency symbol (see `how-to-code-restaurants.md`; the SDK `PriceInfo` type has only `price`, no `formattedPrice`). A cart line's price is **`lineItem.price.amount`** (also a string). Prefix your own currency in the UI. Cart line images are `wix:image://` identifiers — resolve them with `media.getScaledToFillImageUrl(id, w, h, {})` (4 args), never raw (see the store/menu recipes' image callout).
+
+---
+
+## Conclusion
+A correct Restaurants ordering frontend:
+- imports **`operations` / `fulfillmentMethods` from `@wix/restaurants`** (plus `menus`/`sections`/`items` for display) and **`currentCart` / `redirects`** from `@wix/ecom` / `@wix/redirects`;
+- uses **`_id`** (never `id`) for the operation, menu, section, and item;
+- reads the **`operationId`** once from `listOperations()` (the `ENABLED`/`default` operation) and reuses it;
+- adds menu items with the **Orders app id `9a5d83fd-…`** (never the Stores id) and `options` carrying **`operationId` + `menuId` + `sectionId`** (all three) — **no `variantId`**;
+- threads `menuId`/`sectionId` from the render context, not a re-lookup;
+- checks out via **`createCheckoutFromCurrentCart` → `checkout.checkoutId` → `redirects`**, with an **`https://` `window.location.origin`** for the callbacks; the hosted checkout collects fulfillment + payment (which needs a premium plan + payment method).
+</content>