Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt

Use this file to discover all available pages before exploring further.

This is the long version of Build and Customize a Theme with AI. The reference page tells you what’s possible. This page walks you through one concrete change from start to finish, so you can copy the rhythm and apply it to your own ideas. The example: add a testimonials section to the homepage of a brand-new Shoppex shop, using Claude Code as the AI. The same flow works with Codex, Cursor, or any MCP-capable client — the prompts and the result are similar.

​
The fastest way: Edit with AI from the dashboard

Before you read on — Shoppex has a one-click Edit with AI flow that does steps 1-3 below (API key, install CLI, install MCP server) automatically. To use it:
  1. Open the Shoppex dashboard → Store → Themes.
  2. On any theme card, open the ⋯ (more) menu and click Edit with AI.
  3. In the dialog, pick your AI client — Cursor, Claude Code, Claude Desktop, Codex, or Windsurf.
  4. The dialog generates a scoped, expiring API key and shows you the exact commands to run in your terminal: install the CLI, log it in, install the Shoppex MCP server, and clone the theme locally. Copy and paste each block.
  5. Once the commands finish, your AI client has the theme tools wired in. Skip to Step 4 — Verify and inspect below.
You can revoke the generated key at any time from the same dialog — and the dialog shows an audit log of every action the AI takes. If you’d rather wire things up yourself (e.g. you already have a long-lived API key, or you’re scripting this for multiple shops), follow the manual steps below.

​
What you’ll need (manual path)

  • A Shoppex shop. If you don’t have one yet, do Quickstart first. The whole flow works on the default yourshop.shoppex.io URL — no custom domain required.
  • Claude Code installed locally. Free tier is fine for following this guide.
  • About 30 minutes.
You don’t need Node, you don’t need to clone anything, you don’t need to know React. Claude Code talks to Shoppex over an MCP server you’ll install in step 3.

​
Step 1 — Create an API key for the AI

In your Shoppex dashboard:
  1. Open Settings → Developer → API Keys and click Create Key.
  2. Pick scopes: themes.read and themes.write. Nothing else.
  3. Copy the key (shx_...). You’ll need it in a moment — keep it close.
The key gives the AI permission to inspect and modify themes on this shop, but nothing else. It can’t read orders, change settings, or move money.

​
Step 2 — Install Claude Code

If you haven’t used Claude Code before, install it from claude.com/claude-code — the CLI installer is: 
curl -fsSL https://claude.ai/install.sh | bash
After install, run claude in your terminal. You’ll get a chat prompt waiting for your first message.

​
Step 3 — Install the Shoppex MCP server

This is the step that gives Claude Code access to Shoppex’s theme tools. From any terminal: 
npx @shoppexio/mcp-shoppex install --client claude-code --api-key shx_your_key_here
The installer writes the MCP config to the right location for Claude Code automatically. Restart claude so it picks up the new tools. (If you’re on Cursor or another MCP-capable client, swap --client claude-code for the equivalent — see the package’s README for the full list.)

​
Step 4 — Verify and inspect

In Claude Code, paste:
Inspect my Shoppex theme so we know what we’re starting from.
Claude Code uses the theme_inspect MCP tool to fetch your theme structure — sections, pages, settings, the current file tree. After a few seconds you should see Claude summarize your theme. If you get “no Shoppex tools available”, the MCP server didn’t load. Re-run the install command, restart Claude Code, and try again.

​
Step 5 — Describe the change you want

Be specific. Vague prompts give vague edits. For our testimonials example:
Add a testimonials section to the homepage. Three testimonial cards in a row on desktop, stacked on mobile. Each card has a quote, the author’s name, and their role. Use the same visual style as the existing feature section — same border treatment, same spacing. Pull placeholder copy from common SaaS testimonials for now; we’ll replace with real ones later.
Claude Code will plan the change — usually it tells you what files it needs to create or modify before doing anything.

​
Step 6 — Apply and preview

The right workflow is preview first, publish later. Tell Claude Code:
Apply this change and start a preview so I can see it before publishing.
Claude Code calls theme_apply followed by theme_preview. After a moment you’ll get a preview URL on preview.shoppex.io. Open it in your browser. Your real shop on yourshop.shoppex.io is untouched — this is a sandboxed render.

​
Step 7 — Iterate on the preview

The preview is where most of the work happens. Look at the result, give Claude Code feedback:
The cards are too close together on desktop. Add more horizontal spacing between them — at least 24 pixels.
Claude Code edits, re-applies, the preview updates. Refresh in your browser. Iterate as many times as you need. Each round is fast — usually under a minute. Don’t worry about “wasting” iterations; the preview is free.

​
Step 8 — Publish

When it looks right:
This is good. Publish the change to my live theme.
Claude Code calls theme_publish. The publish queues a deploy job that rebuilds the theme and rolls out to your live shop — usually under a minute for small changes, longer for broader edits. Buyers see the testimonials section the next time they load the page.

​
Step 9 — Roll back if needed

If you publish a major change and then realize something’s wrong, you can roll back to a previous backup. Backups are created at theme version upgrades and at official-theme restores (not at every publish — for normal small edits, your safety net is the preview step before publish, not rollback after). If a backup is available:
Roll back to the previous backup.
Claude Code calls theme_rollback. The rollback runs through the same deploy pipeline as a publish — usually about the same wait.

​
What just happened technically

Underneath the chat, Claude Code used Shoppex’s MCP theme tools:
  • theme_inspect — read your current theme’s structure.
  • theme_apply — staged a new version with your testimonial section.
  • theme_preview — created a sandboxed render on preview.shoppex.io.
  • theme_publish — queued a deploy of the staged version to your live shop.
  • theme_rollback — would restore a backup on demand.
These map to the HTTP endpoints under POST /dev/v1/themes/:id/control/*. See Theme API Reference under the Themes group when you want to build your own automation.

​
Bigger changes

The flow scales. Once you’re comfortable with the inspect → apply → preview → publish loop, you can do much more:
  • New page — “Add an /about page with our team and company story.” Claude Code adds the route, creates the template, and you preview before going live.
  • Full theme port — “Use this Figma frame as a reference, rebuild my entire storefront from it.” Heavier (multi-hour, more back-and-forth), but it works when you can describe or paste reference visuals.
  • Theme version upgrades — pull the latest version of a base theme into your customized one, with Claude Code reconciling the diff. Theme upgrades are also when backups are automatically created.
The key habit: one focused change per iteration, preview every time, publish only when you’re sure. This applies whether you’re doing a 5-minute copy tweak or a multi-day rebuild.

​
Common pitfalls

  • Prompts that are too broad. “Make the storefront look more modern” gives Claude Code too much room — you’ll get something it considers modern, which might not be what you meant. Always reference specific elements (“the hero”, “the feature cards”) and concrete attributes (“more spacing”, “darker background”, “smaller heading”).
  • Skipping preview. Tempting on small changes, dangerous on bigger ones. The preview is also your safety net before publish — for everyday edits, there is no automatic backup to roll back to.
  • Editing the live theme directly via the dashboard while a Claude Code session is open. You’ll get a 409 conflict on the next theme_apply because the dashboard incremented the revision. Pick one or the other for any given task.
  • No Shoppex tools in Claude Code. Means the MCP server didn’t load. Re-run the install command (step 3) and restart claude.

Reference: Theme workflow

All the theme-engine endpoints, settings, and edge cases.