AutoGineer
Generated banner for Wix Headless
Generated logo for Wix Headless

Wix Headless

WixOfficialPublished by Wix

  • Skill
  • Tool integration
  • Software development
  • MIT
  • Low risk
  • Has scripts
Download ZIP

From the author

Connect Wix business services (Stores, Bookings, Donations, CMS, Blog, Events, Forms, and more) to a Wix Headless frontend — infer the needed capabilities, install the apps, seed backend content, and produce an SDK-integration guide. For managed (Wix-hosted) projects it can also build the frontend: scaffold a new site (create) or wire an existing/brought-in design (connect), then build and release. Works across managed, self-managed, and stripe project types. Triggers: set up a Wix Headless backend, add Wix business features to my app, accept donations, build or host a Wix site, connect/implement this design with Wix.
— the description by Wix

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The wix-headless skill acts as an orchestrator for integrating Wix business services (such as Stores, Bookings, and CMS) into a headless frontend architecture. It handles the end-to-end configuration of the Wix backend, including app installation, content seeding, and the generation of a tailored SDK integration guide. Depending on the project type (managed, self-managed, or stripe), the skill can either provide a comprehensive integration guide for the user to implement or, in managed scenarios, actively scaffold, wire, and deploy the frontend project.

What it does

  • Infers required Wix capabilities based on user intent and project context.
  • Installs necessary Wix apps and seeds backend content automatically.
  • Generates a custom SDK integration guide for calling Wix services from the frontend.
  • Scaffolds or connects existing frontend projects to Wix for managed hosting.
  • Handles project-type-specific authentication and deployment workflows.
  • Provides a mechanism to relay feedback to Wix regarding the headless experience.

When to use it

  • When you need to integrate Wix business services into a custom-built headless frontend.
  • When you want to automate the setup and content seeding of a Wix backend.
  • When you are building a new site on Wix infrastructure and need a scaffolded frontend.
  • When you have an existing frontend design and need to wire it to Wix business capabilities.
  • When working with Stripe Projects and requiring a Wix backend configuration.

Advantages

  • Reduces manual configuration by automating app installation and content seeding.
  • Provides a clear, actionable SDK integration guide tailored to your specific capabilities.
  • Supports multiple project architectures including managed, self-managed, and Stripe-based setups.
  • Ensures consistent backend setup by following verified inline recipes.
  • Simplifies the transition from design to a functional, Wix-powered headless site.

Usage examples

“Set up a Wix Headless backend for a store with products and a blog.”
The skill will install the Stores and Blog apps, seed sample products and posts, and provide an SDK guide for fetching this data in your frontend.
“I have an existing design; connect it to Wix and host it on their managed infrastructure.”
The skill will initialize the project, wire the existing UI to the necessary Wix business services, and prepare it for release on Wix.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/wix/wix-headless/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip wix-headless.zip -d .agents/skills

Documentation by Wix

Wix Headless

This skill connects Wix business services to a Wix Headless frontend. Its core job is to configure the Wix backend: infer the needed capabilities, install the Wix apps, seed the backend content, and produce an SDK-integration guide describing how to call Wix from the frontend.

What happens with the frontend depends on the project type and operation:

  • Backend-only (self-managed, stripe, or a managed "just set up the backend" run) — the skill emits the SDK guide as its final output; the host owns the frontend, build, and hosting.

  • Managed create / connect — the skill also owns the frontend: it scaffolds a new project (create) or attaches Wix to an existing one (connect), wires it to the backend using that same guide, builds, and releases to Wix. (There is no Designer or template library — the frontend is built ad-hoc to intent.)

On a backend-only run the skill does not own the project scaffolding. When the work needs a frontend, scaffold it according to user intent — framework and structure follow the prompt; the skill's job is the Wix backend plus the emitted SDK guide describing how to call Wix from whatever frontend exists, not choosing or generating the app. This is the norm for a stripe run: the project is provisioned via Stripe Projects (credentials land in .env — see stripe/AUTHENTICATION.md), the skill configures the backend and emits the guide, and the live site is finalized per stripe/DEPLOYMENT.md — while the frontend is scaffolded and wired to intent, by the host.

