Build yours with AI

A store like Music Universe, with your brand

Copy this prompt and paste it into a coding agent (Claude Code, Cursor or Codex) in an empty folder. It asks for your Crystallize tenant, your products and your brand, then builds the store on your own tenant.

Raw Markdown

I want a storefront for my business that works like Music Universe (https://music-universe.superfast.shop), a demo store built on Crystallize: Every player hears a different store: four faders re-rank the catalogue live from a taste vector, typed specs check every cable in a signal chain, and a band’s stage plot becomes a native Crystallize quote at the venue’s prices — with rentals from three depots, and the same record answering the on-site assistant and Claude over MCP.

The content model and the wiring below are proven in that store: keep them for the features I want, and rename things to fit my trade. If a feature doesn't fit my business, leave its parts out rather than forcing it. Everything I see is mine to decide: brand, colours, typography, layout, copy and pages. Don't copy the demo's look; build my brand.

What the demo does: vector personalisation, explainable ranking, typed specs and filters, compatibility checks, quotes, rental, native booking, customer price lists, ai concierge, multiple markets, multi-currency. It is B2C and B2B, in English, Norwegian, Swedish; my markets and languages may differ.

How to work with me

  • You need to run commands, edit files and use MCP tools. If you can't (for example in a plain chat), tell me, and suggest I paste this prompt into Claude Code, Cursor or another coding agent instead.
  • Ask your questions a few at a time (three to five), in the order of the steps below, and suggest a sensible default for each so I can just say yes. Ask each thing once, even where two lists overlap, and ask the ones that change the build first. Don't start a step before the one before it is done.
  • The technical detail below is for you. Talk to me in plain words, and explain a choice only when I need to make it.
  • Keep the folder empty until step 5, apart from .env.local.
  • Never ask me to paste an access token secret into the chat, and tell me not to paste a filled-in command or its output either. Tell me which command to run or which file to put it in, and I'll do it.
  • Before you create or change anything in Crystallize, show me the plan (shapes, pieces, topics, price variants, markets) and wait for my yes. Before an import, show me a sample of five items.
  • Use the Crystallize skills (the skills MCP tool, or the use-crystallize plugin) for how-to: content-model, information-architecture, taxonomy, data-creation, mass-operations, pricing, query, mutation, js-api-client, responsive-images, payments, and when this store needs them subscriptions, bookable-resources, vector-ranking and permissions. Where this prompt and a skill disagree, the skill wins. Check the live schemas with the MCP instead of guessing field names.
  • When something I asked for isn't possible in Crystallize the way I pictured it, say so and offer the closest thing that is.
  • The storefront never reads from the Core API on customer-facing pages. Products, public prices, stock and content come from the Discovery API and the Catalogue API; confidential prices (negotiated B2B price lists) from the Catalogue API on the server.
  • Use the Shop API for everything about customers: carts, checkout, customers, orders (including orders created directly, such as renewals), order meta, pipeline stages, payments and subscription contracts. Take the customer identifier from the server session, never from the browser. The Core API is for setup scripts, back-office tools, scheduled jobs and what the Shop API can't do, always on the server and never once per page view.

Step 1: Crystallize tenant, tokens and MCP

Ask me:

  1. Do I have a Crystallize account and a tenant for this store? If not, I sign up for free at https://app.crystallize.com/signup and create an empty tenant. Ask for its tenant identifier.
  2. Do I have access tokens? If not, tell me: in the Crystallize App, go to Settings → Access Tokens → Generate a new token, name it, and keep the ID and the secret (the secret is shown once). A token acts with its user's role, so while we build, that user needs to be Tenant Admin (or have a role that can write shapes, pieces, topics, items and prices and run mass operations). Once the store is built, switch the MCP to a token from a read-only user.
  3. Is the Crystallize MCP connected, with write access? Check that you have its write tools (run-mass-operation, mutate-core), not only the read tools (tenant-overview, fetch-content-model): with only the read tools, it was added without ?exposeWrite=true. If it's missing, have me run this in my terminal with my own token, then restart you:
    npx add-mcp "https://mcp.crystallize.com/mcp?exposeWrite=true" \
      --header "X-Crystallize-Access-Token-Id: <token id>" \
      --header "X-Crystallize-Access-Token-Secret: <token secret>"
    
    If the MCP can't be connected in my tool, say so and fall back to scripts that call the Crystallize APIs with the tokens from .env.local. In Claude Code, also suggest the Crystallize skills: /plugin marketplace add crystallizeapi/ai, then /plugin install use-crystallize@crystallize-ai. The plugin brings its own read-only Crystallize MCP entry with placeholder credentials: keep using the one added above (and add &exposeSkills=false to its URL once the plugin's skills are installed).
  4. Confirm the connection with tenant-overview, and tell me what's already in the tenant. If it isn't empty, ask whether to build next to what's there or in a fresh tenant.

