@wix/agent-skills 1.16.3 → 1.18.0

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

@@ -0,0 +1,254 @@
+---
+name: "How to Code Rentals"
+description: The frontend read/booking contract for a Wix Rentals site — a delta on how-to-code-bookings.md. Covers filtering the catalog to rentals, the two-call hourly availability flow (start slots then end options), the consecutive-day walk for daily rentals, duration-based price preview, and the createBooking → ecom Cart V2 → checkout-or-place sequence with the rentals app id. Specifies the *how* (modules + exact calls + rentals-specific failure modes); which rentals to render and how the page looks come from the request.
+---
+**RECIPE**: How to Code a Wix Rentals Frontend (Services V2 duration ranges + ecom Cart V2 checkout)
+
+> **⚠️ Read `how-to-code-bookings.md` first — this recipe is a DELTA on it, not a replacement.** Wix Rentals runs on the Wix Bookings APIs, so the client setup, the schema-driven booking form, the `createBooking → ecom Cart V2 → checkout-or-place` sequence, and the `postFlowUrl` HTTPS trap are **all identical** and are documented there. This file covers **only what differs for a rental**: finding rentals, duration-range availability, duration-based pricing, and the handful of rentals-specific errors.
+
+> **⚠️ There is no `@wix/rentals` package, and that is not a gap.** Rentals is `@wix/bookings` with rentals-specific field values. If a run concludes "Wix Rentals has no headless surface" because npm has no `@wix/rentals`, that conclusion is wrong — build on `@wix/bookings`.
+>
+> **Rentals doc set** (four pages, where to go beyond this recipe): [About Wix Rentals](https://dev.wix.com/docs/api-reference/business-solutions/rentals/introduction.md) · [Rentals and the Bookings APIs](https://dev.wix.com/docs/api-reference/business-solutions/rentals/wix-rentals-and-the-bookings-apis.md) (concept → API map) · [About Rentals Availability](https://dev.wix.com/docs/api-reference/business-solutions/rentals/about-wix-rentals-availability.md) · [Sample Flows](https://dev.wix.com/docs/api-reference/business-solutions/rentals/sample-flows.md) (the booking sequences below, end to end).
+
+> **⚠️ Reading rule — always append `.md?apiView=SDK` to every doc link below.** The bare/REST view shows `id`; the SDK view shows `_id`, and the SDK is what your frontend calls.
+
+---
+
+## Constants and modules (the delta)
+
+**Constants** (e.g. `src/services/constants.ts`):
+- **Wix Rentals app id** — `ff5d6eb1-65e4-4f9a-8b14-64d34c12cc2e`. Used **three times**: to filter the catalog to rentals, as the cart's `catalogReference.appId`, and to filter bookings reads (§Cancellation).
+
+**Modules** — all on `@wix/bookings`, alongside the ones `how-to-code-bookings.md` already lists:
+
+| Need | Package | Module |
+|---|---|---|
+| Rental catalog with availability/attribute filters | `@wix/bookings` | `catalogSearch` (`queryServicesByFilters`) |
+| Start times for a rental | `@wix/bookings` | `availabilityTimeSlots` (`listAvailabilityTimeSlots`) |
+| End times for an **hourly** rental | `@wix/bookings` | `availabilityTimeSlots` (`listAvailabilityTimeSlotEndOptions`) |
+| Duration-based price before booking | `@wix/bookings` | `pricing` (`previewPrice`) |
+| Create the booking / cart / redirect | *(unchanged)* | see `how-to-code-bookings.md` |
+
+---
+
+## 1 · Find the rentals
+
+**⚠️ CRITICAL: always filter by the rentals app id.** Rentals share every API with Bookings. On a site that has both, an unfiltered `queryServices` returns haircuts next to meeting rooms. Every catalog read must carry `appId = ff5d6eb1-65e4-4f9a-8b14-64d34c12cc2e`.
+
+`catalogSearch.queryServicesByFilters` is the right entry point for a rental catalog: it filters **and** resolves availability in one call.
+
+```js
+const { results, pagingMetadata } = await catalogSearch.queryServicesByFilters({
+  query: {
+    filter: { appId: RENTALS_APP_ID },
+    sort: [{ fieldName: 'name', order: 'ASC' }],
+    cursorPaging: { limit: 20 },
+  },
+  serviceFilters: {
+    localStartDate: '2026-09-01T00:00:00',   // omit the window entirely to skip the availability check
+    localEndDate:   '2026-09-08T00:00:00',   // exclusive — start of the day AFTER the window
+    timeZone: 'America/New_York',
+  },
+});
+```
+
+- Each entry in `results` carries the full `service` plus an **`available`** flag. With a window set and `exactMatch` left unset, a service comes back when it has **at least one** bookable slot anywhere in the window.
+- **End the window at `00:00:00` of the day *after* the range you want, not at `23:59:59`.** The end boundary is exclusive, so a 23:59:59 end silently drops the last minute of the final day. This matches the daily-booking convention in §3, where a rental's `endDate` is midnight of the day after the last rented day.
+- **To grey out rather than hide** unavailable rentals, set `serviceFilters.includeUnavailable: true` — those come back with `available: false`.
+- **Paginate** by passing `pagingMetadata.cursors.next` back **unchanged** as `query.cursorPaging.cursor`, until `next` is absent.
+- **Location and attribute filters** live in `serviceFilters` too — `locationIds`, `resourceTypes`, and `attributes`. Within one attribute, values are **match-any**; across different attributes, **match-all**.
+- With **no** date range, no availability check runs and everything returns `available: true`.
+
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/catalog-search/query-services-by-filters.md?apiView=SDK>
+
+**Read the range off the service** to drive the UI — it tells you which of the two flows below applies:
+
+```js
+const range = service.schedule?.availabilityConstraints?.durationRange;
+const isDaily = range?.unitType === 'DAY';
+const min = isDaily ? range.dayOptions.minDurationInDays    : range.hourOptions.minDurationInMinutes;
+const max = isDaily ? range.dayOptions.maxDurationInDays    : range.hourOptions.maxDurationInMinutes;
+```
+
+---
+
+## 2 · Hourly availability — two calls, start then end
+
+A fixed-duration service has one slot list. A rental has **two steps**: the customer picks a start, then picks how long.
+
+**Step 1 — start times.**
+
+```js
+const { timeSlots } = await availabilityTimeSlots.listAvailabilityTimeSlots({
+  serviceId,
+  timeZone,
+  fromLocalDate: '2026-09-01T00:00:00',
+  toLocalDate:   '2026-09-02T00:00:00',   // exclusive — start of the next day, not 23:59
+  includeResourceTypeIds: [resourceTypeId],   // the service's primaryResourceType
+  bookable: true,
+});
+```
+
+**⚠️ Pass `includeResourceTypeIds` with the service's `primaryResourceType`, or the slots come back with no resource to book.** Each slot then carries its bookable resource in `availableResources` — carry that forward, `createBooking` needs it.
+
+**Step 2 — end times for the chosen start.**
+
+```js
+const { endOptions } = await availabilityTimeSlots.listAvailabilityTimeSlotEndOptions(
+  serviceId,                                   // ⚠️ POSITIONAL first argument, not part of the options object
+  { localStartDate: selected.localStartDate, timeZone, location: selected.location },
+);
+```
+
+- **⚠️ The response field is `endOptions`, NOT `timeSlots`.** `listAvailabilityTimeSlots` returns `timeSlots`; this call returns `endOptions`. Destructuring `timeSlots` here yields `undefined` and **no error** — the end-time picker just renders empty, which is indistinguishable from "no availability". If your length picker is mysteriously blank, check this first.
+- **`location` is REQUIRED** — pass the selected slot's own `location` straight through. Omitting it fails the call.
+- The service's **maximum duration caps the response**, so you don't need `maxLocalEndDate` — the cap defaults to `localStartDate` plus that maximum. What you actually get back also depends on availability: the options stop earlier if the resource isn't free that long, so the last end option is whichever comes first — the maximum duration, or the end of the free period.
+- Every entry shares the requested `localStartDate` and differs only in **`localEndDate`** — that is the end-time picker.
+- **`availableResources` is always empty on end options**, and `totalCapacity` is always `1`. Take the resource from **step 1**, not from here.
+- **⚠️ `END_OPTIONS_NOT_SUPPORTED`** means you called this for a **daily** or a fixed-duration service. End options are hourly-only — branch on `unitType` before calling.
+
+Docs: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots.md?apiView=SDK> · <https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slot-end-options.md?apiView=SDK>
+
+---
+
+## 3 · Daily availability — one call, then walk the days yourself
+
+There is **no end-options call for daily rentals.** You list days and compute the valid end dates client-side.
+
+**⚠️ `timeZone` must be the site's business timezone — see [the rentals availability docs](https://dev.wix.com/docs/api-reference/business-solutions/rentals/about-wix-rentals-availability.md#daily-availability) for why.** Don't use the visitor's browser timezone.
+
+```js
+const { timeSlots } = await availabilityTimeSlots.listAvailabilityTimeSlots({
+  serviceId, timeZone,
+  fromLocalDate, toLocalDate,
+  timeSlotsPerDay: 1,
+  includeResourceTypeIds: [resourceTypeId],
+  bookable: true,
+});
+```
+
+After the customer picks a start date, **iterate forward through the returned list and stop at the first gap, or when you hit the service's `maxDurationInDays`.** Those are the selectable end dates. A naive "start + max days" range will offer dates across a gap and then fail at booking time.
+
+**How a daily rental is stored depends on the resource's working hours — and it changes which call you make:**
+
+| Resource | Stored as | Booking call |
+|---|---|---|
+| **24/7** (no working-hours schedule) — the `setup-rentals.md` default | **one** booking spanning the whole range | `createBooking` |
+| **Has working hours** | a **linked group**, one booking per working day (2–8) | `createMultiServiceBooking` with `multiServiceBookingType: 'SEQUENTIAL_BOOKINGS'` |
+
+For the **24/7** case, set the boundaries to midnight-to-midnight: `startDate` = midnight on the first day, `endDate` = **midnight on the day after the last day**. A Monday–Wednesday inclusive rental ends at midnight on **Thursday**. **⚠️ Wix derives `allDay` itself — do not set it.**
+
+For the **working-hours** case, build one booking per day with that day's own working-period start and end (e.g. 09:00 → 18:00), and send them together. The group is created **all or nothing**: any unavailable or non-consecutive day fails the whole call.
+
+Docs: <https://dev.wix.com/docs/api-reference/business-solutions/rentals/about-wix-rentals-availability.md> · <https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-multi-service-booking.md?apiView=SDK>
+
+---
+
+## 4 · Price preview (duration-based)
+
+A rental's price depends on its length, so show the total before booking.
+
+```js
+const { priceInfo } = await pricing.previewPrice([{
+  serviceId,
+  resourceId,                       // required for appointment-based services
+  numberOfParticipants: 1,          // always 1 for a rental — see below
+  localStartDate: '2026-09-01T09:00:00',
+  localEndDate:   '2026-09-01T14:00:00',
+  timeZone,                         // required whenever the local dates are sent
+}]);
+// priceInfo.calculatedPrice
+```
+
+**⚠️ `numberOfParticipants` is required and is always `1` for a rental.** Omitting it, or sending `0`, fails with `NUMBER_OF_PARTICIPANTS_NOT_FOUND`. A rental isn't a class: one booking takes one resource, so participant count never drives the price — the duration does. The room's stated capacity ("seats 8") is a resource **attribute** for display, not a participant count. Same reasoning as `defaultCapacity: 1` on the service (`setup-rentals.md` STEP 4).
+
+**⚠️ Omitting `localStartDate` / `localEndDate` / `timeZone` does not error — it silently falls back to participant-based pricing** and returns a flat rate that ignores the duration. The customer then sees one price and is charged another. Always send all three.
+
+Hourly is prorated per minute (`minutes × base ÷ 60`); daily is `base × days`. Doc: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/pricing/pricing-api/preview-price.md?apiView=SDK>
+
+---
+
+## 5 · Book and check out
+
+> **⚠️ LIVE BOOKING PRECONDITION — the site needs a premium plan and a configured payment method.** On a free site the visitor flow fails at the last step: `createBooking` returns **`PREMIUM_VALIDATION_FAILED`**, and `placeOrder` returns **`SITE_NOT_ACCEPTING_PAYMENTS`**. That's site provisioning, not a frontend bug — if a booking can't complete, the setup is incomplete, not the code.
+>
+> Two things make this misleading. **The same `createBooking` succeeds as an admin (`WIX_USER`)**, so it reads like a permissions or payload bug when it's neither — always test the visitor path. And **switching the service to offline / pay-in-person does not avoid it**: `placeOrder` still requires the site to be accepting payments. Record the precondition and surface it to the owner; don't try to code around it.
+
+**Identical to `how-to-code-bookings.md` § "createBooking → cart → checkout"**, with four substitutions:
+
+1. **`endDate` is the customer's chosen end**, not a duration added to the start — that is the whole point of a rental.
+2. **`resource`** comes from the **start slot's** `availableResources` (§2 step 1 / §3). There is no ANY_RESOURCE staff fallback here; rentals are resource-driven.
+3. **Map the slot's `location` to the booking's `location`** — read the id as `slot.location.id ?? slot.location._id`, and write it under `_id`.
+4. **The cart's `catalogReference.appId` is the RENTALS app id**, not the Bookings one:
+
+```js
+const cart = await createCart({
+  catalogItems: [{ quantity: 1, catalogReference: { catalogItemId: bookingId, appId: RENTALS_APP_ID } }],
+  cart: { source: { channelType: 'WEB' } },
+});
+```
+
+Everything downstream — `calculateCart`, the checkout-vs-`placeOrder` decision, `redirects.createRedirectSession` and the HTTPS `postFlowUrl` rule — is unchanged. Follow `how-to-code-bookings.md`.
+
+**⚠️ One exception: do NOT call `getAnonymousActionToken` / `bookingsGetBookingAnonymously` for a rentals booking.** `how-to-code-bookings.md`'s confirmation-page step calls these client-side as the visitor. For rentals, `getAnonymousActionToken` returns `403` (the method requires the `Manage Bookings` scope, which the visitor doesn't have) — skip that whole step. Drive the confirmation page from what you already hold from `createBooking` / `placeOrder` / the redirect return instead; don't add a call to mint or read an anonymous token.
+
+---
+
+## 6 · SEO on item pages, and images
+
+**⚠️ There is no `WIX_APPS.rentals.*` and no `seoTags.ItemType.RENTAL`** — a rental detail page is a **Bookings service** item page, so it uses the **bookings** accessors:
+
+- **`wixMetadata`** from `WIX_APPS.bookings.servicePageMetadata` — referenced **directly** in the export (module scope). Route param `slug` → `identifiers.slug`.
+- **`itemType`**: `seoTags.ItemType.BOOKINGS_SERVICE`.
+
+Everything else about the three-step item-page SEO wiring (`wixMetadata` export → `loadSEOTagsServiceConfig(...)` → `<SEO.Tags>`, and running the config load in the same `Promise.all` with `.catch(() => null)`) is identical to `how-to-code-bookings.md` § "SEO on item pages".
+
+**Images** are the same trap too: `service.media.mainMedia.image` is a **string** holding a `wix:image://v1/…` URI, **not** an absolute URL. Resolve with `media.getImageUrl(...)` from `@wix/sdk` before putting it in `<img src>`, and guard items with no image.
+
+**Mount the slot picker, length picker and book action in a client-only island** (Astro) — availability is timezone- and session-specific. SSR only the catalog and detail reads, for SEO.
+
+---
+
+## Rentals-specific failure modes
+
+| Error | Cause | Handling |
+|---|---|---|
+| Empty length picker, no error | Destructured `timeSlots` from end options instead of **`endOptions`** | Rename the destructure (§2) |
+| `END_OPTIONS_NOT_SUPPORTED` | End options called for a daily or fixed-duration service | Branch on `durationRange.unitType` before calling |
+| `INVALID_DURATION_PROVIDED` | Chosen length falls outside the service's range | The response carries the allowed range — show it and return the customer to the picker |
+| `SLOT_NOT_AVAILABLE` | The slot was taken between selection and booking | Return to the slot picker and refresh availability |
+| Empty availability, no error | The service's resource type has **no resources** | A seed bug, not a frontend one — see `setup-rentals.md` STEP 2 |
+| Rentals mixed with appointments | A catalog read without the `appId` filter | Add `appId` to `query.filter` (§1) |
+| `NUMBER_OF_PARTICIPANTS_NOT_FOUND` | `numberOfParticipants` missing or `0` on the price preview | Send `1` — always 1 for a rental (§4) |
+| Price differs from what was shown | Price preview sent without `localStartDate`/`localEndDate`/`timeZone` | Send all three (§4) |
+| Booking created at the wrong location, or `location` silently empty | Read only `.location._id` (undefined) | Read both `.location.id ?? .location._id` (§5) |
+| Hunting for `WIX_APPS.rentals.*` or `seoTags.ItemType.RENTAL` | Neither exists | Use the **bookings** accessors — a rental detail page *is* a Bookings service page (§6) |
+| `.image.url` fails `tsc`, or images render broken | `media.mainMedia.image` is a **string** holding a `wix:image://` URI | `media.getImageUrl(...)` from `@wix/sdk` (§6) |
+
+---
+
+## Out of scope
+
+**Cancellation.** A logged-in member can cancel their own rental:
+
+- A **single** rental (hourly, or daily on a 24/7 resource) cancels with `cancelBooking` and its current `revision`.
+- A **multi-day group** (daily on a working-hours resource) cancels with `cancelMultiServiceBooking` and the group's **`multiServiceBookingInfo.id`**, read back off any booking in the group.
+
+**⚠️ Read the booking back with `queryExtendedBookings`, filtered on the rentals `appId`.** Without an `appId` (or `createdByAppId`) filter of your own, the query applies a default one that covers Bookings but **not** rentals, and returns **0** results — a rentals booking that exists looks like it doesn't. Naming `appId` in the filter suppresses that default:
+
+```js
+  filter: { appId: RENTALS_APP_ID },
+```
+
+Refunds are the eCommerce Orders API, not Bookings. Also out of scope, as in bookings: waitlists, deposit/payment breakdowns, and multi-item rental carts.
+
+## Conclusion
+
+- Rentals is **`@wix/bookings`** — there is no `@wix/rentals`, and its absence is not a missing capability.
+- **Every catalog read filters on the rentals `appId`**, or a mixed site shows the wrong services.
+- **Hourly** = two availability calls (start → `timeSlots`, then end options → **`endOptions`**, hourly-only, `location` required, `serviceId` positional). **Daily** = one call with `timeSlotsPerDay: 1`, then walk consecutive days client-side.
+- **Daily storage follows the resource:** 24/7 → one booking (midnight to midnight-after, never set `allDay`); working hours → a sequential multi-service group whose id you must persist yourself.
+- **Price preview needs both local dates and the time zone**, or it silently returns a duration-blind price.
+- Booking, cart, checkout and confirmation are the **bookings** flow, with the rentals app id on the cart's `catalogReference` — **except** the anonymous-token confirmation step, which rentals must skip entirely (§5).
+- **The slot's location id must be read defensively** as `.location.id ?? .location._id` — the SDK type says `_id`, but the field stays `.id` on the wire.
+- **SEO and images are the bookings ones too** — `WIX_APPS.bookings.servicePageMetadata` and `seoTags.ItemType.BOOKINGS_SERVICE`; there is no rentals-specific accessor to find.

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