Project types

The skill behaves identically across project types except for authentication and deployment, which are isolated in a per-type folder under references/:

Project typeHostingAuthentication & deployment live in
managedWix infrastructure (maintained by Wix)references/managed/
self-managedthe user's own host (TBD)references/self-managed/
stripethe user's own host, provisioned via Stripe Projectsreferences/stripe/

Everything else — Discovery, Setup, Seed, the SDK handoff — is project-type-agnostic and refers to "the provided authentication mechanism" rather than any specific method.

Resolving the project type

Resolve the type before Discovery, in this order — stop at the first that decides:

  1. Caller-provided. If the host/caller passed a project type (managed | self-managed | stripe), use it. An explicit value always wins.

  2. Detect from project signals (on disk). Check the working directory (read-only):

    • stripe — .env carries WIX_WIX_CLIENT_ID / WIX_WIX_CLIENT_SECRET / WIX_WIX_METASITE_ID (or the plain WIX_* fallback). This is the Stripe-Projects fingerprint.

    • managed — a Wix CLI project: wix.config.json present, or a .wix/ directory, or @wix/cli / @wix/astro in package.json.

    • self-managed — a frontend project on disk (e.g. package.json with a bundler/framework) with neither the Stripe .env fingerprint nor the Wix-CLI markers above.

  3. Detect from user intent. If disk is inconclusive, read the prompt:

    • managed — "managed", "host on Wix", "Wix-hosted", "deploy to Wix", "wix release".

    • stripe — "stripe projects", "I added Wix via Stripe", a Stripe-Projects context.

    • self-managed — "self-hosted", "my own host", names a non-Wix host, "I'll deploy it myself".

  4. Ask. If signals are absent or conflict, ask the user which type applies — don't guess.

Hold the resolved type in scratch; it selects <TYPE_DIR> (see Path resolution). Note self-managed is TBD — once resolved to it, the auth step will stop with a clear "not wired yet" error.

Resolving the operation (managed only)

