> ## 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.

# Customize your theme with AI

> A step-by-step walkthrough — from "fresh shop" to "live theme change" using Claude Code.

This is the long version of [Build and Customize a Theme with AI](/themes/build-and-customize-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.

<Info>
  AI editing works on **custom code themes** — Liquid theme packages you forked from a base
  theme or imported. If your shop is still on a visually-built hosted theme, the **Edit with
  AI** flow forks it into an editable custom copy for you.
</Info>

## 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](https://dashboard.shoppex.io) → **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](#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](/merchants/start/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 Liquid.
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](https://claude.com/claude-code) — the CLI installer is:

```bash theme={"system"}
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:

```bash theme={"system"}
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 Liquid theme structure —
sections, snippets, pages, settings, and 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 validates the Liquid source package, builds a
new immutable live version, and rolls it 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 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 Liquid 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` — published the staged Liquid source package 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](/api-reference/introduction) 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 page template/section wiring, 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`.

<Card title="Reference: Theme workflow" href="/themes/build-and-customize-with-ai">
  All the theme-engine endpoints, settings, and edge cases.
</Card>