Themes

Toolset storefront_theme, 16 tools.

RecordsCopy Anchor Link

themeCopy Anchor Link

A storefront theme of the store: the active one shoppers see and the others the merchant keeps, each with its publish state. Customizer tools take a theme_id and default to the active theme.

• Permission: theme.read
• Tools: theme_list, theme_get

Filters on the list:

theme_catalogCopy Anchor Link

A theme the store can install from the theme store, with its versions and whether it is installed. Install one with theme_install.

• Permission: theme.read
• Tools: theme_catalog_list, theme_catalog_get

ActionsCopy Anchor Link

theme_build_cancelCopy Anchor Link

Withdraw a theme publish whose build has not finished; the live store stays as it is.

• Action key: theme_build.cancel
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "build_id": "019bb74b-3c3b-76a7-a006-7bcb92c30046"
}

theme_build_getCopy Anchor Link

Where a theme publish stands: one build and its log, or the live and current builds.

Where a theme publish stands. With build_id: that build (state queued, building, succeeded, failed, superseded or canceled; error_code and error_message when it failed) and the end of its build log. Without: the live build and the current one. A failed build leaves the live store unchanged.

• Action key: theme_build.get
• Permission: theme.read
• Approval: Runs without approval.
• Effect: Reads only.
• Retries: safe to repeat with the same input.

Example input:

{
  "build_id": "019bb74b-3c3b-76a7-a006-7bcb92c30046"
}

theme_build_retryCopy Anchor Link

Ask again for a theme publish whose build failed.

• Action key: theme_build.retry
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "build_id": "019bb74b-3c3b-76a7-a006-7bcb92c30046"
}

theme_createCopy Anchor Link

Create a new theme from the starter theme; the live theme stays as it is.

• Action key: theme.create
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "name": "Autumn look"
}

theme_deleteCopy Anchor Link

Delete a theme the store does not show; the active theme cannot be deleted.

• Action key: theme.delete
• Permission: theme.write
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Destructive: in compact mode it runs with run_destructive_action.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe"
}

theme_duplicateCopy Anchor Link

Copy a theme with its draft into a new theme, for larger experiments.

• Action key: theme.duplicate
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "name": "Autumn look (copy)"
}

theme_installCopy Anchor Link

Install a theme store theme as a new theme. With update_from it prepares an update of that theme instead: a candidate beside the live version that the merchant reviews and publishes, so nothing live changes and the assistant never publishes it. The summary, in the merchant's language, says what the merchant's work carried over to (unpublished draft changes included), what could not, which code files wait for review, and in review_at the admin page where the merchant reviews and publishes it. With fresh, or where an update cannot be prepared on the theme itself, it installs a clean copy beside the theme instead.

• Action key: theme.install
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "name": "aurora",
  "version": "1.4.0"
}

theme_publishCopy Anchor Link

Make the theme draft live for shoppers once its build succeeds.

Publish the theme draft; a theme that is not live becomes the live one. Makes draft changes live for customers once its build succeeds; build_id names that build, which theme_build_get follows. Always asks the merchant, whose approval shows the theme by name, the changed file paths, the draft preview link and the network hosts in confirm_network_hosts (* reads as any public host). Over an API or MCP connection a publish that changes theme code is refused for now.

• Action key: theme.publish
• Permission: theme.publish
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Destructive: in compact mode it runs with run_destructive_action.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{}

theme_revision_listCopy Anchor Link

The theme's saved versions, newest first, with the live one marked.

List theme revisions, newest first. is_publish marks a publish attempt: went_live_at is set once it went live, last_build is its newest build (state, and error_code when it failed), and live_revision_id is the revision live now. draft_has_unsaved_edits true: the latest edits are only in the draft, so rolling back to the newest revision undoes them.

• Action key: theme_revision.list
• Permission: theme.read
• Approval: Runs without approval.
• Effect: Reads only.
• Retries: safe to repeat with the same input.

Example input:

{
  "limit": 10
}

theme_switchCopy Anchor Link

Make a saved version of a theme the one shoppers see: the way to go live with another theme or roll the live store back.

• Action key: theme.switch
• Permission: theme.publish
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Destructive: in compact mode it runs with run_destructive_action.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "revision_id": "019bb77a-30fc-73e0-a0e9-4af113113214"
}

theme_updateCopy Anchor Link

Rename a theme, change its description or preview image, or archive it.

• Action key: theme.update
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "name": "Autumn look"
}

theme_update_statusCopy Anchor Link

Where a theme update stands and where the merchant reviews and publishes it. The assistant never publishes or undoes an update.

The newest theme update of a theme, the open one first: its status in the merchant's language, the dates of your version and of the update (never a version number), how big a change it is, the code files that wait for the merchant's review, how many pages the before and after pictures cover, and the admin page where the merchant reviews and publishes it. Updates are published and undone only by the merchant on that page.

• Action key: theme_update.status
• Permission: theme.read
• Approval: Runs without approval.
• Effect: Reads only.
• Retries: safe to repeat with the same input.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe"
}