/wix-headless

Seed — create the backend content

For each resolved capability, create the backend content its what names. This file carries only the what (entities, counts, policy) and points at each capability's inline recipe for the API how. No endpoints, payloads, field templates, caps, or batching mechanics live here — those are inlined in the per-capability recipe (inline-recipes/setup-*.md, mapped in §2); read them there.

Use $TOKEN / $SITE_ID from the provided authentication mechanism (see <TYPE_DIR>/AUTHENTICATION.md). The capabilities are independent — no cross-capability ordering or shared data (two exceptions: (a) pricing-plans depends on bookings' service IDs, so seed bookings before pricing-plans; (b) restaurants online ordering depends on the restaurants menu — the ordering add-on binds each menu to an operation, so the menu must be seeded before ordering — both in §2). For each one: read its inline recipe (§1; §2 maps each capability to its setup-*.md), build the body from intent.<cap> + brand, execute against wixapis.com with the universal call shape (Bearer $TOKEN + wix-site-id — see SETUP.md §1), and collect the created IDs into a seeded map keyed by capability.

Cleaning up install sample data is fine on a fresh install — but never delete real content without approval. Some recipes start by removing the app install's default sample/mock data (e.g. a demo "Dinner Menu", a "My Portfolio" collection, sample products). That is safe when you just installed the app and what's present is obviously the install's own sample/demo content. But the site may already hold real content (an iterate/connect re-run, or a site the owner has populated) — if what's there isn't obviously install sample data, or you're unsure, do not delete it: ask the user for approval first. Seeding is otherwise additive — create the requested content alongside what's there; deleting or overwriting existing products / collections / menus / forms / projects / media is destructive and needs the user's explicit ask or approval.

Concurrency is an optional optimization, never a requirement. Seeding the capabilities one after another always works — that is the safe default, and an agent doing everything itself simply seeds each in turn. Because the capabilities are independent (above), if your runtime can run work concurrently you may seed several at the same time to save wall-clock. Treat this strictly as "you may," never "you must": a correct seed must never depend on parallelism.

These constraints hold whether you seed serially or concurrently:

• Bookings before pricing-plans. The plan→service coverage step needs the created service IDs, so keep the two in order and seed them together.
• Restaurants menu before its online ordering. The ordering add-on (setup-restaurant-orders.md) verifies/reshapes the auto-provisioned ordering setup for each menu. Installing the Orders app auto-enables ordering for menus that exist and for menus created after install, so ordering binds either way — but seed the menu first, then the ordering, as one unit, so the verify step has a menu to confirm against. If you split this work off to run concurrently, hand over the seeded menuIds and seed menus-then-ordering together.
• Intra-recipe serial rules stay. Store categories are created one at a time (they share the @wix/stores tree revision; concurrent creates 409), and pricing-plans' sub-steps stay ordered.

Read a capability's recipe only if you're going to seed it yourself; if that capability is seeded as a separate concurrent unit, that unit reads the recipe — you don't. Don't read all the seed recipes into your own context and then hand the work off — that loads each recipe twice (once wasted) and bloats working memory. Read-if-you-seed applies equally to the do-it-all-yourself path (read each recipe once, when you seed that capability) and the split-off path (only the unit that seeds a capability reads its recipe).

1 · Where the how comes from — the inline recipes

Each built capability's create flow lives in a self-contained local recipe at inline-recipes/setup-<capability>.md (§2 maps each capability to its file). The recipe inlines every endpoint, request body, and representative response — open it with the file Read tool and seed from it alone; it supersedes the live REST doc pages, so don't go fetch them. Read a recipe once per run — if you already opened it while planning, proceed from what you have — and only read a capability's recipe if you're going to seed it yourself (a separate concurrent unit reads its own; see the concurrency note above).

For a capability with no inline recipe (e.g. coupons), or for a field/error/endpoint a recipe doesn't cover, DOC_DISCOVERY.md is the fallback — never the first move.

Two cautions apply to every capability regardless of recipe:

Public host, not /_api/. Some method pages show an internal https://www.wixapis.com/_api/<service>/... URL in the schema header while the examples use the bare https://www.wixapis.com/<service>/.... Always call the public (non-/_api/) form — that's the external/headless endpoint; the /_api/ prefix is internal and may be rejected.

Imagery is opt-in. When imagery is off (the default), create entities text-only — omit image fields or use the placeholder the recipe documents; don't source imagery. When imagery is on, still create the entities text-first here, then attach generated images in the "Entity images" step below. This applies to every vertical, stores included — there is no per-vertical exception.

2 · What to seed per capability

Each entry states only the entities, where their count/content comes from, the policy that is genuinely the skill's call, the IDs to keep, and which inline recipe carries the calls — read that recipe (local; Read it, don't curl — it's self-contained and supersedes the doc pages) for everything else.

• stores — A product catalog. Recipe: setup-online-store.md. intent.stores.productCount products whose names/prices fit brand. If intent.stores.categoriesNamed is non-empty, create exactly those categories and assign products into them; if empty, create none (skill policy — overrides any docs default). Variant cardinality — keep it small by default: unless intent.stores calls for specific options, give each product at most one option with ≤3 choices (so ≤3 variants/product); many products legitimately have no options (a single variant). Seeding cost scales with the variant Cartesian product and the field count per variant, so don't manufacture options the brief doesn't need — but honor a larger/explicit option set when intent names one (this default is a floor, not a cap). Text-only by default (images only when imagery is on — §1, §4). Keep (seed-time only): categoryIds[] to assign products into their categories; nothing goes to the handoff — the frontend lists products and categories live (queryProducts / searchProducts / queryCategories), so owner-added products/categories appear with no code change.
• blog — Initial posts. Recipe: setup-blog.md. intent.blog.postCount posts on intent.blog.topics (or brand-derived topics). Text-only (no covers). Keep: nothing for the handoff — posts are discovered live (queryPosts, [...slug] routes). Track created post ids only transiently (to confirm success / assign categories).
• cms — Content collections. Recipe: setup-cms.md. One collection per intent.cms.collections entry; itemCount items each, content from brand. Collections are public-read (visitor reads on the frontend) by default. (Opt-in, members only) if the brief calls for per-user-private or member-only data and members login is in the run, seed that collection member-scoped instead (per-user or member-only — see setup-cms.md); a per-user collection is seeded empty (members populate it), since admin-seeded rows are owned by the admin. Keep (→ handoff): collectionIds{<name>} + each collection's field keys — this is structural (the frontend must know the collection name and its fields to query and bind; it doesn't change when an owner adds a row). itemIds{<name>:[]} only transiently, for wiring multi-references during seeding.
• forms — Visitor-fillable forms. Recipe: setup-forms.md. One form per intent.forms.forms entry; fields from the entry, purpose names the form. Keep (→ handoff): formIds[] + each form's field target keys — structural (the frontend binds each input's name = target to submit; targets are immutable, so they don't go stale when an owner relabels a field).
• events — A ticketed or RSVP occasion, or upcoming events. Recipe: setup-events.md. Each event is either TICKETING (paid — it has ticket tiers) or RSVP (free — the registration form is built-in, so don't seed form fields) per intent. For an RSVP occasion (a wedding, party, gathering): one RSVP event with the occasion's real details (title, a future date/time, location). For a ticketed event: the event plus its ticket tiers (default a single "General Admission" tier if none named). For a listing site: intent.events.eventCount events with brand-appropriate titles and future start dates (a default location/timezone is fine). Text-only. Keep: nothing for the handoff — events and tiers are discovered live (queryEvents, getEventBySlug, queryAvailableTickets); track eventIds/ticketDefinitionIds only transiently.
• bookings — Bookable services. Recipe: setup-bookings.md. intent.bookings.serviceCount services (name + short description fitting brand, a simple duration and price); keep the schedule minimal. Keep: serviceIds[] as seed-time state (pricing-plans' coverage step keys on them, below); nothing for the handoff — services are discovered live (queryServices).
• rentals — Rentable resources. Recipe: setup-rentals.md. A resource type per kind of thing rented (rooms, vans, cameras), then intent.rentals.resourceCount resources inside it (Room A / Room B — parallel capacity comes from more resources, not higher capacity), then intent.rentals.serviceCount rental services, each carrying the Wix Rentals appId, serviceResources naming its resource type, a primaryResourceType, and a durationRange (HOUR or DAY) with the min/max the request implies — defaulting to 60/480 minutes hourly and 1/5 days daily when the brief doesn't say — and a per-unit price. No category — unlike bookings, rental services don't use one; don't create or assign one. Order is load-bearing: resource type → resources → services — a service whose resource type holds no resources has permanently empty availability. Seed resources 24/7 (no working-hours schedule) unless the request names opening hours; that keeps a multi-day rental to a single booking. Keep: resourceTypeIds[] as seed-time state (services key on them); nothing for the handoff — rentals are discovered live (queryServicesByFilters filtered by the rentals appId).
• pricing-plans — Membership tiers. Recipe: setup-pricing-plans.md. intent.pricing-plans.planCount recurring plans (name, price, a monthly billing cycle) fitting brand. When bookings is also in this run and the intent is a membership that covers services (a studio/gym/class pass), also attach the covered bookings services to the plan — seed the bookings services first, since coverage keys on their service ids (see the recipe). Keep: the bookings coverage only transiently, to wire it during seeding; nothing for the handoff — plans are discovered live (queryPlans) and plan→service coverage is read live at checkout, never from a frozen map (see how-to-code-pricing-plans.md).
• restaurants — A menu. Recipe: setup-restaurants.md (add-ons have their own recipes, below). Create the itemCount items per section first (name, description, price fitting brand), then the intent.restaurants.sections referencing those item ids, then the menu referencing the section ids — items → sections → menu (build bottom-up: a section is created with its itemIds, a menu with its sectionIds, so each child must exist before its parent — see setup-restaurants.md STEP 1–3). Text-only. Keep (seed-time only): menuId, sectionIds[], itemIds[] to build the tree; nothing goes to the handoff — the frontend reads menus live (listMenus/listSections/listItems). Online ordering (add-on, on demand) — only when the request calls for ordering (not just a displayed menu): install the Orders app (per SETUP.md §2) and follow setup-restaurant-orders.md; seed the menu FIRST, then ordering, in the same unit (ordering auto-provisions per menu either way — see the concurrency note above — but keeping them one unit gives the ordering verify a menu to confirm against). Configure the business-location address (setup-restaurant-orders.md STEP 0) — required for ordering to work end-to-end; without it Wix limits ordering to "testing only" and checkout breaks. If the brief gives no address, set a placeholder and flag the owner in the handoff. Completing a paid order additionally needs premium + a payment method (dashboard/premium — surface, don't fail). Keep: nothing for the handoff — read live (listOperations/listFulfillmentMethods); track operationId/fulfillmentMethodIds[] transiently. Table reservations (add-on, on demand, INDEPENDENT of ordering/menu) — only when the request calls for reservations: install the Table Reservations app (per SETUP.md §2) and follow setup-restaurant-reservations.md; no menu dependency (reservations bind to a location, not a menu — do NOT apply the menu-first rule) and nothing to bulk-seed (visitors create reservations at runtime); configure the business-location address (setup-restaurant-reservations.md STEP 0) — the reservation location is the site's business location, so set a real address (placeholder + owner flag if the brief names none; shared with ordering if both are present); enabling online reservations is premium-gated (record the precondition, don't fail). Keep: nothing for the handoff — read live (listReservationLocations); track reservationLocationId transiently. Experiences (add-on within Table Reservations, on demand) — only when the request names special dining occasions guests reserve (chef's table, tasting menu, tasting-menu evening — an experience, not a bookings service; see CAPABILITIES.md): they need the Table Reservations app (no extra install) and a configured business-location address (setup-restaurant-reservations.md STEP 0, same as reservations) and, unlike plain reservations, they are seeded — create one Experience per named occasion on the default reservation location, following setup-restaurant-experiences.md. Booking an experience is premium-gated like online reservations (record the precondition, don't fail). Keep: nothing for the handoff — experiences are read live (queryExperiences); track experienceId(s) transiently.
• portfolio — A project showcase. Recipe: setup-portfolio.md. Create the intent.portfolio.collections (title + short description fitting brand), then intent.portfolio.projectCount projects assigned to them — collections before projects (a project's collectionIds must hold real collection ids; see the recipe). Text-only by default (omit coverImage; images only when imagery is on — §1, §4). Keep (seed-time only): collectionIds{<name>} to assign projects into their collections; nothing goes to the handoff — the frontend lists collections and projects live (collections.queryCollections / projects.queryProjects), so owner-added content appears with no code change.

Cross-cutting (on demand). coupons is not a standalone capability (CAPABILITIES.md § "Cross-cutting capabilities") — there's no app to install and it's not in verticals[]. If intent calls for discounts and a parent vertical (stores / bookings / events / pricing-plans) is in this run, create coupons scoped to that parent and add the coupon to the seeded map (seeded.coupons = { couponIds[] }). Coupons has no inline recipe — read the create shape from the docs (DOC_DISCOVERY.md is the fallback): every coupon needs a scope with a namespace and its parent vertical's app installed (https://dev.wix.com/docs/api-reference/business-solutions/coupons/about-wix-coupons.md), and the create-coupon spec needs name/code/start + a scope namespace + exactly one coupon-type field (https://dev.wix.com/docs/api-reference/business-solutions/coupons/coupons/create-a-coupon.md). eCommerce needs no seeding — it's the runtime checkout layer that rides along.

members — nothing to seed. Member login is the identity layer (CAPABILITIES.md): members self-register through the Wix login page, so there is no member to create at seed time and nothing lands in seeded. The frontend wiring is the how-to-code-members-*.md recipes (pick per SDK_HANDOFF.md), surfaced via the Handoff. Optionally — and only if a run's prompt explicitly asks to exercise the pricing-plans purchase path end-to-end — seed one test member; keep this off by default so headless runs stay deterministic and don't stall on an interactive login. Do not seed a member just because pricing-plans is present.

Simple seeds (experiment). For these newer capabilities, create the minimum that demonstrates the shape — a couple of entities with required fields only. The recipe (§2) says which fields are required — stop there; don't seed optional structure (variants, multi-session schedules, perks) the host's app won't exercise.

3 · Enable the backend-backed required features

A capability's Required site features (references/CAPABILITIES.md) are part of a complete site, and some of them need a backend feature switched on — not just content created. The clearest case — only when the brief asks for it — is blog comments (readers commenting on posts): comments are intent-gated, not a baseline blog feature (CAPABILITIES.md blog entry), but when requested they need their backend feature available. For each loaded capability, check its Required site features:

• If one depends on a backend feature that isn't on by default, enable it via the method its recipe documents (or DOC_DISCOVERY.md if the recipe doesn't cover it).
• If it's already on by default, there's nothing to seed — but record it as available so the Handoff tells the host to surface it.
• If it genuinely can't be enabled, note that, so the Handoff doesn't imply the site is complete.

Don't silently skip a required feature — a bare list-and-detail with none of its required features is the "half-built site" this is meant to prevent. (Purely presentational items — showing the author, the date — need no backend and belong to the Handoff's Implementation checklist, not here.)

4 · Entity images (opt-in)

Only if imagery is on (from DISCOVERY.md). For each seeded image-bearing capability — stores products, blog covers, CMS items, bookings services, rental services, restaurant items, portfolio projects + collection covers, event heroes — generate a brand-contextual image per entity and attach it as a required pass-2 step (the seeder created the entity text-first in §2; this writes the image onto it), following references/IMAGE_GENERATION.md (generate → import to Wix Media → attach). The per-entity attach shape lives in that capability's own seed recipe (setup-<capability>.md), next to its create shape — read it there; IMAGE_GENERATION.md §3 is a navigation table (entity → recipe → step) that carries no shapes. Use the IDs already in the seeded map. Image failures never block — skip and continue (the entity stays text-only). When imagery is off, skip this step entirely.

Aggregate

Hold a seeded map in scratch — seeded[<capability>] = { …kept IDs… } — as seed-time working state (it feeds intra-seed steps like image attach in §4 and cross-capability wiring like pricing-plans coverage). What crosses into the handoff is only the schema carve-outs, not the per-item content ids: cms collectionId + field keys, and forms formId + field targets (see SDK_HANDOFF.md §4). Everything else the frontend rediscovers with a live query, so it need not be surfaced — carrying a per-item id/slug list into the handoff only tempts the host to hardcode it. Whether to also write a sidecar file is a host-preference choice (default: return-only, in the handoff message).

On a per-capability error, keep the other capabilities' results and surface the failing REST-call response verbatim; partial state is fine — a targeted re-run is bounded.

Proceed to Handoff

With seeded populated, continue to SDK_HANDOFF.md to produce the document the host wires from.