create/connect/iterate are managed-only. For managed, resolve the operation by intent first, directory second — never let an empty directory override what the user is asking for. Check iterate first (it's decided by an unambiguous on-disk signal):

  • iterate → references/managed/CONNECT.md. The project is already connected to Wix — a wix.config.json (or .wix/) is already present — and the owner wants to add or change capabilities. Same flow as connect, but §1 skips init and reuses the existing wix.config.json; never re-init an already-connected project.

  • connect → references/managed/CONNECT.md. The user brings a design not yet connected to Wix and wants it wired: a frontend project on disk without a wix.config.json, or a brought-in/fetched design (a .zip/folder/file you unzip or read, a design-file URL, a Claude-Design/v0/Lovable export), or language like "connect this / implement this design (… connecting to Wix) / host this on Wix / deploy this to Wix / add Wix Headless to this project". A brought-in or fetched design is connect even when the current directory is empty — the design arrives from elsewhere (zip/fetch/URL), so emptiness at trigger time is not a create signal. (CONNECT.md step 1 places the brought design into CWD, then inits it.)

  • create → references/managed/CREATE.md. The user wants a new site built from a prompt with nothing brought in — "build me a site / store / blog…", no design file, no project on disk.

  • backend-only — the user only wants the backend configured (no frontend work). → the shared spine + emit the SDK handoff.

For self-managed and stripe, the operation is always backend-only (the host owns the frontend). Only when there is genuinely no brought-in design and no connect language does directory emptiness decide: empty → create; an existing frontend on disk → connect.

Preconditions (the host provides these — we read, never create)

  1. The project type — managed | self-managed | stripe — provided by the caller, else detected from project signals / user intent (see Project types § "Resolving the project type"), else asked. It selects <TYPE_DIR> (see Path resolution).

  2. A Wix metasite + a headless OAuth app exist, and credentials are available — obtained via the project type's AUTHENTICATION.md. The skill needs a bearer token authorized for the metasite and the metasite id.

  3. The user intent — free text describing what Wix should power ("add a store", "blog + contact form", "persist my app's data").

  4. (Optional) the project on disk — read-only, to sharpen brand/capability inference.

If the credentials are absent, the Wix backend isn't reachable — stop with a clear error.

What this skill does

Always open DISCOVERY.md first (it's agnostic — capability/brand/intent inference + the imagery gate, no auth). Then route by project type + operation:

Backend-only (self-managed, stripe, or managed backend-only) — the lean spine:

  1. Discovery (references/DISCOVERY.md) — infer capabilities + brand + intent + imagery.

  2. Setup (references/SETUP.md) — install the Wix apps those capabilities need.

  3. Seed (references/SEED.md) — create the backend content (+ entity images if imagery is on).

  4. Handoff (references/SDK_HANDOFF.md) — after Setup and Seed, emit the integration guide: SDK bootstrap, per-capability call shapes, the seeded IDs, and the @wix/* package list.

  5. Finalize deployment (<TYPE_DIR>/DEPLOYMENT.md) — run the project-type's finalize steps.

Throughout any run — if the user asks to send feedback to Wix, complains/gets frustrated, or the run hits any real friction (a confusing error, a doc gap, a tooling dead end, a workaround you had to invent — it doesn't need to repeat), offer to relay it to Wix per references/FEEDBACK.md. Default to offering rather than waiting to be asked. Every flow's finalize step (<TYPE_DIR>/DEPLOYMENT.md / managed/CREATE.md / managed/CONNECT.md) ends with the same checkpoint — treat it as a required self-check, not optional. Send only after an explicit yes — never automatically.

Managed create / connect / iterate — after Discovery, hand the whole run to the managed flow:

  • create → references/managed/CREATE.md (scaffold → Setup → Seed → build the frontend → release).

  • connect → references/managed/CONNECT.md (init → Setup → Seed → wire the existing UI → release).

  • iterate → references/managed/CONNECT.md — the project is already connected, so it reuses the existing wix.config.json (no init). Setup / Seed / wiring are incremental: it may already be set up and seeded from a prior run, so the agent checks current state first (installed apps, already-seeded content, existing wiring) and applies only the delta the new intent needs — never blindly re-installing or re-seeding. Re-release only if the frontend build output changed. These reuse the same SETUP.md/SEED.md/SDK_HANDOFF.md, but apply the SDK guide to build/wire the frontend themselves rather than emitting it, and release via managed/DEPLOYMENT.md.

Each Wix call uses the universal call shape (SETUP.md §1) with $TOKEN/$SITE_ID obtained per <TYPE_DIR>/AUTHENTICATION.md. The skill runs non-interactively except for the one imagery question (and asking the project type if it can't be resolved).

Don't smoke-test the frontend locally unless the user asks to verify. The deliverable is the built-and-released site (managed) or the SDK guide (backend-only) — not a local test report. By default do not start a dev server (wix dev / astro dev / npm run dev) to curl pages, drive the cart / booking / login flow, or launch a headless browser: correctness comes from following the recipes, real errors surface at wix build / wix release, and a headless run can't complete an interactive login or a real payment anyway — so these loops routinely burn minutes of wall for little signal (this is distinct from, and in addition to, the "release once at the very end" rule — that one only bans extra build+release cycles, not dev-server testing). Only spin up a dev server and smoke-test when the user's prompt explicitly asks to verify / test / confirm it works — and then keep it to a single lightweight pass (pages compile and render), not a full purchase/booking/login drive. The one post-release check in <TYPE_DIR>/DEPLOYMENT.md is the sanctioned verification.

Donations exception to the smoke-test policy above: for a build that accepts donations, follow the bounded anonymous API handoff check in references/inline-recipes/how-to-code-donations.md before claiming it works. It does not authorize a payment or campaign mutation, and does not require a dev-server testing loop. That recipe also defines the separate hosted-checkout and payment checks.

Path resolution

Compute <SKILL_ROOT> from this file (<SKILL_ROOT>/SKILL.md — strip /SKILL.md); hold the absolute path in scratch. Then resolve the project type to its folder and hold it too:

<TYPE_DIR> = <SKILL_ROOT>/references/<projectType>/ — one of managed/, self-managed/, stripe/.

WhatPath
Vertical index (intent matching + per-vertical site spec)<SKILL_ROOT>/references/CAPABILITIES.md
Discovery (infer capabilities + brand + intent; existing site → the Dynamic Context call in §1)<SKILL_ROOT>/references/DISCOVERY.md
Setup (install apps)<SKILL_ROOT>/references/SETUP.md
Seed (create backend content)<SKILL_ROOT>/references/SEED.md
SDK-integration handoff (emitted, or applied by create/connect)<SKILL_ROOT>/references/SDK_HANDOFF.md
Image generation (opt-in; agnostic)<SKILL_ROOT>/references/IMAGE_GENERATION.md
Design — fallback visual quality bar for the built frontend, when the user gave no design direction of their own (managed create only)<SKILL_ROOT>/references/DESIGN.md
Content — fallback copy quality bar for the built frontend, when the user gave no copy/voice direction of their own (managed create only)<SKILL_ROOT>/references/CONTENT.md
Experience overlays — a vertical's own design + copy bar on top of DESIGN/CONTENT (optional per vertical; read when that vertical is loaded)<SKILL_ROOT>/references/inline-recipes/experience-<vertical>.md (today: experience-store.md, experience-donations.md)
AI features — text/chat + embeddings (opt-in; agnostic)<SKILL_ROOT>/references/AI_FEATURES.md
Feedback — relay the user's headless-experience feedback to Wix (opt-in; user-approved)<SKILL_ROOT>/references/FEEDBACK.md
Authentication — obtain $TOKEN/$SITE_ID/clientId (project-type-specific)<TYPE_DIR>/AUTHENTICATION.md
Deployment — finalize the live site (project-type-specific)<TYPE_DIR>/DEPLOYMENT.md
Managed create flow (scaffold a new project)<SKILL_ROOT>/references/managed/CREATE.md
Managed connect flow (wire an existing project)<SKILL_ROOT>/references/managed/CONNECT.md
Frontend-axis references (how a frontend wires to Wix)<SKILL_ROOT>/references/astro.md, non-astro.md

Start a run by opening DISCOVERY.md. The flow files (CAPABILITIES, DISCOVERY, SETUP, SEED, SDK_HANDOFF, IMAGE_GENERATION, AI_FEATURES) are project-type-agnostic; the per-type specifics live under <TYPE_DIR>/ (AUTHENTICATION.md, DEPLOYMENT.md, and — managed only — CREATE.md/CONNECT.md).

Where the how comes from

This skill has no skill upstream — the how is read from the live Wix docs at dev.wix.com/docs. Read-priority: a page this skill links is read by curl-ing its .md twin directly (first priority — don't re-discover a curated link with search); the Wix MCP doc/search tools are second priority, for finding pages the skill doesn't link or as a fallback if a fetch fails. (Append .md to any docs URL for raw markdown; menu pages list child links, content pages carry the schema.)

Doc discovery is the shared fallback for both tracks — never the first move. Each track's primary source is its pinned material (below); when that doesn't cover what you need, fall back to references/DOC_DISCOVERY.md — a semantic doc-search + schema lookup that works with or without the Wix MCP.

  • Seed reads each capability's create flow from its inline recipe — a self-contained local inline-recipes/setup-*.md (mapped per capability in SEED.md § "What to seed per capability") that inlines the calls and supersedes the REST doc pages, so read it and seed from it alone. Only a capability with no inline recipe (e.g. coupons) falls back to doc discovery (DOC_DISCOVERY.md).

  • Handoff links the SDK docs for each capability's API shape, and supplies the runtime package set from the inlined map in SDK_HANDOFF.md (the SDK .md pages don't expose @wix/* import strings to navigation, so packages are mapped, not navigated).

Setup carries its app-install call (and the appDefId constants) inline in SETUP.md; CAPABILITIES.md is the vertical index that lets Discovery match intent and declares, per built vertical, the Required site features + Implementation checklist that Seed enables (backend-backed features) and the Handoff carries into the guide (so the host builds a complete site, not a bare data dump). This skill carries the what (which capabilities, how much content, what a finished site includes) and reads the how off the docs.

Files

references/inline-recipes/how-to-code-restaurant-orders.md

name: "How to Code Restaurant Orders" description: The frontend cart/checkout contract for a Wix Restaurants Online-Ordering site — which SDK modules to import, how to read the ordering operation + fulfillment methods, the exact restaurant add-to-cart shape (appId = Orders app, options = operationId+menuId+sectionId, NOT variantId), and checkout via eCommerce. Specifies the how (modules + exact calls + failure modes); which menu/items to sell come from the request.

RECIPE: How to Code a Wix Restaurants Ordering Frontend (Online Orders + eCommerce cart)

A contract for the frontend code that lets a visitor order from a Wix Restaurants menu: reading the ordering operation and fulfillment methods, adding a menu item to the eCommerce cart with the restaurant catalogReference, and checking out. This recipe is the how (which modules, which calls, which fields), not the what — which menu/items to sell and how the page looks come from the request you're fulfilling.

This recipe is for CODING ordering, not seeding it. It assumes the backend already exists — a Restaurants Menus backend (menu → sections → items) and the Restaurants Orders app installed and configured (an ENABLED operation with fulfillment methods, every menu ordering-enabled). See setup-restaurants.md + setup-restaurant-orders.md for the backend. This recipe says nothing about creating any of it — only how to read and purchase from frontend code.

Reading (displaying) the menu is a SEPARATE recipe — pair this with it. how-to-code-restaurants.md covers listing menus/sections/items, assembling the hierarchy in sectionIds/itemIds order, reading item.priceInfo.price, and rendering images. That recipe is display-only (no cart). This recipe adds the ordering layer on top: it consumes the same menus/sections/items reads and needs each rendered item's _id, its section's _id, and the menu's _id to build a cart line. Don't duplicate the menu-reading here — read it there, order it here.

⚠️ Reading rule — always append .md?apiView=SDK to every doc link below. The Wix docs render two views of the same page. The bare / REST view shows id; the ?apiView=SDK view shows _id — and the SDK is what your frontend calls. Reading the REST view by mistake is the most common source of the entity.id-is-undefined cart bug. Fetch the .md?apiView=SDK form directly; don't re-discover these with search.

The modules and the client (read this first)

Restaurants Orders app id (a constant you need for the cart's catalogReference.appId): 9a5d83fd-8570-482e-81ab-cfa88942ee60

⚠️ This is the ORDERS app id, NOT the Stores app id. A restaurant menu item added to the cart must carry appId: '9a5d83fd-…' (Orders). Using the Stores id (215238eb-…) — muscle memory from how-to-code-a-store.md — makes eCommerce resolve the line against the wrong catalog and the add fails. Menu items are not Stores products.

NeedPackageModule (namespace)
Menus / sections / items (display)@wix/restaurantsmenus / sections / items — see how-to-code-restaurants.md
The ordering operation (for operationId)@wix/restaurantsoperations
Fulfillment methods (pickup/delivery to show)@wix/restaurantsfulfillmentMethods
Cart (add / get / checkout)@wix/ecomcurrentCartV2
Redirect to hosted checkout@wix/redirectsredirects

Migrating from Cart V1 / Checkout V1? The code below is V2-only — see the migration guide for the before/after.

Auth / client — framework split:

  • Astro (Wix-managed): authentication is ambient. Call operations / fulfillmentMethods / currentCartV2 directly from server components and backend routes (src/pages/api/*.ts) — no createClient, no OAuthStrategy, no clientId.

    import { operations, fulfillmentMethods } from '@wix/restaurants';
import { currentCartV2 } from '@wix/ecom';
const { operations: ops } = await operations.listOperations();

  • Non-Astro (Vite/React/Vue/static): build one manual visitor client and reuse it:

    import { createClient, OAuthStrategy } from '@wix/sdk';
import { menus, sections, items, operations, fulfillmentMethods } from '@wix/restaurants';
import { currentCartV2 } from '@wix/ecom';
import { redirects } from '@wix/redirects';

const client = createClient({
  modules: { menus, sections, items, operations, fulfillmentMethods, currentCartV2, redirects },
  auth: OAuthStrategy({ clientId: /* the project's PUBLIC OAuth client id */ }),
});
// then: await client.operations.listOperations(), await client.currentCartV2.addLineItemsToCurrentCart({...})

    The clientId is public, not a secret. A mis-wired public env var inlines as undefined and 400s every call.