The storefront needs the tenant identifier and its own credentials: an access token pair for the Shop API (server only), and a static auth token if Discovery and the Catalogue API are secured. Don't reuse the admin build token in production. Put them in .env.local (have me fill in the secrets) and make sure .env* is in .gitignore.

Step 2: my business and my brand

Ask me:

  • What I sell, who buys it, and what makes us different. My brand name and a one-line pitch.
  • My markets, currencies and languages, and my VAT/tax setup.
  • Where my product data lives today: a spreadsheet or CSV, an export from Shopify, WooCommerce or another platform, a PIM or ERP, my current website, or nothing yet. Where my product images are.
  • My brand: logo (SVG if I have it), colours, typefaces, tone of voice, and two or three sites whose look I like. If I have no brand guide, propose a direction from my answers and show it before building pages.
  • Where it should run: my own domain, and hosting (suggest Vercel for Next.js).

Then ask what is particular to this kind of store:

  • Which brands do I carry, and which series (Player II, American Professional II, Qu, SQ)? Signature models are a manufacturer fact, not an artist page.
  • Do my suppliers give me typed specs (connectors, phantom power, preamp gain, current draw, impedance, scale length), or must they be researched per product? Every compatibility check in this store reads them.
  • GTIN and the manufacturer's article number per variant (finish, handedness, cable length)? Never invent them: an empty GTIN means "not registered".
  • Do I rent out gear? Which depots, which units per depot, which periods (day, weekend, week), cancellation and hold rules, and do I hire out PA packages sized by audience?
  • Trade customers: venues, rental companies, schools, studios? A published discount per segment, contract prices per company, quotes, purchase approvals above a budget limit, invoice terms?
  • Which genres, rooms (studio, club, big stage), eras and levels do my customers think in? They become the faders and the taste vectors.
  • Can I export margin, units sold in the last 30 days, ratings and stock per SKU? Order history per customer, imported through the Shop API?
  • Can I use the manufacturers' images, and is the store black (packshots then need transparent cutouts)?
  • Do I want sound on the site (blind A/B clips of amps, pedals or mics)? From which source, with whose permission, and how are the creators credited?
  • Should an AI assistant shop the store, inside the site and/or as an MCP server so Claude can? Which AI provider key?

Step 3: the content model

Create this in my tenant with the MCP, renamed to fit my trade, after I have approved the plan. Keep the structure: it is what the storefront's features depend on.

Build in dependency order, since mass operations run in sequence with no rollback: pieces and shapes (empty first, then their components), topic maps (at most 30 topics per topic/create), price variants, markets and VAT types, the folder tree (two to four levels, five to twelve per level), and only then items. Use lowercase-hyphen identifiers. Decide now which fields are translated and which are discoverable. Restrict every item relation with acceptedShapeIdentifiers. Never add price or stock components to a shape: variants have them built in.

