Skip to main content
Shoppex AI tooling works with the same structured theme document as the visual Builder. The assistant does not edit or upload executable theme code. A useful loop is:

​
Connect your AI client

  • Choose the theme you want to edit in Store → Themes.
  • Open its ⋯ menu and select Edit with AI.
  • Create a scoped key for that theme and follow the generated setup commands for your AI client.
The handoff also gives read-only CLI commands for the current document and schema. Use them for inspection. Use the MCP tools below for revision-gated saves and publishing.
Give the assistant a scoped API key. Review the saved change before publishing, especially when it affects product purchase or checkout handoff UI. Preview stays a dashboard action. Publish through the MCP tool with the exact revision returned by the save, or publish the reviewed draft in the dashboard.

​
Two provenance workflows

The handoff response tells the assistant which workflow to use, through document_provenance, mcp_tools, and instructions:
  • settings_derived is the normal workflow for hosted themes. The assistant edits Builder settings, through theme_settings_get and theme_settings_update.
  • document_authoritative is used for ThemeDocument imports and rebuilds. The assistant edits the complete saved ThemeDocument, through get_theme_document and save_theme_document.
Both workflows publish through publish_theme_document. The tool description repeats this mapping. The assistant must follow the provenance instead of trying the document save flow for every theme.

​
Make a focused change

Ask the assistant to inspect the theme before editing:
Good tasks are narrow and observable, for example:
  • “Change the homepage hero heading and keep the existing buttons.”
  • “Add an FAQ block after the product grid.”
  • “Use the current primary color for collection-card links.”
The assistant must read the current schema and the provenance-specific source, identify the target block, and apply a structured change. Ask it to list the exact fields it changed before saving.

​
Save a settings-derived hosted theme

For settings_derived themes, the assistant must:
  1. Call theme_settings_get and change the returned Builder settings.
  2. Call theme_settings_update with the changed settings and the revision from the read unchanged. The tool increments the revision for the update.
  3. Review the saved result and keep the Builder revision returned by the update.
  4. Call publish_theme_document with that Builder revision as expected_revision.
Do not call save_theme_document for a settings_derived theme. That workflow intentionally returns 409 because Builder settings are the source of truth.

​
Save a document-authoritative theme

For a document_authoritative import or rebuild, the assistant must:
  1. Call get_theme_document and change the complete ThemeDocument it returns.
  2. Call save_theme_document with the read revision as expected_revision.
  3. Review the saved result and keep the new ThemeDocument revision returned by the save.
  4. Call publish_theme_document with that new revision as expected_revision.
In both workflows, publishing validates the result and creates a new locked serving revision. Before publishing, review the saved result in the visual Builder on desktop and mobile, especially purchase and checkout handoff UI.
If another editor saves the theme first, Shoppex returns a revision conflict instead of overwriting your change. Load the current source again: Builder settings for settings_derived, or the ThemeDocument for document_authoritative. Apply your change to it again, then save. Never overwrite the other editor’s change.

​
Good follow-up prompts

  • “Add an FAQ block after the product grid, using the existing spacing.”
  • “Use the current primary color for collection-card links.”
  • “List the exact settings you changed and the saved revision without publishing.”