Submitting a theme

The CLI

The Quickmerce CLI (qm) drives the full lifecycle - scaffold, preview, validate, submit.


# scaffold a new theme
qm theme init my-theme
 
# local preview loop against sample-data
qm theme dev
 
# validate against the theme contract
qm theme validate
 
# build the bundle and submit it for review
qm theme submit

`qm theme validate`

Runs the same three automated checks the server gate runs, so you catch those problems before submitting:

Parser / contract - theme.json, config/settings_schema.json and every templates/*.json parse as JSON; every {% schema %} block parses as JSON; sample-data/shop.json exists and declares a string name and currency; sample-data/ is within its size caps.
Preview render - all seven preview templates (index, product, collection, search, page, wishlist, 404) render to non-empty HTML.
Security scan - no disallowed Liquid/JS constructs, no external <script src>, no oversized .liquid file.

What validate does NOT check. Safe default links, “every user-facing string is a schema setting”, the white-label rule and responsiveness at 1440 / 768 / 375 px are all real requirements a human reviewer enforces - but no tool checks them for you. Passing qm theme validate means the automated gate will pass; it does not mean review will. Read Sections & settings and Navigation and check those yourself.

`qm theme submit`

Builds your bundle, uploads the artifact, and opens a review request. You are notified by email as the submission moves through review.

The dev portal

The developer portal is where you manage your identity and listings:

Your developer profile (name, email - where review notifications are sent).
Your themes and their versions.
Submission status and reviewer feedback for each version.

Verify your email before you submit

Registration sends you a verification email. Until you click that link you cannot submit a theme - POST /marketplace/themes/submit answers 403 Verify your email before submitting a theme, and the portal’s Submit button stays disabled. Registering, logging in and browsing all work unverified; only submission is gated.

If the email never arrives, log in and use Resend verification email on the portal’s verify page. That action reports a real failure rather than silently claiming success, so if it errors the mail genuinely did not go out.

Your theme’s slug comes from `theme.json#name`

The marketplace slug is your name lower-cased with every run of non-alphanumeric characters replaced by a hyphen - "Vesper Noir" becomes vesper-noir. Consequences worth knowing before your first submission:

The slug is the public URL of your listing and the prefix of every asset path.
The first author to submit a given slug owns it. Another developer submitting a theme whose name resolves to the same slug is rejected with 409 Theme slug "<slug>" belongs to another author.
Renaming your theme after launch changes its slug, so it lands as a new listing rather than an update to the existing one. Pick the name deliberately.

The review process

Every submission goes through two stages.

1. Automated gate

On submit, an automated gate runs and records its result:

Parser / contract validation - the bundle parses and satisfies the theme contract.
Preview render audit - each template renders over the sample data across pages at 1440 / 768 / 375 px.
Security scan - no unsafe Liquid constructs, no disallowed tags, no oversized fixtures.

If the gate fails, the submission returns to you with the failure detail - no human review happens until it passes. Fix and re-submit.

2. Human review

A passing submission enters the review queue. A reviewer sees the automated gate result, the embedded live preview, and the version diff, then approves, requests changes, or rejects.

On approval, your version is published to the catalog and merchants can install it.

Versioning & updates

Each install pins a specific version. Publishing a new version does not touch live stores.
When you publish an update, merchants on an older version are notified and choose when to update.
A bad version therefore can’t instantly break installed storefronts - the merchant is always in control of when they move.

Bump theme.json#version (semver) on every meaningful change, and include a changelog with each submission.