Every text, rich text, selection and relation the storefront shows must be discoverable (explicitly); translate text if I sell in more than one language.

  • gear (product): one sellable shape for everything sold, with a specs component choice of 20 family pieces. One shape gives one Discovery type, one filter and facet set, and cross-family ranking (a mic, an interface and monitors in one query).
    • Storytelling: tagline, summary, story, highlights (→ technology), videos. brand (exactly one), line (max one), technologies (max 8), made-in, launch-year, launch-date.
    • physical piece: weight kg, width/height/depth mm, rack units, IP rating.
    • signal piece, the compatibility contract on every product: inputs and outputs (multi-selection of connectors, no gender; cables carry connector-a source and connector-b sink), phantom (requires / supplies / not-needed: a selection, because "not needed" is a fact), protocols (USB audio, Thunderbolt, Dante, dSNAKE, SLink, gigaACE, DX, AES50, MADI, ADAT, MIDI…), power source and connector, power consumption W, operating voltage V, current draw mA, DC polarity.
    • Family pieces, typed components only (numeric with one unit each, mapped to UN/CEFACT; selection; switch only for what is true): electric guitar, acoustic guitar, bass (each embedding a neck piece: scale length mm, fingerboard radius in, frets, nut width), amplifier (format, power W, impedance Ω, speaker outputs 2/4/8/16 Ω), effects (effect types, bypass, stereo, MIDI, presets), power supply (output groups: count × V × mA, isolated), mixer, stagebox, PA, microphone (application, sensitivity mV/Pa, max SPL, self-noise), wireless, interface (mic preamps, max gain dB, Hi-Z inputs), studio monitor, headphones, controller, stand, cable, strings, case (fits-body), accessory (DI type, pad, ground lift). Each family has an anchor field every product fills, for exists filters. No properties tables.
    • in-the-box (repeatable chunk), warranty, provenance chunk for one-of-one instruments; ranking numerics margin, sold-30d, rating, review-count, campaign-boost.
    • Relations (all ≤75): pairs-with (12), fits (40), compatible-with (40), alternatives (8), rental (1). Strings, cables and supplies fit by spec, not by relation.
    • Variant components: gtin (pattern), mpn, fingerboard, handedness, swatch (rendering only, never a facet), serial-number, units-per-carton, length m (one cable variant per length). Attributes finish, fingerboard, handedness drive the colour picker.
  • rental (product): one booking pool per product; variants are periods with duration-hours (day 24, weekend 68 = Fri 12:00–Mon 08:00, week 168). equipment (→ gear) or included rows (quantity + SKU + note) for packages, audience-max, input-channels, depots, add-ons.
  • service (product): pro setup, damage waiver, delivery and pick-up, sound engineer per day.
  • banner (document, folder /blocks): kicker, headline, body, call to action, image, product relations (live names and prices, so copy never carries a price), priority, validity. Placement is a topic (/placement/home-hero, /placement/category-strip, /placement/home-tools); its other topics give it a taste vector like a product's.
  • Documents: brand, line (tier, step-up), technology, guide, landing-page, campaign, rider, depot (address, location, hours, stock location). category folders mirror the category topic map and carry the same blocks.
  • Topic maps on products: brand, category (6 groups → types), line, genre, context, level, price tier, tone (gain from taste; voice warm/balanced/bright and dynamics compressed/balanced/open from two judged numbers per product), era, room, finish colour (on variants), body shape, pickup config, mic type, polar pattern, pedal type, connectivity, power, offer (buy, rent, quote, one-of-one). Spec-derived topics are generated from the typed values, never tagged by hand. Image topics: image type, angle, background, brand, category, finish colour, context.
  • Five taste vocabularies, all derived from topics: sound (genre [1, 0.6, 0.4, 0.3], tone [0.8], pickup config [0.8], pedal type [1, 0.6, 0.35]), rig (brand [1, 0.5], line [0.8], category [1, 0.5], body shape [0.8], mic type [0.6], connectivity [0.8, 0.4], digital protocols only), use (context [1, 0.6, 0.4], price tier [0.7]), mix (drive, era, stage, tier [1] each, written through a rule table from gain, era, room and level topics), ears (voice [1], dynamics [1]; silent gear has none). Bipolar faders are two positive pole keys (drive:clean / drive:driven).
  • Pricing: one price variant per currency, stored excluding VAT (EUR, NOK, SEK, GBP), with shelf prices including VAT on price points. Markets for price lists only: consumer no, se, eu, uk; trade venue, education, rental-partner. Percentage price lists: venue −10 %, education −12 %, rental partner −15 %, a contract list for one company at −20 % (targetAudience by customer identifier, so it stays confidential), a Black Week campaign list −15 %. Promotions: strings 3 for 2, a code for 500 NOK off. Volume tiers on cables, strings and stands.
  • Stock: default (central warehouse) plus one location per depot. Pipelines: Orders, Rentals, Quotes (Requested → Quoted → Accepted), Approvals (Submitted → Awaiting budget holder → Approved → Ordered).

