@wix/agent-skills 1.17.0 → 1.18.0

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

@@ -456,7 +456,7 @@ async function submitContact(formEl) {
     formId: SEEDED_FORM_ID,          // from seeded.forms[].formId
     submissions: values,             // map of target -> value (or -> nested object, for an address)
   });
-  return { _id, status };            // CONFIRMED → render a thank-you (see the status note below)
+  return { _id, status };            // any status → the submission exists; render a thank-you (see the status note below)
 }
 ```
 
@@ -482,13 +482,28 @@ construction, with no hand-maintained list to drift.
 
 Both are fixed in `setup-forms.md` STEP 2.
 
-**⚠️ A resolved promise is not always a recorded submission.** Read `status` from the result: for the
-Wix Forms namespace it is `CONFIRMED` (recorded — show the thank-you), but a form that collects
-payment returns `PAYMENT_WAITING` and some namespaces return `PENDING`, neither of which is recorded
-or visible to the owner yet
+**⚠️ Read `status` from the result — but a resolved call means the submission EXISTS, whatever the
+status.** For the Wix Forms namespace it's `CONFIRMED` (recorded). Some namespaces return `PENDING`,
+which is **not yet recorded** in the Wix Forms collection but **is a created submission**;
+`PAYMENT_WAITING` is a created submission on a form that collects payment
 ([Submission status](https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/introduction#submission-status)).
-Since this renderer skips `PAYMENT` fields, treat anything other than `CONFIRMED` as "not done yet"
-rather than showing a success state.
+
+**All three are a successful submit — show the thank-you.** The visitor has done everything the form
+asked of them; confirming a `PENDING` is a server-side step they play no part in. Showing an error
+instead invites them to submit again, so the cost of getting this wrong is duplicate submissions in
+the owner's inbox for a submission that already exists.
+
+`PAYMENT_WAITING` is the same call: the entry is in the owner's inbox and the *submit* succeeded, so
+**never fail it back to the visitor**. Payment is a separate step — surface it *inside* the success
+state (a "complete your payment" link or instruction) rather than as a failed submission. Since this
+renderer skips `PAYMENT` fields it shouldn't arise at all; if it does, the schema has a payment field
+the UI isn't rendering.
+
+```js
+const { _id, status } = await submissions.createSubmission({ formId, submissions: values });
+// CONFIRMED | PENDING | PAYMENT_WAITING → the submission exists. Thank-you either way.
+if (status === "PAYMENT_WAITING") { /* …and surface the payment step within it */ }
+```
 
 **⚠️ Per-field validation errors — the SDK buries them two levels deeper than the docs' shape.** The
 documented entries (`errorPath`, `errorType`, `errorMessage`, `params` — see
@@ -667,9 +682,10 @@ A correct Wix Forms frontend:
   `target`** so the `submissions` map is keyed by `target` by construction;
 - submits on the **plain visitor token with NO `auth.elevate`** (anonymous submit works; a pure SPA
   can't elevate anyway) and, at the default `ADVANCED` protection, **no captcha**;
-- **only writes submissions** — reading them back is owner-only — and treats
-  **`status === "CONFIRMED"`**, not a resolved promise, as the signal to show the thank-you; reads
-  the created id as **`result._id`**, never `result.id`;
+- **only writes submissions** — reading them back is owner-only — and shows the thank-you for
+  **`CONFIRMED`, `PENDING` *or* `PAYMENT_WAITING`** (all three are created submissions; a payment
+  form surfaces the payment step *within* that success state, never as a failed submit); reads the
+  created id as **`result._id`**, never `result.id`;
 - is **accessible by construction** (the inputs are generated, so a slip repeats on every field):
   each error carries a deterministic id from its `errorPath` and is referenced by `aria-describedby`
   + `role="alert"` and persisted (not conditionally unmounted); a choice group's error and

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

@@ -1,6 +1,6 @@
 ---
 name: "How to Code Members (Astro)"
-description: The frontend contract for member sign-up / log-in / log-out and member-gated surfaces on a Wix-managed **Astro** frontend — the built-in `/api/auth/login` + `/api/auth/logout` routes that `@wix/astro` ships, the `returnUrl` param, gating a page by resolving the member in SSR / a backend route, reading the current member with `@wix/members` `getCurrentMember`, and the two rules that keep this path from breaking: **no `OAuthStrategy`/no client** (that 500s under auto-auth) and **no `auth.elevate`** for a member reading their own data. Specifies the *how* for the Astro axis only — read `how-to-code-members-non-astro.md` for any non-Astro frontend.
+description: The frontend contract for member sign-up / log-in / log-out and member-gated surfaces on a Wix-managed **Astro** frontend — the built-in `/api/auth/login` + `/api/auth/logout` routes that `@wix/astro` ships, the `returnToUrl` param, gating a page by resolving the member in SSR / a backend route, reading the current member with `@wix/members` `getCurrentMember`, and the two rules that keep this path from breaking: **no `OAuthStrategy`/no client** (that 500s under auto-auth) and **no `auth.elevate`** for a member reading their own data. Specifies the *how* for the Astro axis only — read `how-to-code-members-non-astro.md` for any non-Astro frontend.
 ---
 **RECIPE**: How to Code Member Auth on a Wix-managed **Astro** Frontend (built-in `/api/auth/*`, `@wix/members`)
 
@@ -39,16 +39,16 @@ So a paywall that only needs "logged-in vs not" runs on identity alone; anything
 <a href="/api/auth/login">Log in / Sign up</a>
 
 <!-- land the member somewhere specific afterward -->
-<a href="/api/auth/login?returnUrl=/account">Log in</a>
+<a href="/api/auth/login?returnToUrl=/account">Log in</a>
 ```
 
-Logout is a **POST** to `/api/auth/logout` (optionally with `?returnUrl=`):
+Logout is a **POST** to `/api/auth/logout` (optionally with `?returnToUrl=`):
 
 ```astro
 <form method="POST" action="/api/auth/logout"><button>Log out</button></form>
 ```
 
-- **`returnUrl` must be an allowed redirect URI.** When the project is created with that URL it's auto-added; an un-allow-listed `returnUrl` fails the redirect. Default to a relative path already known-good (the login page auto-allows the project's own origin paths).
+- **The param is `returnToUrl` — not `returnUrl`.** The routes validate their query with a strict schema that silently DROPS unknown params, so a misspelled param doesn't error — the member just lands on `/`. The value must be a **relative path** (the callback refuses absolute URLs).
 - After login the member identity **rides on every subsequent SDK call automatically** — no client, no token handling. That's auto-auth (`astro.md`).
 
 ---
@@ -67,14 +67,14 @@ try {
   me = res.member ?? null;
 } catch { /* not a member / not installed — treat as anonymous */ }
 