@@ -26,28 +26,30 @@ A contract for the **frontend code** that lets a visitor **order** from a Wix Re
 | 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` |
+| Cart (add / get / checkout) | `@wix/ecom` | `currentCartV2` |
 | Redirect to hosted checkout | `@wix/redirects` | `redirects` |
 
+> Migrating from Cart V1 / Checkout V1? The code below is V2-only — see the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide) for the before/after.
+
 **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`.**
+- **Astro (Wix-managed):** authentication is ambient. Call `operations` / `fulfillmentMethods` / `currentCartV2` 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';
+  import { currentCartV2 } 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 { currentCartV2 } from '@wix/ecom';
   import { redirects } from '@wix/redirects';
 
   const client = createClient({
-    modules: { menus, sections, items, operations, fulfillmentMethods, currentCart, redirects },
+    modules: { menus, sections, items, operations, fulfillmentMethods, currentCartV2, redirects },
     auth: OAuthStrategy({ clientId: /* the project's PUBLIC OAuth client id */ }),
   });
-  // then: await client.operations.listOperations(), await client.currentCart.addToCurrentCart({...})
+  // then: await client.operations.listOperations(), await client.currentCartV2.addLineItemsToCurrentCart({...})
   ```
   The `clientId` is public, not a secret. A mis-wired public env var inlines as `undefined` and 400s every call.
 
@@ -55,7 +57,7 @@ A contract for the **frontend code** that lets a visitor **order** from a Wix Re
 
 ## 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`).
