Skip to main content

​
Hosted Theme Sync

Use this workflow when you want to edit a real Shoppex-hosted Liquid theme locally. The loop is: 
API key -> pull -> theme dev -> push -> preview -> publish

​
What You Need

  • Shoppex CLI
  • a Shoppex API key with themes.read and themes.write

​
Step 1: Create A Theme Development Key

In the Shoppex dashboard:
  1. Open Settings -> Developer
  2. Open API Keys
  3. Click Create API Key
  4. Choose the Theme Development preset
  5. Copy the secret immediately
The key can inspect and update theme source. It does not need payment, order, customer, or product write scopes.

​
Step 2: Login

npx @shoppexio/cli auth login --api-key shx_your_key

​
Step 3: Pull Source

shoppex theme list
shoppex theme pull --theme 11111111-1111-4111-8111-111111111111 --out ./my-theme
cd ./my-theme
The pulled folder contains .shoppex/theme.json. That file links the local folder to the remote theme id and source revision.

​
Step 4: Run Local Liquid Preview

shoppex theme dev
This starts the Liquid dev server for the pulled package. It requires theme-package.json. Use live shop data instead of fixtures: 
shoppex theme dev --shop-slug my-shop --no-msw

​
Step 5: Push Draft Source

shoppex theme push
What push does:
  • uploads the full local source snapshot
  • replaces the remote draft source
  • deletes remote draft files that you deleted locally
  • validates the draft
  • never publishes automatically
Start a preview immediately after a successful push: 
shoppex theme push --preview

​
Step 6: Preview And Publish

shoppex theme preview
shoppex theme publish
Publish creates a server-Liquid artifact and activates it for the storefront unless you pass a build-only option.

​
Revision Mismatch

If someone changed the remote draft after your last pull, push stops with a revision mismatch. Safe fix: 
shoppex theme pull --force
Only force push when you intentionally want to replace newer remote changes: 
shoppex theme push --force

shoppex theme pull --theme 11111111-1111-4111-8111-111111111111 --out ./my-theme
cd ./my-theme
shoppex theme dev
shoppex theme push --preview
shoppex theme publish

​
Next Steps

Local Development

Fixture data, live shop data, and local validation.

Editing Themes

Dashboard, CLI, Dev API, and MCP workflow.