@wix/agent-skills 1.35.1 → 1.36.1

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

@@ -1,279 +0,0 @@
----
-name: "How to Code Bookings"
-description: The frontend read/booking contract for a Wix Bookings (Services V2) site — which SDK modules to import, how to list services, fetch appointment vs class availability, render the schema-driven booking form, and run the createBooking → ecom Cart V2 → checkout-or-place sequence. Specifies the *how* (modules + exact calls + the failure modes the docs omit); which services to render and how the page looks come from the request.
----
-**RECIPE**: How to Code a Wix Bookings Frontend (Services V2 + ecom Cart V2 checkout)
-
-A concise contract for writing the **frontend code** of a Bookings site: listing services, picking an availability slot, collecting the booking form, and completing the booking. **This recipe is the *how* (which modules, which calls, which fields), not the *what*** — which services to show, how the page looks, and the framework are decided by the request you're fulfilling.
-
-> **This recipe is for CODING the booking flow, not for seeding it.** It assumes a Services V2 backend already exists (services with a category, staff resources, durations/prices, and — for classes — scheduled sessions). It says nothing about creating services — only how to read and book them from frontend code.
-
-> **⚠️ 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 `service.id`-is-`undefined` bug. If a field name surprises you, you're probably reading the REST view — re-open it with `?apiView=SDK`. Discover any shape not pinned here with `SearchWixSDKDocumentation`, not by guessing a URL.
-
----
-
-## The modules and the client (read this first)
-
-**Constants** (a frontend file, e.g. `src/services/constants.ts`):
-- **Wix Bookings app id** (the cart's `catalogReference.appId`): `13d21c63-b5ec-5912-8397-c3a5ddb27a97`
-- **Staff-member resource type id** (the ANY_RESOURCE fallback + staff filtering): `1cd44cf8-756f-41c3-bd90-3e2ffcaf1155`
-
-**⚠️ CRITICAL: there is NO `availability` namespace.** `import { availability }` / `availability.queryAvailability` does not exist and fails. Appointment availability is `availabilityTimeSlots.listAvailabilityTimeSlots`; class availability is `eventTimeSlots.listEventTimeSlots` — two different namespaces. Import only:
-
-| Need | Package | Module |
-|---|---|---|
-| Services (list, query by slug) | `@wix/bookings` | `services` |
-| Appointment availability | `@wix/bookings` | `availabilityTimeSlots` |
-| Class availability | `@wix/bookings` | `eventTimeSlots` |
-| Categories (optional filter) | `@wix/bookings` | `categoriesV2` |
-| Locations (optional filter) | `@wix/bookings` | `services` (`queryLocations`) |
-| Create the booking | `@wix/bookings` | `bookings` (`createBooking`) |
-| Cart that holds the seat (add / calc / place) | `@wix/auto_sdk_ecom_cart-v-2` | `createCart`, `calculateCart`, `placeOrder` |
-| Redirect to hosted checkout | `@wix/redirects` | `redirects` |
-| Booking-form schema | `@wix/forms` | `forms` (`getFormSummary`) |
-
-**Never** use `confirmBooking` (see *Creating the booking*) — the ecom cart confirms the seat here, not a server-side confirm.
-
-**Auth / client — framework split:**
-- **Astro (Wix-managed):** authentication is ambient. Call the modules directly from server components / backend routes and from browser islands (the `@wix/astro` visitor client) — **no `createClient`, no `OAuthStrategy`, no `clientId`.** Nothing here needs elevation (the reads below all run as the visitor); a public-env `clientId` read in `.astro` SSR is `undefined` at server render → 500, so don't build an `OAuthStrategy` client there.
-- **Non-Astro (Vite/React/Vue/static):** build one manual visitor client and reuse it:
-  ```js
-  import { createClient, OAuthStrategy } from '@wix/sdk';
-  import { services, availabilityTimeSlots, eventTimeSlots, categoriesV2, bookings } from '@wix/bookings';
-  import { createCart, calculateCart, placeOrder } from '@wix/auto_sdk_ecom_cart-v-2';
-  import { redirects } from '@wix/redirects';
-  import { forms } from '@wix/forms';
-
-  const client = createClient({
-    modules: { services, availabilityTimeSlots, eventTimeSlots, categoriesV2, bookings, createCart, calculateCart, placeOrder, redirects, forms },
-    auth: OAuthStrategy({ clientId: /* the project's PUBLIC OAuth client id */ }),
-  });
-  ```
-  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)
-
-V2 service objects are **flat**. The exact paths the frontend reads, and the plausible-wrong sibling each is mistaken for:
-
-```jsonc
-// services.queryServices(...).find()  →  result.items[]   (filter out s.hidden)
-service = {
-  _id,                                              // links · cart catalogItemId base   (NOT .id → undefined)
-  name, description, tagLine,
-  type,                                             // "APPOINTMENT" | "CLASS"
-  hidden,                                           // skip hidden services
-  mainSlug: { name },                               // the URL slug   (NOT service.slug; fallback supportedSlugs[0].name)
-  schedule: { id, availabilityConstraints: { sessionDurations: [60] } },  // duration = sessionDurations[0] (minutes)
-  payment: { fixed: { price: { value, currency } } },                     // value is a STRING; currency is the site's
-  media: { mainMedia: { image } },                  // image is a "wix:image://…" string — resolve via media.getImageUrl()
-  category: { _id },                                // the service's category
-  form: { _id },                                    // the booking form (fetch via @wix/forms)
-  bookingPolicy: { cancellationFeePolicy: { enabled } },  // drives the checkout-vs-place decision
-  staffMemberDetails: { staffMembers: [{ staffMemberId, name }] },  // STAFF_MEMBER_DETAILS conditional field
-}
-
-// availabilityTimeSlots.listAvailabilityTimeSlots(...)  →  result.timeSlots[]   (APPOINTMENT)
-apptSlot = { localStartDate, localEndDate, scheduleId, location, availableResources }  // fields at TOP level (NOT slot.startDate); availableResources may be []
-//   availableResources[] = { resources: [{ _id, name }] }   // NESTED; each resource id is _id NOT id — this is what you read to label/group a slot by its staff/instructor
-
-// eventTimeSlots.listEventTimeSlots(...)  →  result.timeSlots[]   (CLASS)
-classSlot = { localStartDate, localEndDate, eventInfo: { eventId } }  // carries eventId; NO scheduleId
-```
-
-**⚠️ CRITICAL: entity ids are `_id`, NOT `id`.** `service._id`, `booking._id`. `service.id` is `undefined` in SDK code. This includes the **resource objects nested under a slot** — `slot.availableResources[].resources[]._id` (NOT `.id`); reading `.id` there silently yields `undefined`, so grouping/labeling/filtering slots by staff or instructor breaks with no error (an image-led class site rendering blank instructor names/photos is the tell). **`staffMemberDetails.staffMembers[].staffMemberId`** is the exception — despite the name it **IS the resource GUID** (it matches the seed's staff `resourceId`), and it's the value you filter availability and book by.
-
----
-
-## The booking features (build the ones the site needs)
-
-Each section is a **self-contained feature** — implement only the ones the site uses; the only ordering is *within* the flow (pick a slot → collect the form → book). The minimal path is: list services → pick a slot → submit the form → book.
-
-### Listing services (and the `_id` rule)
-
-Always filter by `appId`, request `STAFF_MEMBER_DETAILS`, and call `.find()`:
-
-```js
-// Catalog (list):
-const { items } = await services
-  .queryServices({ conditionalFields: ['STAFF_MEMBER_DETAILS'] })
-  .eq('appId', BOOKING_APP_ID).limit(100).find();   // filter out items where s.hidden
-
-// Single service by slug — the same .eq() builder chain:
-const { items: [service] } = await services
-  .queryServices({ conditionalFields: ['STAFF_MEMBER_DETAILS'] })
-  .eq('mainSlug.name', slug).eq('appId', BOOKING_APP_ID).limit(1).find();
-```
-Doc: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services.md?apiView=SDK>
-
-- **⚠️ `queryServices` is a fluent builder — its only argument is `QueryServicesOptions` (`conditionalFields`, etc.), NOT a `{ query: { filter, paging } }` object.** Apply the `appId` filter and paging as `.eq(...)` / `.limit(...)` chain calls, then `.find()`. The `{query:{filter,paging}}` form is the REST body shape; it does **not** type-check against the SDK (`'query' does not exist in type 'QueryServicesOptions'`) — if the SDK reference page shows an object-param form, trust the installed builder, not that doc example.
-
-- **`appId` filter is required** — omitting it returns services from other apps / nothing useful.
-- **Read V2 flat fields** (cheat-sheet): slug `mainSlug.name` (**not** `service.slug`), `name`/`description`/`tagLine`, duration `schedule.availabilityConstraints.sessionDurations[0]`, price `payment.fixed.price.value` (a **string**). A missing service usually means it wasn't seeded **with a category** (the visibility invariant), not a query bug.
-
-### Filtering — location & category (both auto-skip)
-
-Both filter the **catalog query** and re-render. **Show each filter only when there is more than one choice.**
-
-- **Category:** `categoriesV2.queryCategories().find()` → `result.items[{ _id, name }]`. **Non-fatal** — wrap in try/catch and render without the bar if it fails. Show the bar only when `items.length > 1` (the seed creates at least one category, so a single-category site shows no bar). Filter: `filter['category.id'] = { $eq: categoryId }`; a service's category is `service.category._id`.
-- **Location:** `services.queryLocations()` → `{ businessLocations, customLocations: { exists }, customerLocations: { exists } }`. Show the selector only when the total count > 1. A real business id → `filter['locations.business.id'] = { $hasSome: [id] }`; the synthetic `"custom"`/`"customer"` → `filter['locations.type'] = { $hasSome: ['CUSTOM'|'CUSTOMER'] }`. Carry the chosen location to the slots step so availability is scoped too (next section).
-
-### Availability (the slots step) — appointment vs class
-
-**⚠️ CRITICAL: APPOINTMENT and CLASS use different namespaces, and the slot fields are at the TOP level.**
-
-```js
-// APPOINTMENT — serviceId is a single GUID STRING:
-const { timeSlots } = await availabilityTimeSlots.listAvailabilityTimeSlots({
-  serviceId, fromLocalDate, toLocalDate, timeZone, bookable: true, cursorPaging: { limit: 100 },
-  // staff (optional):    resourceTypes: [{ resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID, resourceIds: [staffMemberId] }],
-  //                      includeResourceTypeIds: [STAFF_MEMBER_RESOURCE_TYPE_ID],
-  // one business location: locations: [{ _id: locationId, locationType: 'BUSINESS' }],
-});                                          // slots: result.timeSlots[] — localStartDate/localEndDate/scheduleId at TOP level
-
-// CLASS — different namespace, PLURAL serviceIds; slots carry eventInfo.eventId, NO scheduleId:
-const { timeSlots } = await eventTimeSlots.listEventTimeSlots({
-  serviceIds: [serviceId], fromLocalDate, toLocalDate, timeZone, includeNonBookable: false,
-  // staff/location (optional): eventFilter: { 'resources.id': { $hasSome: [staffMemberId] }, 'location.id': [locationId] },
-});
-```
-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-event-time-slots.md?apiView=SDK>
-
-- **`fromLocalDate`/`toLocalDate` are LOCAL strings `YYYY-MM-DDThh:mm:ss` (no `Z`)** plus a separate `timeZone`. Passing UTC ISO strings with `Z` returns the wrong window.
-- **Slot fields are top-level** — read `timeSlot.localStartDate` / `.localEndDate` / `.scheduleId`, NOT `timeSlot.slot.startDate`. CLASS slots carry `eventInfo.eventId` and have **no** `scheduleId`.
-- **⚠️ Scope availability to exactly ONE business location on a multi-location service.** Unscoped, `listAvailabilityTimeSlots` returns **one slot per location** per time → every time appears N× (duplicated rows). Build the location list from `queryLocations()` intersected with the service's location ids (a `service.locations` id alone can be one the availability engine doesn't recognize → 0 slots). Staff does **not** multiply rows — one slot carries many `availableResources`.
-- **Staff picker auto-skips ≤1 staff** (`service.staffMemberDetails.staffMembers`). Filter by `staffMemberId` (the resource GUID). When a slot is picked with a specific staff, record `resource = { _id: staffMemberId, name }`; with "any staff", leave it unset (the booking emits the ANY_RESOURCE fallback below).
-- **Group slots by day** — don't render a flat time-only grid (the visitor can't tell which day a slot is on). Week / month / N-day is your choice.
-
-### The booking form — schema-driven (`@wix/forms`)
-
-The booking form is a `@wix/forms` form attached to the service at `service.form._id`. Render it **schema-driven** — never hardcode field names.
-
-**⚠️ CRITICAL: use `getFormSummary`, NOT `getForm`.** `getForm` returns the full nested schema (`form.formFields[].inputOptions.stringOptions.componentType…`), and hand-parsing that deep shape is the #1 source of a **silently empty form** — when your guess at the nested path is wrong, the parse yields zero fields and the form renders no inputs (→ empty `formSubmission` → `createBooking` 400 `first_name must have required property`) or hangs on a "loading" state. Use the **flat** summary instead:
-
-```js
-const { formSummary } = await forms.getFormSummary(service.form._id);
-// formSummary.fields[] = { target, label, type, options?, deleted, _id }   ← FLAT, no nesting
-const fields = (formSummary?.fields ?? [])
-  .filter(f => !f.deleted)
-  .filter(f => f.type && ['STRING', 'EMAIL', 'PHONE', 'NUMBER', 'URL'].includes(f.type));  // simple text-like only (`f.type` is optional on the summary field — guard it or strict build errors)
-```
-Doc: <https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/get-form-summary.md?apiView=SDK> · bookings↔forms: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/wix-forms-integration.md?apiView=SDK>
-
-- **`target` is the submission key** (top-level on each field — no `inputOptions` digging). `type` is a clean enum: render `EMAIL`→`type=email`, `PHONE`→`type=tel`, `NUMBER`→`type=number`, else text; a field with `options[]`→a `<select>`.
-- Each input **writes straight into one values object keyed by `target`** (`{ [target]: value }`). **That object IS the `formSubmission`** — pass it directly to `createBooking`. Do **not** rebuild a second object by looping the schema at submit time.
-
-**⚠️ CRITICAL: render the contact-basics fallback whenever the parsed list is EMPTY — not only on a thrown error.** A successful `getFormSummary` that yields zero usable fields (all filtered out, or an unexpected shape) must still produce a working form. Default to `first_name` / `last_name` / `email` (the booking enforces exactly these) so the form always renders and submits:
-```js
-const formFields = fields.length ? fields : [
-  { target: 'first_name', label: 'First Name', type: 'STRING' },
-  { target: 'last_name',  label: 'Last Name',  type: 'STRING' },
-  { target: 'email',      label: 'Email',      type: 'EMAIL'  },
-];
-```
-**Never gate the form's render on a loading flag that can't resolve** (e.g. showing "Loading form…" while `formFields.length === 0`) — with the fallback above the list is never empty, so render directly.
-
-**⚠️ Skip complex, object-valued field types** — `MULTILINE_ADDRESS`, `OBJECT`, `ARRAY`, `WIX_FILE`, `SIGNATURE`, `PAYMENT`, `DATE`/`TIME` (the filter above already keeps only the simple text-like types). Rendering one as a text input sends a string where the API wants an object and `createBooking` rejects it with **"must be object"**. Only the contact basics are enforced, so dropping optional complex fields is safe.
-
-### Creating the booking — the createBooking → ecom Cart V2 sequence
-
-This is one feature with a fixed sequence. **Use it as-is — the payload shapes are exact and easy to get subtly wrong.** APPOINTMENT and CLASS share the same sequence; they differ only in the slot fields.
-
-```
-createBooking(...)          // booking lands CREATED — the cart holds the seat (no confirmBooking)
-createCart(...)             // one catalogItem per bookingId, appId = BOOKING_APP_ID, channelType WEB
-calculateCart(cartId)       // → { cart, summary }; totals on summary.priceSummary.total.amount
-isCheckoutRequired ?  redirect to hosted checkout (paid)  :  placeOrder(cartId) (free / pay-in-person)
-```
-
-**1 · createBooking.** Doc: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md?apiView=SDK>
-
-```js
-const created = await bookings.createBooking({
-  selectedPaymentOption,                 // derive from service.payment.options — see below
-  totalParticipants: 1,
-  bookedEntity: {
-    slot: {
-      serviceId,
-      scheduleId: slot.scheduleId ?? undefined, // APPOINTMENT only — the SELECTED SLOT's own scheduleId, NOT service.schedule.id (the availability slot types it `string | null`; `?? undefined` to satisfy the `string | undefined` param under strict)
-      eventId: slot.eventInfo?.eventId,   // CLASS only (Wix derives startDate/endDate/resource/location from it)
-      startDate: slot.localStartDate,     // local "YYYY-MM-DDThh:mm:ss"
-      endDate:   slot.localEndDate,
-      timezone,
-      // specific staff: resource: { _id: staffMemberId, name }
-      // any staff:      resourceSelections: [{ resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID, selectionMethod: 'ANY_RESOURCE' }]
-      location: { locationType: 'OWNER_BUSINESS' },   // map BUSINESS→OWNER_BUSINESS, CUSTOMER→CUSTOM
-    },
-  },
-}, { formSubmission });                   // the form values keyed by `target`
-const bookingId = created.booking._id;
-```
-
-- **⚠️ `scheduleId` MUST come from the SELECTED SLOT (`slot.scheduleId`), not from the service.** The APPOINTMENT slot carries its own top-level `scheduleId` (cheat-sheet) — carry it from the slots step into the booking. The service object *also* has a `schedule.id` (you read it for duration), but it is a **different value**: sending `service.schedule.id` (or an empty `scheduleId` prop) makes `createBooking` 400 with `VALIDATION_FAILURE: "…startDate, endDate, location.locationType, resource.id, and scheduleId must be set"`. (CLASS sends `slot.eventInfo.eventId` instead — no `scheduleId`.)
-- **⚠️ Pass `formSubmission`, NOT `contactDetails`.** `contactDetails` is what Wix derives back onto the response; sending it instead of `formSubmission` drops the visitor's input.
-- **⚠️ `formSubmission` is the object your inputs wrote to (values keyed by `target`) — send it DIRECTLY; do NOT rebuild it by iterating the parsed form-field schema.** If you re-derive the submission by looping over the schema array and your render falls back to a hardcoded field list when the schema parse comes back empty, the rebuild loop reads the empty schema and sends an **empty body** → `createBooking` 400s with `INVALID_ARGUMENT: "first_name must have required property 'first_name'…"` even though the form looked filled. Keep the typed-values object (`{ [target]: value }`) as the single source and pass that.
-- **⚠️ ANY_RESOURCE fallback (staff).** With no specific staff chosen, send `resourceSelections: [{ resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID, selectionMethod: 'ANY_RESOURCE' }]` and Wix auto-assigns a bookable resource — appointment slots can return `availableResources: []` yet book fine this way. A specific choice sends `resource: { _id, name }` instead.
-- **⚠️ Derive `selectedPaymentOption` from the service — do NOT hardcode `"ONLINE"`.** `online && !inPerson → "ONLINE"`; `!online && inPerson → "OFFLINE"`; else `"ONLINE"`. A **free / pay-in-person** service booked `ONLINE` makes the cart reject it with **`INSUFFICIENT_INVENTORY`** (`available_quantity: 0`).
-- **`locationType` on the booking slot is `OWNER_BUSINESS`** (the booking endpoint's enum), NOT `BUSINESS` (which is the *services* endpoint's enum). Map the slot's `BUSINESS`→`OWNER_BUSINESS`, `CUSTOMER`→`CUSTOM`.
-- **Wrap in try/catch** — `createBooking` can reject (slot taken between fetch and submit, strict phone validation). Surface a friendly message; don't crash.
-
-**2 · Cart holds the seat → checkout or place.**
-
-```js
-const cart = await createCart({
-  catalogItems: [{ quantity: 1, catalogReference: { catalogItemId: bookingId, appId: BOOKING_APP_ID } }],
-  cart: { source: { channelType: 'WEB' } },
-});
-if (!cart._id) throw new Error('cart creation failed');   // Cart V2 types `_id` as `string | undefined`; narrow once so the strict build accepts it downstream
-const cartId = cart._id;
-const { cart: calc, summary } = await calculateCart(cartId);   // totals are NOT stored on the Cart V2 entity
-
-// checkout required? cancellation-fee policy → yes; total 0 → no; FULL_PAYMENT_OFFLINE → no; else yes
-if (checkoutRequired) {
-  const { redirectSession } = await redirects.createRedirectSession({
-    ecomCheckout: { checkoutId: cartId },          // the cartId IS the checkoutId here
-    callbacks: { postFlowUrl: `${origin}/booking-confirmation` },
-  });
-  window.location.href = redirectSession.fullUrl;  // Wix-hosted checkout
-} else {
-  const order = await placeOrder(cartId);          // free / pay-in-person → confirmation
-}
-```
-
-- **⚠️ No `confirmBooking`.** The classic server-side confirm step is not used — the **ecom Cart V2** holds the seat: `placeOrder` (free/offline) or the hosted checkout (paid) drives confirmation, so a client-only site completes the whole flow with no server elevation.
-- **⚠️ CRITICAL: `origin` in `postFlowUrl` MUST be the `https://` published host — from `window.location.origin`, NEVER `new URL(request.url).origin`.** The Headless redirect allowlist registers the `https://` host and treats `http://<same host>` as a different, unlisted origin; a `http://` `postFlowUrl` makes the return ("Continue Browsing") **403** with *"… isn't listed as an allowed redirect domain."* Server-derived `new URL(request.url).origin` is `http://` behind Wix's proxy → pass `window.location.origin` from the client, or force `https`. Doc: <https://dev.wix.com/docs/go-headless/getting-started/setup/manage-urls/add-allowed-redirect-domains>.
-- **⚠️ CRITICAL: the confirmation page must reflect REAL status — do NOT hardcode `?status=success` in `postFlowUrl`, and do NOT default the page to success.** The buyer lands on `postFlowUrl` whether they completed payment **or** clicked "Continue Browsing" to abandon the hosted checkout. A confirmation page that reads `status ?? 'success'` (or trusts a `?status=success` you baked into the URL) renders "confirmed" for an **unpaid, abandoned** booking. Drive the confirmation from the actual order/booking — look up the booking (it's `CREATED` after `createBooking`; payment is a separate state) or the order — and don't present an unconfirmed booking as confirmed. For the free/offline branch, `placeOrder` having returned an `orderId` is a real success signal; for the paid branch, returning from the redirect is **not**.
-- **⚠️ Read the booking back as the anonymous visitor — `getBooking` is a manage-scope read that `403`s the visitor (same axis as the events `ticketDefinitions` trap; do NOT `auth.elevate`).** The visitor-public path is a two-step token handoff, both exports on `@wix/bookings` — use these exact calls, don't hunt the installed `.d.ts` for them:
-  1. **At booking time** (right after `createBooking` returns `booking._id`) mint a one-shot read token: `const { token } = await bookings.getAnonymousActionToken(bookingId)` — **`bookingId` is a POSITIONAL string arg, not `{ bookingId }`** (the object form fails `tsc`). Append the token to your `postFlowUrl` (e.g. `?bookingId=…&token=…`).
-  2. **On the confirmation page** read it back: `const { booking } = await bookings.bookingsGetBookingAnonymously(token)` — the response is **wrapped** (`{ booking }`). Drive the UI off **`booking.status`** (`CREATED` = seat held / payment pending; `CONFIRMED`/`PENDING` = done) and the time off **`booking.bookedEntity.slot.startDate`**.
-- The cart's `catalogReference.catalogItemId` is the **`booking._id`** and `appId` is the **Bookings app id** (a booking id is automatically valid as an ecom catalog item).
-
-### Rendering & mounting
-
-- **Price**: `service.payment.fixed.price.value` (string) + `.currency` (the site's stored currency — format from it, don't assume USD).
-- **Image**: `service.media.mainMedia.image` is a **string**, not an object (the installed type is `image?: string`, so `.image.url` fails `tsc`) — but its value is a Wix media URI like `wix:image://v1/…`, **not** an absolute URL (`.startsWith("https://")` is `false`). Putting it straight into `<img src>` ships broken images. Resolve it first: `import { media } from "@wix/sdk"`, then `media.getImageUrl(service.media.mainMedia.image).url` → `https://static.wixstatic.com/media/…`. Guard for services with no image.
-- **Mount slots + form + book in a `client:only="react"` island** (Astro) — availability is timezone/session-specific. SSR only the read pages (catalog/detail) for SEO.
-
-### SEO on item pages (Astro, Wix-managed)
-
-A **service detail** page is a Wix **item page**: its `<title>`/description/OG/canonical come from what the owner sets in the dashboard. On the Astro (Wix-managed) frontend, wire it per the canonical guide — **[Add SEO Support to Item Pages](https://dev.wix.com/docs/go-headless/wix-managed-headless/seo/add-seo-support-to-item-pages.md)** — which covers the three steps: export `wixMetadata` (registers the route → sitemap + dashboard SEO editor), call `loadSEOTagsServiceConfig(...)`, and render `<SEO.Tags>` (from `@wix/seo`; deps + `@wix/essentials ≥ 1.0.10` are in the guide's "Before you begin").
-
-For a service page use:
-- **`wixMetadata`** from `WIX_APPS.bookings.servicePageMetadata` — referenced **directly** in the export (module scope). Route param `slug` → `identifiers.slug`.
-- **`itemType`**: `seoTags.ItemType.BOOKINGS_SERVICE`.
-
-Run `loadSEOTagsServiceConfig` in the same `Promise.all` as the service read, with `.catch(() => null)`, so a SEO hiccup falls back to the layout's default title instead of failing the page. Optional: render a `Service` schema.org JSON-LD `<script>` from the fetched service (see the guide's structured-data step).
-
-### Out of scope
-Waitlist, on-site manage/cancel, payment/deposit breakdown, multi-service packages, and COURSE bookings. Waitlist and manage/cancel have **no headless source of truth** — don't invent them on the anonymous-token layer; post-booking self-service is the Wix-hosted flow / member area.
-
----
-
-## Conclusion
-A correct Services V2 booking frontend:
-- imports **`services` / `availabilityTimeSlots` / `eventTimeSlots` / `bookings`** from `@wix/bookings`, plus **Cart V2** (`@wix/auto_sdk_ecom_cart-v-2`), `@wix/redirects`, and `@wix/forms` — and never the nonexistent `availability` namespace or `confirmBooking`;
-- uses **`service._id`** (never `service.id`) and reads the **flat V2 fields** (`mainSlug.name`, `payment.fixed.price.value`, `schedule.availabilityConstraints.sessionDurations[0]`);
-- fetches availability per type (**`availabilityTimeSlots`** for APPOINTMENT, **`eventTimeSlots`** for CLASS) with **local date strings**, reads slot fields at the **top level**, and scopes to one location to avoid duplicate rows;
-- renders the booking form **schema-driven via `getFormSummary`** (the flat `formSummary.fields[].target`, never `getForm`/`formFields`), **falls back to `first_name`/`last_name`/`email` whenever the parsed list is empty** (so the form never renders blank or hangs), keys values by `target`, skips complex field types, and passes that object as **`formSubmission`** (not `contactDetails`);
-- runs **createBooking → createCart → calculateCart → checkout-or-place**, deriving `selectedPaymentOption` from the service (free/offline → `OFFLINE`, else `ONLINE` — the wrong choice rejects the cart with `INSUFFICIENT_INVENTORY`) and using the **ANY_RESOURCE** fallback when no staff is chosen.

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

@@ -1,163 +0,0 @@
----
-name: "How to Code CMS"
-description: The frontend read/write contract for Wix CMS (Wix Data) — the `@wix/data` `items.query` builder, the `_id`-and-fields-on-the-item shape (not `item.data.field`), why public-read collections need no `auth.elevate`, how to resolve images and render Ricos rich text, and the visitor-write path for collaborative collections (`items.insert`/`update`/`remove`, the update-replaces-whole-item footgun, shared/unscoped data). Specifies the *how* (module + exact calls + the failure modes the docs omit); which collections to render/write come from the request.
----
-**RECIPE**: How to Code a Wix CMS Frontend (`@wix/data`, Wix Data v2)
-
-A concise contract for writing the **frontend code** that reads Wix CMS collections: listing items, filtering, following references, and rendering images and rich text. **This recipe is the *how* (which module, which calls, which fields), not the *what*** — which collections to show, how the page looks, and the framework are decided by the request you're fulfilling.
-
-> **This recipe is for CODING the frontend, not for seeding it.** It assumes the collections and items already exist and are **public-read** (created by `setup-cms.md`). It says nothing about creating collections or inserting data — only how to read them from frontend code.
-
-> **⚠️ 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** describes the REST shape — items nested under `item.data.<field>` and queried via a `POST /items/query` body. The **`?apiView=SDK` view** describes the SDK shape — items with **fields on the item itself** and a chainable `items.query(...)` builder. The SDK is what your frontend calls; reading the REST view by mistake is the source of the `item.data.title`-returns-`undefined` bug below. Fetch the `.md?apiView=SDK` form directly.
-
----
-
-## The module and the client (read this first)
-
-**⚠️ CRITICAL: the Wix Data items API is the `items` named export of `@wix/data`** — `import { items } from "@wix/data"`, then `items.query` / `items.get` / `items.insert` / `items.update` / `items.remove` (plus `items.bulkInsert` / `items.queryReferenced`). Do **not** import from the internal `@wix/wix-data-items-sdk` — `@wix/data` is the single documented package.
-
-| Need | Package | Module / export |
-|---|---|---|
-| Read collection items (query, get, filter, references) | `@wix/data` | `items` |
-| Resolve `wix:image://` URIs to URLs | `@wix/sdk` | `media` |
-
-**Collection id has NO namespace.** A native collection's id is just the name the seed created (`"team-members"`, `"faq"`, `"Projects"`) — pass it straight to `items.query("team-members")`. The `<namespace>/<name>` form is only for Wix App collections. Stay consistent with the `collectionId` the seed recipe kept.
-
-**Auth / client — framework split:**
-- **Astro (Wix-managed):** authentication is ambient. Call `items.query(...)` directly from server components and backend routes (`src/pages/api/*.ts`) — **no `createClient`, no `OAuthStrategy`, no `clientId`.**
-- **Non-Astro (Vite/React/Vue/static):** build one manual visitor client and reuse it:
-  ```js
-  import { createClient, OAuthStrategy } from '@wix/sdk';
-  import { items } from '@wix/data';
-
-  const client = createClient({
-    modules: { items },
-    auth: OAuthStrategy({ clientId: /* the project's PUBLIC OAuth client id */ }),
-  });
-  // then: client.items.query('team-members').find()
-  ```
-  The `clientId` is public, not a secret.
-
-**⚠️ CRITICAL: do NOT call `auth.elevate` — public collections are public-read, and member-scoped ones use the member token.** `setup-cms.md` creates a public collection with `read: "ANYONE"`, so the visitor token reads it directly. A pure SPA/static frontend has **no server and cannot elevate** at all; even on Astro the read is visitor-scoped and needs no elevation. (Elevation is only for collections that genuinely can't be public — not the case here.) **If a query on a PUBLIC collection comes back empty, it wasn't seeded public-read — that's a permissions bug in the seed, not a query bug** (re-check the collection's `read` permission); don't reach for `elevate` to paper over it.
-
-**Member-scoped collections (only when the run includes members login).** A collection seeded member-scoped (`setup-cms.md` → `SITE_MEMBER_AUTHOR` for per-user-private, or `SITE_MEMBER` for member-only) is read/written with the **logged-in member's token** — the same client, just after the member has logged in (see `how-to-code-members-astro.md` / `how-to-code-members-non-astro.md`). Key rules:
-- **Still NO `auth.elevate`.** The member token carries the identity; the platform scopes the rows server-side. Reaching for elevate here is the wrong axis (it's for admin/site-wide reads, not a member's own data).
-- **`SITE_MEMBER_AUTHOR` returns only the caller's OWN rows automatically** (matched on the item's `_owner`) — you don't filter by owner in the query, and you **must not** set `_owner` on insert (the platform stamps it from the member identity). `items.query('my-notes').find()` as member A returns A's notes; as member B, B's.
-- **An anonymous / not-yet-logged-in read returns ZERO items — that's the gate, not a bug.** Don't render a member-scoped surface to anonymous visitors: gate the route/page behind login first (bounce to the login flow), *then* query. An empty result after a confirmed login on a `SITE_MEMBER_AUTHOR` collection just means that member has no rows yet (show an empty state), not a permissions error.
-
----
-
-## The shape you read (field cheat-sheet)
-
-```jsonc
-// items.query("CollectionId").find()  →  result.items[]
-item = {
-  _id,                                  // the item id (SDK normalizes to _id, NOT id)
-  _createdDate, _updatedDate, _owner,   // system fields
-  name, role, bio, order,               // YOUR fields — directly on the item (NOT item.data.name)
-}
-// result also has: result.length, result.hasNext(), result.pageSize
-```
-
-`result.items[]` is the array; paging via `result.hasNext()` / a follow-up `.find()`. A `wix:image://` value in an IMAGE field and a Ricos object in a RICH_TEXT/RICH_CONTENT field both need resolving before render (see below).
-
----
-
-## The features (build the ones the site needs)
-
-Each section is a **self-contained feature** — implement only what the site uses, in any order.
-
-### Listing / reading (and the field-access rule)
-
-Query a collection with the chainable builder; `.find()` resolves to `{ items, ... }`.
-Doc: <https://dev.wix.com/docs/sdk/business-solutions/data/items/query.md?apiView=SDK>
-
-```js
-const { items: rows } = await items.query('team-members')
-  .ascending('order')
-  .limit(50)
-  .find();
-// rows[0] === { _id, name, role, bio, order, _createdDate, ... }
-```
-
-**⚠️ CRITICAL: fields are on the item itself — `item.name`, NOT `item.data.name`.** The SDK returns each field as a top-level property of the item (the API was revised to match the Velo `wix-data` shape). `item.data.name` is the **REST** response shape and reads `undefined` in SDK code — the silent "every field is blank" bug. If you're reaching through `.data`, you're reading the REST doc view; re-open it with `?apiView=SDK`.
-
-**⚠️ CRITICAL: the id is `_id`, never `id`.** `item.id` is `undefined`; use `item._id` for keys, links, and reference lookups.
-
-**⚠️ `items.queryDataItems(...)` does NOT exist in the SDK.** The chainable entry point is `items.query("collectionId")` — `queryDataItems` is a REST/method name. Don't mix the two.
-
-### Filtering and single-item lookup
-
-Chain filter/sort/page methods on the query builder, then `.find()`:
-
-```js
-// by slug (detail page)
-const { items: [post] } = await items.query('articles').eq('slug', slug).limit(1).find();
-// compound filter + sort
-const { items: rows } = await items.query('products')
-  .eq('inStock', true).gt('price', 25).ascending('title').limit(50).find();
-```
-
-Builder methods: `.eq` / `.ne` / `.gt` / `.ge` / `.lt` / `.le` / `.contains` / `.startsWith` / `.hasSome` / `.ascending` / `.descending` / `.limit` / `.skip`. (No `$`-operator JSON body — that's the REST `/items/query` shape; in the SDK the operators are builder methods.)
-
-### Following references
-
-A `REFERENCE` / `MULTI_REFERENCE` field stores only ids by default. To inline the referenced items, add `.include("<fieldKey>")`:
-
-```js
-const { items: rows } = await items.query('projects').include('teamMembers').find();
-// rows[0].teamMembers is now an array of full team-member items, not ids
-```
-Doc: <https://dev.wix.com/docs/sdk/business-solutions/data/items/query-referenced.md?apiView=SDK> (for `items.queryReferenced`, the alternative when a multi-reference set is large). Without `.include(...)`, the field is just ids — resolve them yourself or use `include`.
-
-### Rendering images (IMAGE fields)
-
-An `IMAGE` field comes back as a **`wix:image://v1/<hash>/<file>#…` identifier, not a ready URL** — putting it straight into `<img src>` shows nothing (`ERR_UNKNOWN_URL_SCHEME`). Resolve it with the SDK media module, and reuse one helper on every render path:
-
-```js
-import { media } from '@wix/sdk';
-function imgSrc(v, w = 800, h = 600) {
-  if (!v) return '';
-  if (typeof v === 'string' && v.startsWith('wix:image://')) return media.getScaledToFillImageUrl(v, w, h, {});
-  return typeof v === 'string' ? v : (v?.url ?? '');   // an already-absolute https URL passes through
-}
-```
-
-**Never hand-build a `static.wixstatic.com/.../v1/fit/...` URL** — the format is easy to get wrong and the image then **403s**. Only `wix:image://` values need resolving; an already-absolute `https://` URL (e.g. an Unsplash placeholder seeded when imagery was off) goes straight into `<img src>`. Doc: <https://dev.wix.com/docs/sdk/core-modules/sdk/media>
-
-**⚠️ When imagery is OFF (the seed default), IMAGE fields are EMPTY — fall back, don't render a broken `<img>`.** The seed is text-only unless imagery is on, so a `photo`/`coverImage`/`headshot` field is often **absent or empty** on every item. Guard the render: only emit `<img>` when the field resolves to a real URL, otherwise show a graceful fallback (an initials avatar, a colored placeholder, or simply omit the image) — never an empty/broken `<img src="">`. A missing image is expected content state here, not an error.
-
-### Rendering rich text (RICH_TEXT / RICH_CONTENT fields)
-
-Wix CMS stores `RICH_TEXT` / `RICH_CONTENT` as **Ricos JSON** — a structured node tree (PARAGRAPH, HEADING, BULLETED_LIST…), not HTML and not a string.
-
-**⚠️ Do NOT `set:html={item.bio}` or `String(item.bio)` directly.** That dumps `[object Object]` or `{"nodes":...}` into the page. Render the Ricos node tree — either with a small SSR Ricos→HTML walker (covers PARAGRAPH, HEADING, lists, BLOCKQUOTE, BOLD/ITALIC/LINK; renders anything else defensively as a `<p>`), or with `@wix/ricos`'s React `RicosViewer` as a client island when the content carries the full feature set (galleries, embeds). For short bound fields a plain-text variant is fine; for a body field, render it **formatted**.
-
-### Writing from the frontend (only to a visitor-writable collection)
-
-Most collections are **read-only** from the visitor client — admin-owned content (catalog, team, articles) the site only displays. **Fire-and-forget visitor input** (contact, signup, lead capture) goes through **Wix Forms**, not CMS — don't `items.insert` for those.
-
-But when the site is built around **shared, visitor-editable data** — a guestbook, a community board, a collaborative list anyone can add to and edit — that collection is seeded **visitor-writable** (`insert`/`update`/`remove: ANYONE`, see `setup-cms.md`), and the client does full CRUD with the same `items` module:
-
-```js
-const created = await items.insert('community-board', { title, note, status: 'open' }); // → item with _id
-await items.update('community-board', { ...item, status: 'claimed' });                  // see footgun below
-await items.remove('community-board', item._id);
-```
-
-**⚠️ CRITICAL: `items.update()` REPLACES the whole item — it does NOT patch.** Per the docs: *"If the existing item had fields with values and those fields aren't included in the updated item, the values in those properties are lost."* So `update('c', { _id, status })` **wipes `title`, `note`, and every other field** — the classic "toggling status erases the row" bug. **Always pass the FULL item** on update (spread the record you already hold in state: `{ ...item, status }`). If you only have the id + one changed field and not the whole record, use **`items.bulkPatch('c', [id]).setField('status', v).run()`** instead — `bulkPatch` modifies only the named fields. Doc: <https://dev.wix.com/docs/sdk/business-solutions/data/items/update.md?apiView=SDK>
-
-**⚠️ A write needs the collection seeded with the matching open permission — else it 403s.** `items.insert`/`update`/`remove` only succeed if the collection was created with that verb at `ANYONE` (`setup-cms.md`). A write to an `ADMIN`-write collection 403s from the visitor client (there's no `auth.elevate` on this path to get around it). If writes 403, fix the seed permission, not the call.
-
-**⚠️ On the ANONYMOUS path the data is SHARED and unscoped — no per-user identity.** The visitor token has no per-user identity, so an `ANYONE`-writable collection is **global/shared across all visitors** (not per-user, not cross-device) and **any visitor can edit or delete any row**. That's the intended model for a collaborative board; surface it as such. **For per-user-private data, that's the member-scoped path** (`SITE_MEMBER_AUTHOR`, see the member-scoped note above): the same `items.insert`/`update`/`remove` calls, but run under a **logged-in member's token**, and each member touches only their own `_owner`-matched rows. On Astro you may route writes through a backend `src/pages/api/*` endpoint, but the permission facts are identical — no `_owner` set by hand, no elevate.
-
----
-
-## Conclusion
-A correct Wix CMS frontend:
-- imports the **`items`** export of **`@wix/data`** (never `@wix/wix-data-items-sdk`), and `media` from `@wix/sdk` for images;
-- queries with **`items.query("collectionId")` + builder methods + `.find()`** (no namespace on the id; `queryDataItems` doesn't exist);
-- reads fields **on the item** (`item.name`) and the id as **`item._id`** — never `item.data.name`, never `item.id`;
-- does **no `auth.elevate`** — a public collection is read on the visitor token (an empty result there is a seed permissions bug, not a query bug), and a **member-scoped** collection (opt-in, `SITE_MEMBER_AUTHOR`/`SITE_MEMBER`) is read on the **logged-in member's token** with the same no-elevate rule (an anonymous read returning empty is the gate, not a bug);
-- resolves `wix:image://` via `media.getScaledToFillImageUrl` and renders Ricos rich text formatted (never raw `set:html`/`String`);
-- treats CMS as **read-only by default** (fire-and-forget input → Forms); writes to a **visitor-writable** collection use `items.insert`/`update`/`remove` — always passing the **full item** on `update` (it replaces, not patches), expecting the data to be **shared/unscoped**, and relying on the collection's seeded `ANYONE` write permission (no `auth.elevate`). For **per-user-private** data (opt-in, members login in the run) the same calls run under the **member token** against a `SITE_MEMBER_AUTHOR` collection — each member sees/edits only their own `_owner`-matched rows, `_owner` is never set by hand, and the surface is gated behind login.

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

@@ -1,146 +0,0 @@
----
-name: "How to Code Donations"
-description: Read Wix Donations campaigns and accept one-time or recurring donations through Cart V2 and a Headless redirect session. Covers numeric cart amounts, omitted one-time frequency, donor selections, misleading catalog errors and staged verification; does not create campaigns or prescribe hosting.
----
-# Accept a donation on a Headless site
-
-Use existing Wix Donations campaigns; setup/editing belongs to
-[the management recipe](../../../wix-manage/references/donations/create-and-update-donation-campaigns.md).
-Read the [donor-experience guidance](experience-donations.md) when building
-the UI. Resolve sibling links locally when installed; otherwise read the same repository path under
-`https://www.wix.com/skills/`. This contract is independent of framework and hosting.
-
-## 1. Read the campaign as the donor will
-
-Use one visitor identity per browser session; reuse the existing auth/transport. A public OAuth client
-ID is not a secret; API keys, app secrets and owner tokens never belong in the browser. Confirm the
-client targets the supplied content site. Do not require donor login or provision a replacement site.
-
-| Need | REST call and minimal body | SDK equivalent |
-| --- | --- | --- |
-| Discover campaigns | `POST https://www.wixapis.com/donation-campaigns/v2/donation-campaigns/query` · `{ "query": { "filter": { "archived": false }, "cursorPaging": { "limit": 100 } } }` | `donationCampaigns.queryDonationCampaigns().eq('archived', false).limit(100).find()` |
-| Campaign detail | `GET https://www.wixapis.com/donation-campaigns/v2/donation-campaigns/<ID>` | `donationCampaigns.getDonationCampaign(id)` |
-| Goal metrics, only with a goal and permitted access | `GET https://www.wixapis.com/donation-campaigns/v2/donation-campaigns/<ID>/metrics` | `donationCampaigns.getDonationCampaignMetrics(id)` |
-
-REST returns `donationCampaigns` / `donationCampaign`; SDK queries return `items`, SDK entities use
-`_id`. Continue query paging with the returned cursor. Resolve detail routes from live IDs, not a
-seed-time list; missing/archived campaigns are unavailable, not a fallback to the first campaign.
-Offer giving only when `status === 'COLLECTING'` and not archived. Reaching a goal does not close a
-campaign if it allows further donations. A refused query is an error, not an empty campaign list.
-
-Render from `donationFrequencies`, `predefinedDonationAmounts[].price` and `.description`,
-`customAmountEnabled` / `customAmountOptions`, `commentsEnabled`, `askDonorCoverFee`, and optional
-`campaignGoal`. Currency is the site's default; use formatted API values or a verified currency code,
-never assume USD. A metrics failure must not invent a raised total, donor count or currency.
-Campaign story copy is site-authored; the entity has no story or slug.
-
-Carry an explicitly chosen giving frequency through discovery and campaign links to the form, but
-only when that campaign offers it. Retain later donor edits. Keep a short-lived, site/visitor/campaign-
-scoped draft (preset/custom amount, cadence, fee, note) across refresh and checkout abandonment; notes
-never belong in query strings or logs. Restore and revalidate against live settings before allowing
-checkout. Do not clear the draft merely because a return URL was visited; see the shared experience
-reference for recovery and accessible form requirements. This is UI state, not an extra Wix API.
-
-Docs: [query](https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns/query-donation-campaigns),
-[get](https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns/get-donation-campaign),
-[metrics and permissions](https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns/get-donation-campaign-metrics).
-For SDK shapes read their `.md?apiView=SDK` views. Modules: `donationCampaigns` from `@wix/donations`,
-`cartV2` from `@wix/ecom`, `redirects` from `@wix/redirects`, on the project's existing SDK client or
-ambient auth. REST-only projects do not install an SDK just for this flow.
-
-## 2. Build the catalog reference correctly
-
-**Campaign prices are decimal strings; cart `options.amount` must be a JSON number.** Convert and
-validate before the request. `ONE_TIME` belongs to the campaign/UI enum; **omit `frequency` from
-the cart options for one-time giving**. Only `WEEK`, `MONTH`, `YEAR` are recurring cart values.
-
-```js
-const amount = Number(selectedAmount);
-if (!Number.isFinite(amount) || amount <= 0) throw new Error('Enter a positive donation amount.');
-// Before this: validate against the selected campaign's presets/custom limits and offered frequency.
-const catalogItems = [{
-  quantity: 1,
-  catalogReference: {
-    appId: '333b456e-dd48-4d6b-b32b-9fd48d74e163',
-    catalogItemId: campaignId,
-    options: {
-      amount,
-      ...(frequency !== 'ONE_TIME' ? { frequency } : {}),
-      ...(askDonorCoverFee && donorOptedIn ? { donorCoveringFees: true } : {}),
-    },
-  },
-}];
-```
-
-Validate a nonempty amount first: `Number('')` is zero, not a donor selection. Honor the campaign's
-allowed choices. Put an enabled donor message in `cart.note` (Cart V2 limit 1,000 characters), not
-invented catalog options. Fee coverage adds the documented 2.9% **through the flag**; send the base
-donation amount, not a locally inflated amount plus the flag. Recurring coverage applies per charge.
-Do not create custom-priced items to bypass campaign rules.
-[Donation catalog-reference contract](https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns/e-commerce-integration-with-donation-campaigns).
-
-## 3. Create a fresh Cart V2, then a redirect session
-
-Use the same visitor identity throughout. Keep this separate from the shopper's current merchandise
-cart. New Cart V2 flows have **no separate Create Checkout call**; the returned cart ID is the ID
-handed to `ecomCheckout.checkoutId`. Do not mix in the V1 create-checkout-from-cart step.
-[Cart V2 migration](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide).
-
-| Step | REST request | Result |
-| --- | --- | --- |
-| Create cart | `POST https://www.wixapis.com/ecom/v2/carts` · `{ "cart": { "source": { "channelType": "WEB" } }, "catalogItems": [...] }` (the numeric reference above; optional `cart.note`) | `cart.id` |
-| Inspect calculated totals during verification | `POST https://www.wixapis.com/ecom/v2/carts/<CART_ID>/calculate` · `{}` | `cart` and `summary`; inspect the donation line, currency, calculated amounts and issues |
-| Create redirect session | `POST https://www.wixapis.com/_api/redirects-api/v1/redirect-session` · `{ "ecomCheckout": { "checkoutId": "<CART_ID>" }, "callbacks": { "postFlowUrl": "<ORIGIN>/donate/<ID>", "thankYouPageUrl": "<ORIGIN>/donate/thank-you" } }` | `redirectSession.fullUrl` |
-
-SDK: `cartV2.createCart({ cart: { source: { channelType: 'WEB' }, ...(note ? { note } : {}) }, catalogItems })`
-returns a cart with `_id`; pass it to `redirects.createRedirectSession` with the same body as above.
-Navigate the **full document** to the exact returned URL (`window.location.assign(fullUrl)`), not an
-SPA router, iframe, guessed checkout URL or manually created order.
-
-Use actual, reachable callback routes on the deployed origin; the external origin must be allowed
-on the OAuth client. `postFlowUrl` is also used on abandonment: it is not a paid signal. A success
-callback may carry `orderId`; confirm order/payment state through an authorized read before stating
-that a donation was paid. Never grant owner access just to populate a public thank-you page.
-
-Docs: [create cart](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart),
-[calculate](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/calculate-cart),
-[redirect session](https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session).
-On a Kit build, call its shipped `donationCheckoutUrl` / form instead of rebuilding this sequence.
-
-## 4. Diagnose the failed stage, not a guessed cause
-
-- `ITEM_NOT_FOUND_IN_CATALOG`: first inspect the exact donation app ID, campaign ID, **numeric**
-  `options.amount`, and one-time frequency omission. Check the campaign on the same site/identity.
-  The error alone is not proof of a missing campaign, a missing app, or a premium requirement.
-- Keep status, application error code/body and failing stage available to the developer, with tokens,
-  checkout-session URLs and donor data redacted. Give the donor a recoverable inline message. Never
-  replace every error with an unexplained generic failure or convert failures to empty/success states.
-- Keep the form disabled while creating the cart/session. Do not run both add-to-current-cart and
-  donate handlers on the same action. Do not silently retry cart creation after a timeout or redirect
-  failure; inspect/reuse the known cart when possible rather than duplicating the action.
-- Distinguish API handoff from payment acceptance. Cart/session creation can succeed before live
-  payments are enabled. A payments-capable plan and connected, eligible provider are separate
-  go-live checks; recurring donations also need recurring support. Do not hardcode either “premium
-  is never required” or “every checkout error means upgrade”.
-  [Payment setup](https://support.wix.com/en/article/wix-donations-adding-and-setting-up-wix-donations).
-
-## 5. Verify before handoff
-
-For a build accepting donations, run a bounded API smoke test with an **anonymous visitor token**,
-not the owner's token: read a real campaign → create a cart with one numeric donation line → calculate
-and inspect it → create the redirect session. Use the exact requests above with `curl --fail-with-body`,
-`Authorization: <VISITOR_TOKEN>` and `Content-Type: application/json`; mint that identity, when needed,
-with `POST https://www.wixapis.com/oauth2/token`, body
-`{ "clientId": "<PUBLIC_CLIENT_ID>", "grantType": "anonymous" }` → `access_token` / `refresh_token`.
-Confirm permission for this test before creating its cart; do not seed or mutate campaigns to make
-the test pass. Stop at the failing stage and preserve the sanitized response; never loop blind retries.
-
-Check one-time and an offered recurring selection, custom bounds and correction, fee on/off when
-offered, and notes when enabled. Local/mocked checks do not prove live API permissions. In a browser,
-check discovery and form first screens at desktop, 390px and 320px widths, plus keyboard/error behavior.
-Follow a monthly entry through cause selection; confirm its cadence, then cancel/back from checkout
-and refresh to verify the donor's choices survive without implying payment. Confirm hosted checkout
-shows the intended cause, amount, currency and cadence; a resized desktop viewport alone does not
-verify the mobile checkout. **Do not submit a payment** without
-explicit authorization for that transaction and amount. Handoff states which levels passed (API,
-hosted checkout, payment/return), what was blocked, and which setup remains; no mandatory report file.