Skip to main content

​
Hosted Theme Sync

This workflow applies to custom code themes (forked or imported Liquid packages) hosted on Shoppex.
Use this workflow when you want to edit your Liquid custom theme locally. The loop is:

​
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

​
Step 3: Pull Source

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

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

​
Step 5: Push Draft Source

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:

​
Step 6: Preview And Publish

Publish builds a new immutable live version 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:
Only force push when you intentionally want to replace newer remote changes:

​
Next Steps

Local Development

Fixture data, live shop data, and local validation.

Editing Themes

Dashboard, CLI, Dev API, and MCP workflow.