+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 request params (note the redirect session's `checkoutId`, which is just the cart's `_id`).
 
 ```jsonc
 // operations.listOperations()  →  { operations: [...] }   (no arguments)
@@ -79,11 +81,12 @@ fulfillmentMethod = {
 // 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
+// currentCartV2.getCurrentCart()  →  { cart: { _id, lineItems: [...] } }   // NOTE: returns { cart } — destructure it
+lineItem = { _id, name: { original }, quantityInfo: { confirmedQuantity }, pricing: { unitPrice: { amount } }, attributes: { image } }
+// price → pricing.unitPrice (ConvertedMoney, NO formatted string in V2 — format it yourself; .amount is site currency, .convertedAmount the buyer's display currency); qty → quantityInfo.confirmedQuantity; image → attributes.image (wix:image:// → resolve)
 
-// currentCart.createCheckoutFromCurrentCart({ channelType })  →  { checkoutId }   // a STRING — NOT { checkout }, NOT _id
-// redirects.createRedirectSession({ ecomCheckout: { checkoutId }, callbacks })  →  { redirectSession: { fullUrl } }
+// the cart's _id is the checkout id → pass to the redirect session:
+// redirects.createRedirectSession({ ecomCheckout: { checkoutId: cart._id }, callbacks })  →  { redirectSession: { fullUrl } }
 ```
 
 ---