-if (!me) return Astro.redirect('/api/auth/login?returnUrl=/account');
+if (!me) return Astro.redirect('/api/auth/login?returnToUrl=/account');
 ---
 <h1>Welcome, {me.profile?.nickname ?? me.loginEmail}</h1>
 ```
 
 - **Guard the SSR call in `try/catch`** — an unguarded throw truncates the response mid-stream (white screen; `astro.md` A3). An anonymous visitor is a normal state, not an error: catch → treat as logged-out → redirect to login.
 - **Don't render account/gated UI as a client island that checks auth in the browser.** Resolve identity server-side and gate the route; render only what a member should see. (Same reasoning as the blog-comment API-endpoint path — avoid the browser-auth detour.)
-- For an **action** that only *some* callers may take (post a comment, place a member order), don't gate the whole page: render the control always, and on submit POST to a `src/pages/api/*.ts` endpoint that resolves the session and, if the caller isn't a member, redirects to `/api/auth/login?returnUrl=…`.
+- For an **action** that only *some* callers may take (post a comment, place a member order), don't gate the whole page: render the control always, and on submit POST to a `src/pages/api/*.ts` endpoint that resolves the session and, if the caller isn't a member, redirects to `/api/auth/login?returnToUrl=…`.
 
 ---
 
@@ -116,8 +116,8 @@ So: browsing the plans grid is public, but the **subscribe** button and the **my
 
 ## Conclusion
 Correct member auth on an Astro frontend:
-- uses the **built-in `/api/auth/login`** (login *and* sign-up) and **POST `/api/auth/logout`** routes with an allow-listed `returnUrl` — the login handshake **never** builds an `OAuthStrategy` client, and one must never be built in **SSR frontmatter** (the public-env `clientId` is `undefined` at server render → 500). (The one exception is the custom-login surface — `how-to-code-members-custom-login.md` — which builds an explicit client in a backend route or client island, never in SSR frontmatter.)
-- gates surfaces **server-side** (SSR frontmatter or a `src/pages/api/*.ts` route), guarded in `try/catch`, bouncing anonymous visitors to `/api/auth/login?returnUrl=…`;
+- uses the **built-in `/api/auth/login`** (login *and* sign-up) and **POST `/api/auth/logout`** routes with an allow-listed `returnToUrl` — the login handshake **never** builds an `OAuthStrategy` client, and one must never be built in **SSR frontmatter** (the public-env `clientId` is `undefined` at server render → 500). (The one exception is the custom-login surface — `how-to-code-members-custom-login.md` — which builds an explicit client in a backend route or client island, never in SSR frontmatter.)
+- gates surfaces **server-side** (SSR frontmatter or a `src/pages/api/*.ts` route), guarded in `try/catch`, bouncing anonymous visitors to `/api/auth/login?returnToUrl=…`;
 - reads the current member via **`@wix/members` `getCurrentMember`** (not the dev-preview `@wix/site-members`), resolving the photo `wix:image://` URI and expecting only PUBLIC fields for other members;
 - does **no `auth.elevate`** for a member reading their own data (elevation is a different, admin-only axis that lives in a backend route);
 - treats **login as required** whenever pricing-plans is present (subscribe + my-subscription), and as a soft add-on for the "my …" surfaces of the other verticals;

package/skills/wix-headless/references/inline-recipes/how-to-code-members-custom-login.md

@@ -15,7 +15,7 @@ A concise contract for building your **own** login / sign-up / logout UI and dri
 > **⚠️ This is a client-driven (`OAuthStrategy`) flow — it is the non-Astro shape.** `register`/`login` live on `client.auth`, i.e. the manual visitor client `non-astro.md` builds. Astro's auto-auth ships **no client** to call them on. So: on a **non-Astro** frontend (SPA / static), this is the natural path. On **Astro**, custom login means stepping *outside* auto-auth — instantiate an explicit `OAuthStrategy` client (in a backend route or a client island) to run these calls; do **not** expect the built-in `/api/auth/*` routes to do custom login (they only drive the Wix login page). If the brief is Astro *and* doesn't demand a custom form, prefer the Wix login page (`how-to-code-members-astro.md`).
 
 Pinned docs (read before wiring — `curl` the `.md` directly):
-- Custom login via the JS SDK: <https://dev.wix.com/docs/go-headless/self-managed-headless/authentication/members/custom-login-page/custom-login/custom-login-using-the-js-sdk.md>
+- Custom login via the JS SDK: <https://dev.wix.com/docs/go-headless/authentication/members/custom-login-page/build-a-custom-login-page-js-sdk.md>
 - `OAuthStrategy` reference (`register`/`login`/`processVerification`/`getMemberTokensForDirectLogin`/`sendPasswordResetEmail`, the `StateMachine` + `IdentityProfile` objects): <https://dev.wix.com/docs/sdk/core-modules/sdk/oauth-strategy.md>
 - Current member (SDK): <https://dev.wix.com/docs/sdk/frontend-modules/members/current-member/introduction> (open with `?apiView=SDK`)
 

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

@@ -11,7 +11,7 @@ A concise contract for wiring **login / sign-up / logout and member-gated surfac
 > **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>
+- Wix-managed login via the JS SDK: <https://dev.wix.com/docs/go-headless/authentication/members/wix-login-page/add-a-wix-login-page-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`)

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/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.