The shapes you read (field cheat-sheet)

These are SDK read shapes (?apiView=SDK), so entity ids are _id. Prices/fees are decimal strings. The cart-add body (under Adding a menu item to the cart) is a separate write shape; the _id rule applies to read entities, not to request params (note the redirect session's checkoutId, which is just the cart's _id).

// operations.listOperations()  →  { operations: [...] }   (no arguments)
operation = {
  _id,                        // → cart options.operationId   (NOT .id → undefined)
  name, default,              // the auto-created ordering operation has default: true
  onlineOrderingStatus,       // "ENABLED" when the site is taking orders
  fulfillmentIds,             // ids of the fulfillment methods attached to this operation
  defaultFulfillmentType,     // "PICKUP" | "DELIVERY"
}

// fulfillmentMethods.listFulfillmentMethods()  →  { fulfillmentMethods: [...] }
fulfillmentMethod = {
  _id, type,                  // "PICKUP" | "DELIVERY"
  name, enabled,              // show only enabled:true to the visitor
  fee, minOrderPrice,         // decimal STRINGS ("0", "5") — no currency symbol
  pickupOptions,              // present when type PICKUP
  deliveryOptions,            // present when type DELIVERY (deliveryTimeInMinutes, deliveryArea, …)
}

// item (from items.listItems — see how-to-code-restaurants.md)
item = { _id, name, priceInfo: { price } }   // price is a decimal STRING; _id → cart catalogItemId