Step 4: my data

Import my products and content with mass operations, mapping my data onto the model: validate each file with build-mass-operation, run it with run-mass-operation and follow it with get-mass-operation-status. Read the operation logs, not just the task status: a task can finish as complete with failed operations, and there is no rollback. Give every upsert a resourceIdentifier so a re-run updates instead of duplicating, and chunk large imports. Start with a small batch, check it in the Crystallize App with me, then run the rest.

Publish every imported item in each language: the storefront only sees published versions (in a mass operation, item/publish needs real itemIds). Import images from URLs with copyRemoteAsset, or upload them (presigned upload, then registerImage). Renditions are generated in a queue: after a large import, republish once they exist, and have the storefront fall back to the original image URL while variants is empty. Before building pages, query Discovery once; if the tenant isn't ignited yet, run igniteDiscoApi (with stacks: opensearch if we use vector ranking), wait for the task to complete, and allow a few minutes. If I have no data yet, create a small, clearly labelled placeholder set (ten or so products) so we can build the pages, and remind me to replace it.

  • The demo holds 316 products (656 variants) from around 25 brands, Squier and Epiphone included, in English, Norwegian and Swedish; 66 rentals (63 single items and PA packages for 150, 300 and 600 people) with 453 named units at three depots (Oslo, Bergen, Stockholm). Specs, variants, GTINs and images come from manufacturer sites, one polite request at a time; taglines and stories are our own. Prices that no manufacturer publishes are marked as estimates.
  • Images were copied from the manufacturers' CDNs, classified by file name, position and a vision pass, given alt text and topics per language, and white packshots got transparent cutouts for the black store. 39 banner blocks (11 heroes, 21 category strips, 7 tool tiles).
  • Soundcheck audio: TONE3000 captures, rendered offline, with the creators' permission and credit.
  • Build order: tenant → model → taxonomy → customers and price lists → images → catalogue → rental → translations → orders → vectors (gated, then ignite) → cutouts → banners.
  • From me: my range with specs, prices and images, my series, item numbers, depots and rental fleet, trade segments and contracts, and the sounds I want customers to hear.

