@wix/agent-skills 1.19.1 → 1.20.0

package/skills/wix-headless-fast/references/storefront/app/wix/storefront/types.ts

@@ -10,14 +10,24 @@ export interface ProductSummary {
   id: string;
   slug: string;
   name: string;
-  /** Lowest price, formatted with currency symbol (e.g. "€34.99"). */
+  /**
+   * The price the buyer pays for the cheapest variant, formatted (an automatic discount already
+   * applied). When `price !== maxPrice` the product is a RANGE — render "price – maxPrice".
+   */
   price: string;
-  /** Highest price, formatted — differs from `price` when variants are priced differently. */
+  /** Highest variant price, formatted — differs from `price` when variants are priced differently. */
   maxPrice: string;
-  /** Strikethrough "was" price, formatted; null when not on sale. */
+  /**
+   * Struck "was" price, formatted; null when not on sale — and ALWAYS null for a range (a lone
+   * struck minimum beside a range claims a saving that may not apply to the variant picked).
+   */
   compareAtPrice: string | null;
-  /** Merchant-set badge ("New", "Best Seller"); null when none. */
+  /** The primary merchant ribbon ("New", "Best Seller"); null when none. Same as ribbons[0]. */
   ribbon: string | null;
+  /** EVERY merchant ribbon, primary first ("New", "Sale") — render all of them, one shared style. */
+  ribbons: string[];
+  /** The cheapest variant's id — what a direct add sends for a product with no options; null when unknown. */
+  minPriceVariantId: string | null;
   availability: Availability;
   /** OUT_OF_STOCK but pre-orderable — label "Pre-order", not "Sold out". */
   preorder: boolean;
@@ -27,6 +37,11 @@ export interface ProductSummary {
   hoverImageUrl: string;
   /** e.g. "2 colors · 3 sizes"; "" for a single-variant product. */
   optionsSummary: string;
+  /**
+   * Hex colors of a color option's visible choices, catalog order — render as small dots on the
+   * tile (a preview, not a picker: selection happens in QuickAdd or on the PDP). [] when none.
+   */
+  swatches: string[];
   /** True when the product can be added to the cart with no choices (single variant, in stock). */
   quickAddable: boolean;
 }
@@ -60,15 +75,21 @@ export interface ProductVariant {
   variantId: string;
   /** The option selections this variant answers to: optionName -> choiceName. */
   choices: Record<string, string>;
+  /** The price the buyer pays, formatted — an automatic discount beats the regular price. */
   price: string;
+  /** Struck "was" price, formatted; null unless it is real and higher than `price`. */
   compareAtPrice: string | null;
   inStock: boolean;
+  /** Out of stock but pre-orderable — still buyable (the add carries preOrderRequested). */
+  preorderEnabled: boolean;
 }
 
 /** A product as the detail page needs it. */
 export interface ProductDetail extends ProductSummary {
   /** Product description as an HTML string — render with innerHTML, not as text. */
   descriptionHtml: string;
+  /** Merchant info sections (materials, shipping, care…) — title + HTML; render as sections or accordions. */
+  infoSections: { title: string; html: string }[];
   /** Every gallery image as a resolved https URL, main image first, de-duplicated. */
   gallery: string[];
   options: ProductOption[];
@@ -80,6 +101,36 @@ export interface Category {
   id: string;
   slug: string;
   name: string;
+  /** Plain-text description when the merchant wrote one; "" otherwise. */
+  description: string;
+}
+
+export interface FacetChoice {
+  /** The option choice id — what searchCatalog({ choiceIds }) filters on. */
+  id: string;
+  name: string;
+  /** Hex color for a swatch facet; null for a text facet. */
+  colorCode: string | null;
+}
+
+/** One filterable option across the catalog (or a category): "Color" with its choices. */
+export interface Facet {
+  name: string;
+  isColor: boolean;
+  choices: FacetChoice[];
+}
+
+/** The catalog's (or category's) lowest and highest product price, as numbers in site currency — the slider's bounds. */
+export interface PriceRange {
+  min: number;
+  max: number;
+  currency: string;
+}
+
+/** What the filter panel needs beyond the product page: the facets and the price bounds of the scope. */
+export interface FacetData {
+  facets: Facet[];
+  priceRange: PriceRange | null;
 }
 
 export interface CartLine {
@@ -97,6 +148,11 @@ export interface CartLine {
   descriptionLines: string[];
   /** Not IN_STOCK → the line can't be checked out as-is. */
   status: string;
+  /**
+   * The recurring plan's terms for a subscription line — "Monthly plan · every month · 12 payments";
+   * "" for a one-time purchase. A subscription line must read as one in the cart.
+   */
+  subscription: string;
 }
 
 export interface Cart {
@@ -105,5 +161,7 @@ export interface Cart {
   itemCount: number;
   /** Formatted subtotal (after discounts) — from the cart estimate, not hand-summed. */
   subtotal: string;
+  /** Formatted CART-level discount (a coupon or cart rule) — "" when none; item discounts are already in subtotal. */
+  discount: string;
   currency: string;
 }

package/skills/wix-headless-fast/references/storefront/app-astro/layouts/SiteLayout.astro

@@ -1,12 +1,18 @@
 ---
 // The site chrome for every storefront page — THIS file (header/footer/nav) plus the @theme
 // token block in src/styles/global.css are what you brand. Keep:
-//   - the <slot name="seo-tags" /> in <head> (the product page's owner-editable SEO lands there)
+//   - the <slot name="seo-tags" /> in <head> (the product page's owner-editable SEO lands there,
+//     including the <title> — which is why ours is printed only when the slot is empty)
 //   - the global.css import (Tailwind + the design tokens every shipped component reads)
 //   - one <CartButton> in the header and one <CartDrawer> per page (both client:only —
 //     they read browser cart state and must not server-render)
+//   - category links in the nav (or your own menu/footer) — every category page reachable by
+//     a real link (`/category/<slug>`), from the live tree, so a category the owner adds later
+//     shows up with no code change
 import CartButton from "../components/storefront/CartButton";
 import CartDrawer from "../components/storefront/CartDrawer";
+import { fetchCategories } from "../wix/storefront/catalog";
+import type { Category } from "../wix/storefront/types";
 import "../styles/global.css";
 
 interface Props {
@@ -14,6 +20,15 @@ interface Props {
   description?: string;
 }
 const { title, description } = Astro.props;
+
+// Non-fatal: the chrome renders without the links if the read fails. Six in the header keeps a
+// large tree from crowding it — put the rest in a menu or the footer, but keep them linked.
+let navCategories: Category[] = [];
+try {
+  navCategories = (await fetchCategories()).slice(0, 6);
+} catch {
+  /* the shop link still reaches everything */
+}
 ---
 
 <!doctype html>
@@ -21,7 +36,8 @@ const { title, description } = Astro.props;
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>{title}</title>
+    {/* The product page's <SEO.Tags> renders the <title>; print ours only when no page filled the slot — two titles otherwise. */}
+    {!Astro.slots.has("seo-tags") && <title>{title}</title>}
     {description && <meta name="description" content={description} />}
     <slot name="seo-tags" />
   </head>
@@ -31,6 +47,9 @@ const { title, description } = Astro.props;
         <a href="/" class="text-base font-bold tracking-tight text-foreground no-underline">Brand Name</a>
         <nav class="flex items-center gap-6 text-sm">
           <a href="/shop" class="text-foreground no-underline transition-colors hover:text-muted-foreground">Shop</a>
+          {navCategories.map((c) => (
+            <a href={`/category/${c.slug}`} class="hidden text-foreground no-underline transition-colors hover:text-muted-foreground md:inline">{c.name}</a>
+          ))}
           <CartButton client:only="react" />
         </nav>
       </div>

package/skills/wix-headless-fast/references/storefront/seed/SEED.md

@@ -75,7 +75,11 @@ the shipped UI**: give at least one product a color option and put one product o
 truthfully to the business (a ceramics studio has glaze colors; a bakery doesn't).
 
 **Seeding is additive — never delete or overwrite existing content.** No cleanup, no removing
-"sample" data, no resets. If a cleanup genuinely seems needed, ask the user first.
+"sample" data, no resets. If a cleanup genuinely seems needed, ask the user first. The one
+exception is built in: the fast path passes `--fresh-site` because it created the site seconds
+earlier, and the seed then deletes the Stores install's sample products before creating yours
+(`samplesDeleted` in the result). Never pass that flag by hand against a site that existed before.
+Categories are idempotent by name too — a re-run reuses "Donuts" instead of creating a second one.
 
 **A bulk create can partially succeed.** The result carries `failures: [{ name, error }]` next
 to `products` — read it. A non-empty `failures` means those products are genuinely absent, not

package/skills/wix-headless-fast/references/storefront/seed/seed-store.mjs

@@ -1,7 +1,7 @@
 // Storefront seed — a BUILD-TIME script, never shipped in the app. Run it from the project
 // root (where wix.config.json lives) with a plan file:
 //
-//   node <SKILL_ROOT>/references/storefront/seed/seed-store.mjs plan.json
+//   node <SKILL_ROOT>/references/storefront/seed/seed-store.mjs plan.json [--fresh-site]
 //
 // It mints its own site token via the Wix CLI (the token never leaves this process), installs
 // the Wix Stores app if needed, waits for the V3 catalog, bulk-creates products (variants
@@ -331,11 +331,34 @@ async function stockOptionlessProducts(ctx, created) {
   }
 }
 
+// Existing categories by name (for idempotent reruns) — a re-run of the seed must reuse
+// "Donuts", not create a second one. Empty map on any failure (falls back to create).
+export async function queryCategoriesByNames(ctx, names) {
+  const out = new Map();
+  if (!names.length) return out;
+  try {
+    const r = await req(ctx, "/categories/v1/categories/query", {
+      body: { treeReference: { appNamespace: "@wix/stores", treeKey: null }, query: { cursorPaging: { limit: 100 } } },
+    });
+    const wanted = new Set(names);
+    for (const c of r.categories ?? []) if (wanted.has(c.name) && !out.has(c.name)) out.set(c.name, c.id);
+  } catch (e) {
+    console.error(`category name pre-check failed (creating everything): ${String(e.message).slice(0, 120)}`);
+  }
+  return out;
+}
+
 // Categories share the @wix/stores tree revision — concurrent creates 409, so: sequential.
+// Idempotent by name: a name that already exists is reused, never duplicated.
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/create-category.md
 export async function createCategories(ctx, names) {
+  const existing = await queryCategoriesByNames(ctx, names);
   const out = [];
   for (const name of names) {
+    if (existing.has(name)) {
+      out.push({ id: existing.get(name), name });
+      continue;
+    }
     const r = await req(ctx, "/categories/v1/categories", {
       body: { category: { name, visible: true }, treeReference: { appNamespace: "@wix/stores", treeKey: null } },
     });
@@ -344,6 +367,24 @@ export async function createCategories(ctx, names) {
   return out;
 }
 
+// The Stores install drops sample products ("I'm a product") into every new catalog. On a site the
+// fast path JUST created nothing else can exist, so they are deleted before seeding — otherwise the
+// storefront ships with the samples between the real products. Only called with --fresh-site; a
+// seed against an existing site never deletes anything (SEED.md: seeding is additive).
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/bulk-delete-products.md
+export async function deleteAllProducts(ctx) {
+  let deleted = 0;
+  for (let pass = 0; pass < 10; pass++) {
+    const r = await req(ctx, "/stores/v3/products/query", { body: { query: { cursorPaging: { limit: 100 } } } });
+    const ids = (r.products ?? []).map((p) => p.id).filter(Boolean);
+    if (!ids.length) break;
+    await req(ctx, "/stores/v3/bulk/products/delete", { body: { productIds: ids } });
+    deleted += ids.length;
+    if (ids.length < 100) break;
+  }
+  return deleted;
+}
+
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/bulk-add-items-to-category.md
 export async function addProductsToCategories(ctx, mapping) {
   for (const [categoryId, productIds] of Object.entries(mapping)) {
@@ -421,12 +462,22 @@ async function setSiteCurrency(ctx, currency) {
  * threaded in memory. This is the default path — call it once instead of the individual
  * functions.
  */
-export async function setupStore(ctx, { products = [], categories = {}, currency } = {}) {
+export async function setupStore(ctx, { products = [], categories = {}, currency } = {}, { freshSite = false } = {}) {
   validateProducts(products);
   await installStoresApp(ctx);
   // Before any product exists: a product's price is stored in the site currency at create time,
   // so switching afterwards leaves the catalog priced in the old one.
   if (currency) await setSiteCurrency(ctx, currency);
+  // A just-created site holds only the install's sample products — clear them (never on an
+  // existing site: the flag is the fast path's, set only when it created the site itself).
+  let samplesDeleted = 0;
+  if (freshSite) {
+    try {
+      samplesDeleted = await deleteAllProducts(ctx);
+    } catch (e) {
+      console.error(`sample cleanup failed (seeding on top): ${String(e.message).slice(0, 120)}`);
+    }
+  }
 
   // Idempotent by name: an errored bulk create (429/5xx) may still have applied server-side,
   // and SKILL.md tells the agent to re-run a failed seed — creating only the names that don't
@@ -478,21 +529,23 @@ export async function setupStore(ctx, { products = [], categories = {}, currency
   // failures is part of the result, not an exception: a partial seed still leaves a usable
   // store, and the agent needs the names to report rather than silently shipping a short
   // catalog. Re-run the seed to retry them — existing names are skipped, not duplicated.
-  return { products: withNames, categories: cats, imagesAttached, failures };
+  return { products: withNames, categories: cats, imagesAttached, samplesDeleted, failures };
 }
 
 // ---- CLI entry ----------------------------------------------------------------------------------
 
 const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").pop());
 if (invokedDirectly) {
-  const planPath = process.argv[2];
+  const args = process.argv.slice(2);
+  const freshSite = args.includes("--fresh-site");
+  const planPath = args.find((a) => !a.startsWith("--"));
   if (!planPath) {
-    console.error("usage: node seed-store.mjs <plan.json>   (run from the project root)");
+    console.error("usage: node seed-store.mjs <plan.json> [--fresh-site]   (run from the project root)");
     process.exit(1);
   }
   const plan = JSON.parse(readFileSync(planPath, "utf8"));
   const ctx = makeCtx();
-  setupStore(ctx, plan)
+  setupStore(ctx, plan, { freshSite })
     .then((result) => console.log(JSON.stringify(result, null, 2)))
     .catch((e) => {
       console.error(e.message);

package/skills/wix-manage/SKILL.md

@@ -48,6 +48,9 @@ Generate an SEO content plan and read its blog post topics, or troubleshoot an e
 ### [Manage Google Search Console for a Wix Site](references/seo/manage-google-search-console.md)
 "Connect a Wix site to Google Search Console and drive its setup through the public GSC Connection and Site Readiness APIs: check connection and readiness, start the Google authorization, verify ownership, add the property, submit the sitemap, request indexing, read search performance, run URL inspection, recover a stale connection, or disconnect. The site owner authorizes in their own browser via a single-use connect URL."
 
+### [Generate AI SEO Suggestions for a Wix Site](references/seo/manage-seo-suggestions.md)
+"Generate AI-written SEO text for a Wix site through the public Tag Suggestions and Page Optimization APIs: title tag and meta description options for a page, alt text for the images of a page, store product, or blog post (one image or up to 20 per call), corrected heading levels for a page's headings, and a whole-page rewrite of title, description, headings, and body text aimed at the page's focus keyword, returned as before/after pairs. Use it when the user wants to improve, optimize, audit, or write the SEO text of a page or the homepage. Suggestions are returned for review; applying one is a separate SEO tags write."
+
 ---
 
 ## Accessibility
@@ -107,7 +110,7 @@ Full CRUD operations for Wix Bookings services using Services API. Covers servic
 "Answers whether an appointment-based Wix Bookings service currently has bookable availability — the primary question — and diagnoses the cause only when there's no availability or the owner asks why. To diagnose, first rules out service-level blockers the availability endpoint can't see (service hidden, online booking off), then runs DiagnoseAvailability for ordered, machine-readable staff/setup reasons, with a manual fallback for booking-policy and capacity causes. Use when someone asks whether a service has availability, or why a service shows no times / customers can't book it."
 
 ### [End-to-End Booking Flow](references/bookings/end-to-end-booking-flow.md)
-Complete booking flow from service discovery to payment. Query services, check availability with Time Slots V2, create bookings, and process payment via eCommerce checkout.
+Books and settles appointments, classes and courses with the site owner's credentials — an operator managing bookings, or server-side code booking as the owner. Covers service discovery, availability with Time Slots V2, creating the booking, and settling it by direct confirmation or eCommerce checkout. A visitor booking for themselves needs a visitor token instead; this recipe links that path.
 
 ### [External Calendar Integration](references/bookings/external-calendar-integration.md)
 OAuth-based integration with Google Calendar, Microsoft Outlook, and Apple Calendar. Covers authentication flows, sync configuration, and bidirectional event management.
@@ -251,7 +254,7 @@ Buy a domain through Wix or connect one the user already owns — intent, availa
 "Creates an event with the Wix Events V3 API — the required request body, ISO-8601 date and time settings, venue/online/TBD location, RSVP vs ticketed registration, guest capacity, short vs rich-text descriptions, ticket tiers and pricing, and recurring series. Covers the exact field shapes and the API's misleading validation messages. Use when the user wants to create an event, set its date, location, description, guest limit or ticket prices, or set up a repeating event."
 
 ### [Manage Wix Events — Publishing, Cancelling, Cloning and Counting](references/events/manage-wix-events.md)
-"Operates on events that already exist with the Wix Events V3 API — publishing a draft, cancelling, deleting, cloning, updating an event's date or details, and counting events. Use when the user wants to publish or cancel an event, duplicate one, move an event's date, or count their events. Creating an event, its tickets or a recurring series is a separate recipe."
+"Operates on events that already exist with the Wix Events V3 API — finding an event by title, publishing a draft, cancelling, deleting (one or by filter), cloning, updating an event's date or details, and counting events. Use when the user wants to find, publish or cancel an event, duplicate one, move an event's date, delete events in bulk, or count their events. Creating an event, its tickets or a recurring series is a separate recipe."
 
 ---
 
@@ -289,7 +292,7 @@ Creates payment links for unpaid bookings using Payment Links API. Links booking
 **Routing — Google paid-advertising campaigns for a site (Smart & Performance Max).** All flows require a Google Ads account, created once via the setup recipe. Budgets are in micros (1,000,000 = 1 currency unit). REST base: `https://www.wixapis.com/_serverless/pa-google/v1`.
 - **First-time setup / "connect Google Ads" / `ACCOUNT_NOT_FOUND`** → [Install and Create an Account](references/google-ads/install-and-create-account.md) (do this before anything else).
 - **Suggested keywords / geo / budget / ad copy / images** → [Get AI Campaign Suggestions](references/google-ads/get-campaign-suggestions.md).
-- **Offer a Success Guide after creating a PMAX Leads campaign (a proactive offer requires approval) / improve it / success guide / says they completed or fixed a guide recommendation / mark or reopen a recommendation** → [Manage a Campaign Success Guide](references/google-ads/manage-campaign-success-guide.md) (a direct improvement/guide request is already approval; works while `LEARNING` and before metrics exist).
+- **Improve an existing campaign / see what to fix next / Campaign Success Guide / mark or reopen a recommendation** → [Manage a Campaign Success Guide](references/google-ads/manage-campaign-success-guide.md).
 - **Create a multi-channel / lead-gen / Shopping campaign** → [Create a Performance Max Campaign](references/google-ads/create-performance-max-campaign.md).
 - **Pause / resume / launch / update budget / delete / history** → [Manage Campaign Lifecycle](references/google-ads/manage-campaign-lifecycle.md).
 - **Performance, conversions, search terms, per-product / per-asset metrics** → [Query Campaign Performance Analytics](references/google-ads/query-campaign-analytics.md).
@@ -308,7 +311,7 @@ Creates payment links for unpaid bookings using Payment Links API. Links booking
 "Manages existing Google Ads campaigns on a Wix site: list/get, launch (first activation) vs resume (reactivate after a pause), pause a running campaign — optionally with a scheduled auto-resume date — update name/budget/targeting, change the daily budget, delete permanently, and read status history / change log. Use when the user wants to 'pause my Google ad', 'resume my campaign', 'stop the campaign', 'change my daily budget', 'rename the campaign', 'delete this campaign', 'list my Google Ads campaigns', or 'why did my campaign status change'. Requires an existing Google Ads account and campaign. REST base https://www.wixapis.com/_serverless/pa-google/v1."
 
 ### [Manage a Campaign Success Guide](references/google-ads/manage-campaign-success-guide.md)
-"Retrieves and manages the campaign success guide for an existing Wix Google Ads Performance Max Leads campaign. Offer it after creating a supported campaign, even while it is learning or has no metrics; that proactive offer requires approval before retrieval. A direct request to improve a campaign, see what to fix next, or show the guide is already approval to retrieve it. Also use when a user reports completing or wants to reopen a guide item. Treat a clear completion report as an actionable update request even when phrased as a statement. Covers campaign selection, prioritized guide retrieval, and suggestion status updates without redundant confirmation. REST base https://www.wixapis.com/pa-platform/suggestions/v1."
+"Campaign Success Guide for existing Wix Google Ads Performance Max Leads campaigns. Use after creating a supported campaign, even while it is learning or has no metrics, and whenever users ask how to improve a campaign, what to fix next, to view the guide, or to mark or reopen a recommendation. Covers campaign and site selection; prioritized actionable recommendations; deduplicated, destination-specific Editor and Google Ads navigation; offers to perform supported work after approval; Merchant Center and Business Profile connection follow-ups; and suggestion-status tracking."
 
 ### [Query Campaign Performance Analytics](references/google-ads/query-campaign-analytics.md)
 "Reads performance analytics for a Google Ads campaign on a Wix site: daily performance metrics (impressions, clicks, CTR, cost, leads, phone calls) with optional previous-period comparison and trends; conversion metrics from Wix Analytics (orders, revenue, leads, CPL, ROAS); the search terms that triggered a campaign's ads; per-product shopping performance for retail campaigns; and per-asset performance (headlines, descriptions, images) for PMAX Leads. Explains when to use campaignResourceName vs the Wix campaignId, the dateRange shape, field enums, sorting, and paging. Use when the user asks 'how is my campaign doing', 'show ad performance', 'what search terms triggered my ads', 'which products/assets perform best', 'campaign ROI/ROAS', or 'conversions from my Google ads'. REST base https://www.wixapis.com/_serverless/pa-google/v1."
@@ -425,7 +428,7 @@ Drive the Wix Site Import agent to migrate an existing store or site from anothe
 "Builds direct links to the account-level sites pages on manage.wix.com — the My Sites list (all sites in the account) and each site's own dashboard. Pairs the site list with the Query Sites read API. Use when the user asks where something is in the Wix dashboard, wants a direct link to a dashboard page, or you need a dashboard URL to include with the result of an API operation."
 
 ### [Upload a Website or HTML Files](references/sites/upload-static-site.md)
-Get a user's ready-made website live on Wix when they already have the site files — an index.html, a zip, or a static build exported from an AI builder or any other tool — by sending them to the Wix Headless drop page, where they upload the files and instantly get a live hosted site they can claim into their account. Use whenever the user wants to upload, publish, or host their own HTML/CSS/JS files as a NEW site. Not for migrating a live store/site from another platform by URL or from CSV exports (use Site Import), not for adding HTML or custom code into an existing Wix site, and not for uploading images or documents to a site's media files.
+Publish a user's ready-made website — an index.html, a static build, or a zip exported from an AI builder or any other tool — as a new live Wix site. Covers both ways to get there — handing the user the Wix Headless drop page, and calling the Wix Headless instant-site REST API yourself when you can reach the files and make outbound HTTPS requests. When you also hold the user's identity, covers putting the published site straight into their Wix account and reading back its final live URL. Use whenever the user wants to upload, publish, deploy, or host their own HTML/CSS/JS as a NEW site, including files generated for them earlier in the conversation, or to update a site already published this way (iterate on the same site instead of creating another). Not for migrating a live store/site from another platform by URL or from CSV exports (use Site Import), not for adding HTML or custom code into an existing Wix site, and not for uploading images or documents to a site's media files.
 
 ---
 

package/skills/wix-manage/references/bookings/create-and-update-booking-services.md

@@ -201,6 +201,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "Consultation",
       "type": "APPOINTMENT",
@@ -234,6 +235,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "Free Consultation",
       "type": "APPOINTMENT",
@@ -264,6 +266,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "Yoga Class",
       "type": "CLASS",
@@ -283,7 +286,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   }'
 ```
 
-After creation, use the `service.schedule.id` from the response to create class events with `bulkCreateEvents` (see Step 3).
+After creation, use `results[0].item.schedule.id` from the response to create class events with `bulkCreateEvents` (see Step 3). This requires `returnEntity: true` on the request — without it the response carries only `results[0].itemMetadata.id`, which has no `schedule.id`; and the created service is directly under `item` (there is no `item.service`).
 
 **Required Fields:**
 

package/skills/wix-manage/references/bookings/create-appointment-service.md

@@ -109,6 +109,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -142,6 +143,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -171,7 +173,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
 - `schedule.availabilityConstraints.sessionDurations` sets the appointment length
 - Availability is based on the assigned staff member's working hours schedule
 
-Save the `serviceId` from the response: `results[0].item.service.id`
+Save the `serviceId` from the response: `results[0].item.id` (the created service is directly under `item` — there is no `item.service`). This requires `returnEntity: true` on the request; without it the response carries only `results[0].itemMetadata.id`.
 
 ---
 

package/skills/wix-manage/references/bookings/create-class-service.md

@@ -96,6 +96,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -124,6 +125,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -149,7 +151,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
 - `defaultCapacity` is **required** — sets max participants per session
 - After creation, class sessions must be scheduled separately via `bulkCreateEvents` using the returned `service.schedule.id` (see [Create and Update Booking Services](./create-and-update-booking-services.md))
 
-**Response:** Save the service ID from `results[0].itemMetadata.id`
+**Response:** Save the service ID from `results[0].item.id` and the schedule ID for `bulkCreateEvents` from `results[0].item.schedule.id` (the created service is directly under `item`). This requires `returnEntity: true` on the request — without it the response carries only `results[0].itemMetadata.id`, which has no `schedule.id`.
 
 ---
 

package/skills/wix-manage/references/bookings/create-course-service.md

@@ -101,6 +101,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -129,6 +130,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -157,8 +159,8 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
 - After creation, course sessions must be scheduled separately via `bulkCreateEvents` using the returned `service.schedule.id` (see [Create and Update Booking Services](./create-and-update-booking-services.md))
 - If the user asked you to create the course and gave the session count/times, the job is not complete after `bulkCreateServices`; continue by creating the Calendar events, then verify the service has future events before telling the user it is ready
 
-Save the `serviceId` from the response: `results[0].item.service.id`
-Save the `service.schedule.id` from the response for the follow-up `bulkCreateEvents` request.
+Save the `serviceId` from the response: `results[0].item.id` (the created service is directly under `item` — there is no `item.service`). This requires `returnEntity: true` on the request; without it the response carries only `results[0].itemMetadata.id`.
+Save the `service.schedule.id` from the response (`results[0].item.schedule.id`) for the follow-up `bulkCreateEvents` request.
 
 ---
 

package/skills/wix-manage/references/bookings/end-to-end-booking-flow.md

@@ -1,11 +1,68 @@
 ---
 name: "End-to-End Booking Flow"
-description: Complete booking flow from service discovery to payment. Query services, check availability with Time Slots V2, create bookings, and process payment via eCommerce checkout.
+description: Books and settles appointments, classes and courses with the site owner's credentials — an operator managing bookings, or server-side code booking as the owner. Covers service discovery, availability with Time Slots V2, creating the booking, and settling it by direct confirmation or eCommerce checkout. A visitor booking for themselves needs a visitor token instead; this recipe links that path.
 ---
 
 # End-to-End Booking Flow (REST)
 
-Step-by-step flow for implementing a complete booking experience using REST APIs.
+Step-by-step flow for creating and settling bookings **with the site owner's credentials** —
+see who that covers, and where visitor-facing code goes instead, immediately below.
+
+> ## ⚠️ These are owner-side calls, not visitor-facing code
+>
+> Every call below runs with the **site owner's credentials** — an API key or the site's admin
+> token. That covers two situations, and both are this recipe:
+>
+> - an **operator managing bookings**, calling these APIs from a script, a management tool, or a
+>   back-office screen
+> - **server-side code in a site or app acting as the owner** — a backend function booking a
+>   client in, a scheduled job, a webhook handler
+>
+> Either way the booking belongs to the site, not to the person being booked.
+>
+> **Building a site or app where a visitor books for themselves? These payloads are right, the
+> identity is not.** A visitor's booking and checkout run on an **anonymous visitor token** minted
+> from the site's OAuth app client id. Using the owner's credentials for a visitor's purchase
+> produces a checkout that belongs to the site: no cart persistence, no abandoned-checkout
+> recovery, and no attribution to the customer. Read these first:
+>
+> - [Book an Appointment](https://dev.wix.com/docs/api-reference/business-solutions/bookings/skills/book-an-appointment)
+>   — the same flow from the visitor's side: visitor token, slot re-validation, booking form
+>   fields, checkout hand-off, and eight pitfalls from real conversations
+> - [Retrieve Tokens](https://dev.wix.com/docs/api-reference/business-management/headless/authentication/retrieve-tokens)
+>   — minting and refreshing the anonymous visitor token
+> - [Allow Redirect URIs and Domains](https://dev.wix.com/docs/go-headless/authentication/setup/allow-redirect-uris-and-domains)
+>   — registering your URLs so the visitor returns to your app after the Wix-hosted checkout
+> - [Manage OAuth Apps](../sites/manage-oauth-apps.md) — creating the OAuth app, whose id is the
+>   `client_id` the frontend mints visitor tokens from
+> - [Bookings Quick Start](https://dev.wix.com/docs/go-headless/self-managed-headless/tutorials/java-script-sdk-tutorials/bookings-quick-start)
+>   — the same flow through the JavaScript SDK on a headless site
+>
+> Mixed apps are normal: the owner's credentials manage the catalog, staff, policies and coupons
+> (the recipes here), while the visitor's own token books and pays.
+
+## Contents
+
+1. [Query Available Services](#step-1-query-available-services) — `POST /bookings/v2/services/query`.
+   The three service types and how each one changes the rest of the flow, plus the four fields to
+   carry forward: `id`, `schedule.id`, `type`, `staffMemberIds`.
+2. [Check Availability](#step-2-check-availability) — `POST /_api/service-availability/v2/time-slots`.
+   Time Slots V2 replaces the deprecated Availability Calendar. Dates must be full local
+   datetimes or the call 400s; `availableResources` stays empty unless you ask for it by resource
+   type; the `location.locationType` a slot returns is **not** the value Create Booking accepts.
+   Classes come from a different endpoint and carry an `eventId`.
+3. [Create the Booking](#step-3-create-the-booking) — `POST /_api/bookings-service/v2/bookings`.
+   One payload shape per service type: appointments need every slot field spelled out, classes
+   need only the service and event ids and derive the rest, courses book a whole schedule.
+   Participants are `totalParticipants` **or** `participantsChoices`, never both. The booking
+   lands as `CREATED` and is not on the calendar until step 4.
+4. [Confirm or Process Payment](#step-4-confirm-or-process-payment) — two branches. Free and
+   pay-at-location bookings are confirmed directly with a payment status. Paid bookings go into a
+   cart that references the booking id, and whoever is paying is sent to its checkout URL; a
+   server-to-server place-order path skips the payment page entirely, which only fits an operator
+   or backend job booking someone in.
+5. [Service Type Summary](#service-type-summary) — appointment, class and course side by side:
+   which `bookedEntity` each uses, which availability API feeds it, and what makes it different.
 
 ## Prerequisites
 
@@ -256,7 +313,15 @@ Use the booking ID as `catalogItemId` with the Wix Bookings app ID. Save `cart.i
 
 Redirect the user to the returned `checkoutUrl`. After payment, the booking is automatically confirmed.
 
-**4c. Place Order (alternative, server-to-server)**
+> When the person paying is a visitor, create the cart and this URL **with their visitor token**,
+> not the owner's credentials — see the note at the top. The call succeeds either way, which is
+> what makes it easy to get wrong.
+
+**4c. Place Order — no payment page (alternative, server-to-server)**
+
+> This one only makes sense on the owner's side: it creates the order outright, with nobody
+> visiting a payment page. Right for an operator or backend job booking someone in; not a way to
+> charge a visitor, who still has to be sent to checkout.
 
 First calculate the cart to get a price-verification token:
 

package/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-seasonal-promotion.md

@@ -1,6 +1,6 @@
 ---
 name: "Flow: Seasonal Promotion"
-description: SEASONAL sub-flow — load [Goal: Seasonal Revenue] FIRST (it owns classification and routing); this is a sub-step, NOT a direct entry from README.
+description: "SEASONAL sub-flow — load [Goal: Seasonal Revenue] FIRST (it owns classification and routing); this is a sub-step, NOT a direct entry from README."
 ---
 # Flow: Seasonal Promotion