// currentCartV2.getCurrentCart()  →  { cart: { _id, lineItems: [...] } }   // NOTE: returns { cart } — destructure it
lineItem = { _id, name: { original }, quantityInfo: { confirmedQuantity }, pricing: { unitPrice: { amount } }, attributes: { image } }
// price → pricing.unitPrice (ConvertedMoney, NO formatted string in V2 — format it yourself; .amount is site currency, .convertedAmount the buyer's display currency); qty → quantityInfo.confirmedQuantity; image → attributes.image (wix:image:// → resolve)

// the cart's _id is the checkout id → pass to the redirect session:
// redirects.createRedirectSession({ ecomCheckout: { checkoutId: cart._id }, callbacks })  →  { redirectSession: { fullUrl } }

The features (build the ones the site needs)

Each subsection is a self-contained feature — implement only what the site uses. The only ordering is within a feature (read the operation before you build a cart line that references it).

Reading the ordering operation (and the _id rule)

Get the operation so you have the operationId every cart line needs. listOperations() takes no arguments and returns a plain array.

const { operations: ops = [] } = await operations.listOperations();
const op = ops.find((o) => o.onlineOrderingStatus === 'ENABLED') ?? ops.find((o) => o.default) ?? ops[0];
const operationId = op._id;

Doc: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/operations/list-operations.md?apiView=SDK