Step 5: the storefront

  • Next.js 16 (App Router, Cache Components) on Vercel, plain fetch GraphQL clients. Customer-facing pages read only from Discovery, the Catalogue API and the Shop API; the Shop API handles carts, checkout, customers, orders, quotes and bookings. The Core API belongs to the seed scripts and back-office or scheduled jobs: tenant counts for an About page come from a scheduled job or the build, not a Core call on page view.
  • Discovery: browse.gear with topic facets, range facets on spec numerics and pagination; search and autocomplete; trade prices through <variant>PriceFor(marketIdentifiers) for the SKUs on screen. Every ranking is rankBy with house terms (margin, sales, rating, campaign boost, in stock, recency) plus one tasteCosine term per vocabulary of the shopper's taste in context.userTaste. The storefront reads the schema first (does rankBy exist, which fields and vocabularies), because a term naming a missing field fails the whole query.
  • Mix your store: four faders (Tone clean–driven, Era vintage–modern, Room studio–stage, Level first rig–pro) write into the shopper's mix vector (× 1.5). While a fader moves, mix weighs 3 and the other vocabularies 0.8. Category grids re-score the visible cards in the browser from each card's house score and per-vocabulary cosines, then ask Discovery for the exact order on release.
  • Personas: a "log in as" switch over eight demo customers in an httpOnly cookie: Mia, Erik, Sara and Liam (consumers in Norway, Sweden and the UK), Kulturhuset Sentrum (venue), Stageline Utleie (rental partner on contract), Bergen kulturskole (school, approvals) and Lydloftet Studio. Each brings a base taste and a fader preset; switching drops the previous faders. Markets come from the session on the server, never from the browser or a tool argument.
  • Personal content: the front-page hero, the category strip and the order of the seven tool tiles are banner blocks ranked by the same tasteCosine terms as products ("Picked for Erik: Blues, Rock, Vintage"); without a taste, the highest priority wins. The house hero stays the prerendered first paint.
  • Search: the shopper's words become hard filters, shown as removable chips: "48V phantom interface 4 inputs", "Strat with 25.5" scale under 15 000 kr", "Orange 4x12 cab 16 ohm", "kondensatormikrofon". Product types, brands, series, pickups, body shapes, connectors and numbers with units are read in English, Norwegian and Swedish from the taxonomy and a spec model generated from the seed model; only musicians' slang ("strat", "cab", "lydkort") is hand-written. Nothing found: looser spelling, then fewer filters, then suggestions.
  • Signal chain builder: checks each link from the typed specs: connector and the exact cable (or an adapter), phantom (a condenser into a desk without it blocks), gain (mic sensitivity against preamp max gain; warns with an inline preamp), Hi-Z (suggests a DI), protocol (stagebox ↔ mixer, or an expansion card), passive speakers, amp head ↔ cab (impedance against the head's speaker outputs, cab power against head power), and pedalboard power (total mA, outputs, voltage, polarity, digital pedals on non-isolated outputs). The rules are pure code shared with tests; missing cables, supplies and DIs resolve to stocked SKUs (the cable variant of the right length) and go into the basket in one update.
  • Stage plot: a 10 × 7 m stage plot becomes an input list; the band's gear (from the members' order history) and the venue's house kit are matched to inputs by application, and what is missing is bought or rented. The server derives the list again (it never trusts the browser) and sends it as a native quote request in the Quotes pipeline on the venue's account, purchases at its trade price, rentals as weekend lines.
  • Rentals (booked natively in Crystallize): in setup, booking policies (seconds) and one setBookable pool of named units per rental, unit meta holding the depot; publish after every bookable change. In the Shop API: availability per day and depot (Discovery never serves it), bookSkuItem into a cart that already has the customer, cancelReservation when a booked line is removed. Damage waiver and delivery are ordinary service lines.
  • Checkout and quotes: hydrate with the customer and markets (decimals: 4) → set customer and meta → place → confirmCartBooking → createFromCart (standard, or a quote for trade buyers) → wait for the cart's order id → confirm bookings again. Accepting a quote creates an order with relatedOrderIds and moves the quote to Accepted. Order lines carry the product's topic paths in meta, so a shopper's taste can be rebuilt from orders.
  • Blind soundcheck and Mic shootout: five blind A/B rounds of pre-rendered clips from TONE3000 NAM captures (amps and pedals), loudness-matched to −18 LUFS; a six-mic bracket of the same riff through one amp capture into cab IRs recorded with each mic. Only rendered audio is published, never the captures; each reveal names the creator and links the tone. The picks become the shopper's ears vector (a cookie) for every ranking.
  • Shop by song: a curated song or free text maps to topic paths, turned into a taste with the same rules as products; Discovery ranks each slot of the rig (guitar, amp, one pedal per named pedal type) against it.
  • Gift crossfader: the giver's and the receiver's tastes are mixed per vocabulary like two channels, normalised, and passed to Discovery as context.userTaste.
  • Rig recall and side cart: "Your rig" reads the signed-in customer's orders back, groups the gear and runs the chain rules to say what it lacks. The side cart's "Completes your rig" takes candidates from the basket's relations and companion product types, ranks them by taste in one Discovery query, and drops what is in the basket or already owned.
  • On-site assistant: a streamed Claude tool loop at /api/assistant (Sonnet by default, ASSISTANT_MODEL switches) with 12 tools over the store's own functions: search, product, show, similar, recommendations, compatibility check, add-ons, rental search and availability, stage plot readiness, basket add and view. The shopper, faders, ears and basket come from cookies.
  • MCP server: /api/mcp with 17 tools: search, show, get and similar products, recommendations, check compatibility, suggest add-ons, search rentals, rental availability, book rental, stage plot readiness, add to basket, update basket line, view basket, checkout, and the signed-in whoami and my_orders. Demo OAuth 2.1 with stateless signed tokens, where signing in picks a demo customer, so rankings use their taste and their price list. An MCP Apps resource draws the cards; /mcp/{view,buy,cart} hand a basket over to the store.
  • Semantic data: JSON-LD Organization, WebSite, BreadcrumbList and Product or ProductGroup with one Offer per variant (GTIN, MPN, price including VAT), a Markdown twin of every page (.md or Accept: text/markdown), llms.txt, Open Graph images per page, hreflang en/nb/sv. Noindex everywhere (X-Robots-Tag and robots meta) behind one SITE_INDEXABLE switch; robots.txt never disallows, and the sitemap is generated but not advertised.
  • Env: CRYSTALLIZE_TENANT_IDENTIFIER, CRYSTALLIZE_ACCESS_TOKEN_ID, CRYSTALLIZE_ACCESS_TOKEN_SECRET, NEXT_PUBLIC_SITE_URL, SITE_INDEXABLE; for the assistant ANTHROPIC_API_KEY (and optional ASSISTANT_MODEL); for the MCP sign-in MCP_AUTH_SECRET (optional MCP_SITE_URL).