@@ -126,8 +129,8 @@ Doc: <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/onli
 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: [{
+await currentCartV2.addLineItemsToCurrentCart({
+  catalogItems: [{                                          // the write shape uses `catalogItems`
     quantity,
     catalogReference: {
       catalogItemId: item._id,                              // the MENU ITEM's _id
@@ -141,9 +144,9 @@ await currentCart.addToCurrentCart({
   }],
 });
 ```
-Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/add-to-current-cart.md?apiView=SDK>
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/add-line-items-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: `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 — Cart V2 rejects the add with an explicit error rather than accepting an invalid line. This is the restaurant analog of the store's mandatory `variantId`.
 
 **⚠️ 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.)
 
@@ -151,21 +154,21 @@ Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purch
 
 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
+### Checkout — redirect to the hosted checkout page
 
-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>
+The cart's `_id` **is** the checkout id — pass it into the redirect session's `ecomCheckout.checkoutId`. Read the current cart, then hand its id to a redirect session (identical to the storefront flow — restaurant orders ride on the same eCommerce checkout).
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.md?apiView=SDK>
 
 ```js
-const checkout = await currentCart.createCheckoutFromCurrentCart({ channelType: currentCart.ChannelType.WEB });
+const { cart } = await currentCartV2.getCurrentCart();   // NOTE: returns { cart } — destructure it
 const session = await redirects.createRedirectSession({
-  ecomCheckout: { checkoutId: checkout.checkoutId },   // checkout.checkoutId — NOT checkout._id
+  ecomCheckout: { checkoutId: cart._id },   // the cart's _id IS the 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.
+**⚠️ The cart's `_id` is the checkout id.** Pass `cart._id` into the redirect session's `ecomCheckout.checkoutId`. And `getCurrentCart()` returns **`{ cart }`** — destructure it, or `cart` is `undefined` and `cart._id` throws *"Cannot read properties of undefined (reading '_id')"*.
 
 **⚠️ 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>.
 
@@ -173,16 +176,16 @@ window.location.href = session.redirectSession.fullUrl; // the hosted-checkout U
 
 ### 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).
+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.pricing.unitPrice`** / **`pricing.totalPrice`** — a `ConvertedMoney` `{ amount, convertedAmount }`; Cart V2 line items carry no preformatted price, so format it yourself. The currency lives on the cart, not the money object — format from `cart.customerInfo?.currencyCode ?? cart.businessInfo?.currencyCode` (see the *Formatting cart prices* section of `how-to-code-a-store.md` for the exact `Intl.NumberFormat` helper), e.g. `new Intl.NumberFormat(undefined, { style: 'currency', currency }).format(Number(pricing.totalPrice.convertedAmount ?? pricing.totalPrice.amount))`. 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`;
+- imports **`operations` / `fulfillmentMethods` from `@wix/restaurants`** (plus `menus`/`sections`/`items` for display) and **`currentCartV2` / `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).
+- checks out by feeding the **current cart's `_id`** (the checkout id) to **`redirects`**, with an **`https://` `window.location.origin`** for the callbacks; the hosted checkout collects fulfillment + payment (which needs a premium plan + payment method).
 </content>

package/skills/wix-headless/references/inline-recipes/setup-online-store.md

@@ -31,6 +31,8 @@ A freshly provisioned Wix Stores app comes pre-seeded with demo/sample products.
 
 Create the products in a **single bulk request** to `POST https://www.wixapis.com/stores/v3/bulk/products-with-inventory/create`. **How many products, and which are in or out of stock, are set by the request you're fulfilling — this step only gives the call and the required format.** Each product needs a real web image URL relevant to it, and `price` via `actualPrice` (+ optional `compareAtPrice`).
 
+**First decide each product's type by what the buyer receives:** shipped → `PHYSICAL` (the JSON below); a file the buyer downloads and keeps → `DIGITAL` (the digital block below — carries a file, no `quantity`). *Access* — a membership or an online course/program the buyer enrolls in — is **Pricing Plans**, not a Stores product.
+
 **⚠️ CRITICAL: PRODUCT & VARIANT VISIBILITY — set `"visible": true` explicitly.**
 Storefront product queries (`searchProducts` / `queryProducts`) return **only visible products** to site visitors. A product created without `"visible": true` is created successfully but will **NOT appear** on the live site — the catalog looks empty. So:
 - Set `"visible": true` on **every product** (product level).
@@ -94,7 +96,18 @@ Storefront product queries (`searchProducts` / `queryProducts`) return **only vi
 **⚠️ CRITICAL FORMAT REQUIREMENTS:**
 - **Description MUST be rich-text nodes**, not a plain string — a plain string causes an `"Expected an object"` error. Use the `{ "nodes": [...], "metadata": {...} }` shape shown.
 - **Media — gated by the `imagery` policy (`SEED.md` § "Entity images"), no exception for stores.** **Always create products text-only here** — omit `media`. When `imagery` is **on**, the **Attach images** step below writes generated brand images in a second pass; it does **not** happen at create time.
+- **Choose the product type from what the buyer receives:** a shipped item is `PHYSICAL` (default); a downloadable file they keep — ebook, PDF, template, preset pack, track, downloadable video — is `DIGITAL`. Selling *access* rather than a file — a membership, subscription, or an online course/program the buyer enrolls in — is **Pricing Plans**, not a Stores product.
 - **Physical products MUST set `"productType": "PHYSICAL"` and an empty `"physicalProperties": {}`** (on the product and on each variant).
+- **Digital products (`"productType": "DIGITAL"`) drop `physicalProperties` and are sellable only when each variant carries both a file and stock** — miss either and the product is created fine, reads back `visible: true`, and is rejected at add-to-cart. Upload the file first (`POST /site-media/v1/files/generate-upload-url` → `PUT` the bytes → `file.id`):
+
+  ```json
+  { "productType": "DIGITAL", "visible": true,
+    "variantsInfo": { "variants": [ {
+      "price": { "actualPrice": { "amount": "12.00" } }, "visible": true,
+      "inventoryItem": { "inStock": true },
+      "digitalProperties": { "digitalFile": { "id": "<file.id>" } }
+    } ] } }
+  ```
 - **Options:** text options use `"optionRenderType": "TEXT_CHOICES"` + `"choiceType": "CHOICE_TEXT"`; color options use `"optionRenderType": "SWATCH_CHOICES"` + `"choiceType": "ONE_COLOR"` + a `colorCode`.
 - **Variants = the full Cartesian product** of all option choices; each variant references **all** options via `optionChoiceNames`, sets `price.actualPrice.amount` (+ optional `compareAtPrice.amount`) as **strings**, and `inventoryItem.quantity`.
 - If part of the bulk request fails, retry the failed products **once** with the exact same format; do not loop.