⚠️ list* return the array as OPTIONAL — default it (= []) or the strict build fails. listOperations() / listFulfillmentMethods() / listItems() type the returned array as T[] | undefined, so destructuring { operations: ops } and calling ops.find(...) directly errors under strict / astro check ('ops' is possibly 'undefined', TS18048) — a build-breaker on managed Astro. Default it in the destructure ({ operations: ops = [] }) or guard with ?? [].

⚠️ CRITICAL: the entity id is _id, NOT id. operation.id / item.id / section.id are undefined in SDK code. Feeding operation.id into options.operationId (or item.id into catalogItemId) sends an empty string and the add-to-cart fails. Use _id everywhere. (A surprising id field means you're reading the REST doc view — re-open with ?apiView=SDK.)

Read the operation once and reuse operationId for every add-to-cart on the page — don't call listOperations() per line item.

Reading fulfillment methods (pickup / delivery to show)

List the methods to render the visitor's pickup/delivery choices (fee, minimum, type). Show only enabled: true.

const { fulfillmentMethods: methods = [] } = await fulfillmentMethods.listFulfillmentMethods();
const offered = methods.filter((m) => m.enabled);

Doc: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/fulfillment-methods/list-fulfillment-methods.md?apiView=SDK (default the array = [] — see the optional-array note above)

⚠️ listFulfillmentMethods takes an OPTIONS object, not a query builder. It accepts an optional { paging } object and returns a Promise of { fulfillmentMethods } directly — do not chain .find()/.eq() on it (that's the queryProducts builder pattern from stores; it does not apply here). fee and minOrderPrice are decimal strings — render them with your currency, and Number(...) only if you need arithmetic. Which method the buyer actually uses (and the delivery time slot) is chosen on the hosted checkout; listing here is for display, not a required pre-checkout step.

Adding a menu item to the cart — the restaurant catalogReference

This is the one shape that differs materially from a Stores cart. Build a line item whose catalogReference names the Orders app and carries operationId + menuId + sectionId in options.

await currentCartV2.addLineItemsToCurrentCart({
  catalogItems: [{                                          // the write shape uses `catalogItems`
    quantity,
    catalogReference: {
      catalogItemId: item._id,                              // the MENU ITEM's _id
      appId: '9a5d83fd-8570-482e-81ab-cfa88942ee60',        // the ORDERS app id (not Stores)
      options: {
        operationId,                                        // from listOperations()
        menuId,                                             // the _id of the menu the item is shown in
        sectionId,                                          // the _id of the section the item is shown under
      },
    },
  }],
});

Doc: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/add-line-items-to-current-cart.md?apiView=SDK

⚠️ CRITICAL: options MUST carry operationId, menuId, AND sectionId — all three. A restaurant line item is identified by where in the menu it was ordered from, not by a variant. Omitting any of the three makes eCommerce unable to resolve the item against the Restaurants catalog — Cart V2 rejects the add with an explicit error rather than accepting an invalid line. This is the restaurant analog of the store's mandatory variantId.

⚠️ CRITICAL: there is NO variantId here. options.variantId is a Stores concept — menu items have no variants in this flow. Don't copy the store recipe's variantId resolution; a restaurant line uses operationId/menuId/sectionId instead. (Menu item modifiers — "extra cheese" — are a separate concern and out of scope for the basic order flow.)

⚠️ Thread sectionId and menuId from the render, not a lookup. When you assemble the menu (menu → sections → items, per how-to-code-restaurants.md), each item is rendered inside a known section and menu — capture that section._id and menu._id at render time and pass them to the add-to-cart handler alongside item._id. Re-deriving an item's section afterward is unnecessary and error-prone; you already have it in the render context.

Optional: options.onlineOrderingPageUrl (e.g. "/online-ordering") lets the buyer click the cart line to return to the item — include it only if your site has such a page.

Checkout — redirect to the hosted checkout page

The cart's _id is the checkout id — pass it into the redirect session's ecomCheckout.checkoutId. Read the current cart, then hand its id to a redirect session (identical to the storefront flow — restaurant orders ride on the same eCommerce checkout). Doc: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.md?apiView=SDK

const { cart } = await currentCartV2.getCurrentCart();   // NOTE: returns { cart } — destructure it
const session = await redirects.createRedirectSession({
  ecomCheckout: { checkoutId: cart._id },   // the cart's _id IS the checkout id
  callbacks: { postFlowUrl: `${origin}/`, thankYouPageUrl: `${origin}/` },
});
window.location.href = session.redirectSession.fullUrl; // the hosted-checkout URL (fulfillment + time slot chosen here)

⚠️ The cart's _id is the checkout id. Pass cart._id into the redirect session's ecomCheckout.checkoutId. And getCurrentCart() returns { cart } — destructure it, or cart is undefined and cart._id throws "Cannot read properties of undefined (reading '_id')".

⚠️ CRITICAL: origin for postFlowUrl/thankYouPageUrl MUST be the https:// published host — derive it from window.location.origin, NEVER new URL(request.url).origin. The Headless redirect allowlist registers the site's https:// host and treats http://<same host> as a different, unlisted origin. If you build the redirect session in a server route (src/pages/api/*), new URL(request.url).origin resolves to http:// behind Wix's TLS-terminating proxy → the buyer's return redirect 403s with "… isn't listed as an allowed redirect domain." Pass window.location.origin from the client into the route (or force the scheme to https). Doc: https://dev.wix.com/docs/go-headless/getting-started/setup/manage-urls/add-allowed-redirect-domains.

⚠️ LIVE PAID CHECKOUT PRECONDITION. A visitor can add to cart and reach the hosted checkout with just this code, but completing a paid order needs the site to have a premium plan and a configured payment method. That's site provisioning, not a frontend bug — if checkout can't collect payment, the setup is incomplete, not the code.

Reading the price and the cart

Menu item price is item.priceInfo.price — a decimal string with no currency symbol (see how-to-code-restaurants.md; the SDK PriceInfo type has only price, no formattedPrice). A cart line's price is lineItem.pricing.unitPrice / pricing.totalPrice — a ConvertedMoney { amount, convertedAmount }; Cart V2 line items carry no preformatted price, so format it yourself. The currency lives on the cart, not the money object — format from cart.customerInfo?.currencyCode ?? cart.businessInfo?.currencyCode (see the Formatting cart prices section of how-to-code-a-store.md for the exact Intl.NumberFormat helper), e.g. new Intl.NumberFormat(undefined, { style: 'currency', currency }).format(Number(pricing.totalPrice.convertedAmount ?? pricing.totalPrice.amount)). Cart line images are wix:image:// identifiers — resolve them with media.getScaledToFillImageUrl(id, w, h, {}) (4 args), never raw (see the store/menu recipes' image callout).

Conclusion

A correct Restaurants ordering frontend:

  • imports operations / fulfillmentMethods from @wix/restaurants (plus menus/sections/items for display) and currentCartV2 / redirects from @wix/ecom / @wix/redirects;

  • uses _id (never id) for the operation, menu, section, and item;

  • reads the operationId once from listOperations() (the ENABLED/default operation) and reuses it;

  • adds menu items with the Orders app id 9a5d83fd-… (never the Stores id) and options carrying operationId + menuId + sectionId (all three) — no variantId;

  • threads menuId/sectionId from the render context, not a re-lookup;

  • checks out by feeding the current cart's _id (the checkout id) to redirects, with an https:// window.location.origin for the callbacks; the hosted checkout collects fulfillment + payment (which needs a premium plan + payment method).

    </content>

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

What our scanner noticed· Low risk

  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Wix
Publisher
Wix (Official)
Source
wix/skills · skills/wix-headless · commit d168bc2
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Wix.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download wix-headless.zip