Build my design, not a demo's: my typefaces, colours and tone, with pages that suit my products. Show me the home page, a category and a product page early, and adjust the design with me before building the rest.

Every page is built for search engines, answer engines and AI agents from the start, not added at the end:

  • SEO: server-rendered HTML, one <h1>, a unique title and description, canonical URLs, hreflang per language, a sitemap and robots.txt, and clean, translated paths.
  • Structured data: JSON-LD on every page that has a subject: Organization and WebSite (with a SearchAction) on the home page, Product with Offer (price, currency, availability) on product pages, BreadcrumbList on categories and products, Article or Recipe on content. Generate it from the same data as the page.
  • GEO, for answer engines and agents: /llms.txt (an H1, a summary, links to every section), /llms-full.txt, and a Markdown twin of every page (its URL plus .md, or Accept: text/markdown), with prices, stock and facts written out in plain sentences.
  • Agents can act, not only read: register the store's actions (search, add to cart, check availability) with WebMCP (navigator.modelContext.registerTool, or annotated forms), and keep the accessibility tree clean: semantic HTML, labelled controls, real buttons and links.
  • Fast and stable: responsive images from Crystallize, no layout shift (reserve space for images and late content), little client JavaScript. Aim for 100 in every Lighthouse category (Performance, Accessibility, Best Practices, SEO; heavy 3D or video pages may score lower on performance) and pass every Agentic Browsing check.

Step 6: run it, then ship it

Run it locally and walk me through each feature above with my own data. Fix what I find. Before you call it done, run Lighthouse on the home page, a category and a product page (npx lighthouse <url> --only-categories=performance,accessibility,best-practices,seo,agentic-browsing), validate the JSON-LD (https://validator.schema.org), open /llms.txt and a page's .md twin, and fix what falls short. Deploy only when I ask: set the same environment variables on the host, point my domain, and give me the live URL.

Watch out for

  • upsertVocabulary is a full replace and vocabularies can't be deleted: approve names and dimensions before the first write. setItemTaste calls for one item must run in sequence (parallel calls lose writes); check variant components afterwards, then publish and ignite.
  • Discovery answers HTTP 404 "There is no ignited Tenant" (not GraphQL) until the first igniteDiscoApi(stacks: opensearch). A new shape (banners) needs another ignite.
  • searchable, sortable, facetable and filterable are rejected by this Core API: drop unknown config keys, and check TenantRankByField after the ignite before ranking on a field.
  • Discovery serves margin and trade-tier prices. Keep it restricted and read it on the server; ranking that runs in the browser needs a separate public view without those fields.
  • Topic.translations lists only the other languages: take the queried language's name from the topic itself. A document with components in a language but no name in it publishes as MISSING_NAME_FOR_LANGUAGE, even when the name is the same everywhere.
  • copyRemoteAsset returns before the image exists, and fails without a Content-Length: read the task's info.error, then upload through a presigned request. Some CDNs answer 403 to a spoofed browser User-Agent; check that a copy isn't an HTML error page.
  • Published reads lag a bulk publish by minutes. The Shop API create returned ids for orders that never appeared in the customer's list: log every id and check after a wait. Orders go through the Shop API only, and it can't delete them.
  • Set the cart's customer before bookSkuItem; a plain addSkuItem of a rental SKU reserves nothing. Confirm bookings again once the order exists. Inside the cancellation window cancelReservation refuses: re-hydrate without the line.
  • Price lists targeted at customer groups fail: target markets or customer identifiers, with negative percentages on every price variant. Markets aren't validated, so a typo never matches.
  • Unset switches read false: treat false as "not stated" in JSON-LD, the Markdown twin and the agents. One unit per numeric (range filters ignore units): convert 25.5 inch to mm before filtering.
  • Sound clips: publish only the rendered audio, credit every creator, and get permission first.
  • Don't invent facts about my business (prices, stock, certifications, delivery promises). Ask, or leave a clearly marked placeholder.

And for every Crystallize store, from the skills:

  • Orders: create and change them through the Shop API /order (createFromCart, create, setMeta with merge: true, addToStage, setPayments). Editing an order in Core adds a duplicate to the Shop API's list. Read a customer's orders with the identifier from the session, limit: 100, grouped by coreId (keep the newest). Seed order history through /order create, not Core registerOrder. The order id is the cart id; don't call fulfill after createFromCart.
  • Payments: create the order from the payment provider's verified webhook, never from the browser, once per cart.
  • Cart meta goes in hydrate(input: { meta }); hydrate is the whole cart, so send every line each time.
  • Images: serve them straight from Crystallize (not through an image optimizer such as next/image in its default setup): a WebP srcset from the returned variants with an accurate sizes, falling back to the original URL while renditions are missing. Replace an image by uploading a new one, not with registerImageRevision.
  • Ranking (if the store ranks per shopper): check that __type(name: "RankByInput") exists; pass context as a variable, with userTaste entries of { vocabulary, weights, magnitude } (magnitude = the square root of the sum of squared weights); tieBreaker is required; don't combine sorting with ranking, and page with skip and limit inside the rerank window; introspect TenantRankByField for field names; leave context out when there's no taste; use explain: true only for tuning.
  • Bookings (if the store books): durations are in seconds; the role needs the bookingPolicies permission; put the customer on the cart before bookSkuItem; every hydrate must resend each booked line with its window and unit, or the booking is cancelled; remove a booking by re-hydrating without it.

Done when

  • My tenant has the content model above with my products, prices and images in it.
  • The storefront runs on my domain in my brand, and every feature I chose works with my data: we have clicked through each one together.
  • Lighthouse scores close to 100 in every category and every Agentic Browsing check passes on the home, category and product pages.
  • I know how to add a product, change a price and publish, in the Crystallize App.