Publishing

There are two ways a theme gets onto a storefront, for two different audiences:

You are…	You want…	Use
A designer selling to hosts	A public theme in the marketplace	The Stayblox CLI: validate, push, submit for review
A host (or their developer)	A custom theme for your own storefront	The zip upload in your admin. No review, private to your site.

Publish to the marketplace (CLI)

Marketplace themes are published with the Stayblox CLI from a theme directory containing a theme.json manifest:

stayblox theme validate          # check the package, publish nothing
stayblox theme push              # publish a draft version
stayblox theme push --submit     # publish and submit for review in one go

push creates (or updates) a draft version of your theme. Drafts are completely private: the theme doesn't appear in the marketplace and its assets live in a private bucket until a version is approved.

What validation checks

Both validate and push run the same server-side validation and return a structured report. Errors block publishing; warnings don't, but fix them before submitting:

• Manifest: theme.json present and valid. slug is 2–40 chars of lowercase letters, digits, and dashes, starting and ending with a letter or digit; name is max 100 chars; version is strict semver (X.Y.Z).
• Ownership: the slug isn't owned by another account, and the version hasn't already been released.
• Structure: layout/theme.liquid must exist. Each config/*.json file (settings_schema.json, settings_data.json, menu.json, pages.json) must be valid JSON when present; missing ones are warnings (defaults will be empty). In config/pages.json, an entry's key must be one of blog, blog-post, or contact (a reserved page), and can't be combined with slug or is_home; see Templating → reserved pages.
• GraphQL: if your package includes any graphql/*.graphql files, each operation in them is validated against the live storefront schema. Every operation must be named and unique across your files, and query depth/complexity limits are enforced (a violation blocks publishing). Errors are reported with file and message.
• Quality: a locales/en.json so storefront strings don't fall back to raw keys (a warning if missing).

The package carries no screenshots. Store previews are captured automatically from your live demo URL; an optional thumbnail.(webp|jpg|jpeg|png) at the theme root or in assets/ overrides the marketplace listing card image. See Store previews.

Review

Submitting (push --submit, or stayblox theme push followed by a later submit) moves the draft into the review queue. Each version moves through:

draft  →  pending review  →  approved   (live in the marketplace)
                          →  rejected   (read the review notes, fix, bump, re-push)

Check where things stand with stayblox theme versions (or stayblox theme version 1.2.0 for one version's full report); both show status, validation report, and any review notes. On approval the version's assets are promoted to the public bucket and the theme becomes visible (and installable) in the marketplace.

When a review lands you're notified by email and in the bell of your partner dashboard, and a rejection includes the reviewer's notes.

Approved and rejected versions are immutable. Bump version in theme.json and push again; drafts can be re-pushed freely while you iterate. Drafts you abandon can be deleted (stayblox theme delete <version>); drafts untouched for 90 days are cleaned up automatically.

Your partner dashboard

Your account panel (where you manage your partner account) has a Themes section listing everything you've published: per-theme version history with status badges, validation reports, and review notes, plus actions to submit a draft for review or delete it. It's also where you manage the marketplace listing: name, description, demo URL, industries, and pricing. The slug and version always come from theme.json; the dashboard never changes code.

Versioning

Each release has:

• a human version name, the semver string from theme.json (e.g. 1.2.0), and
• a monotonically increasing version code, assigned by the platform, used to decide what's newer.

How updates reach hosts

Each install is pinned to the version the host installed, with any files the host edited stored as per-site overrides. When a newer version is approved (higher version code), what happens depends on each install's auto-update setting:

• Auto-update on: the install moves to the new version immediately when it's approved. Hosts toggle this per theme in their admin's theme library.
• Auto-update off (the default): Stayblox flags an update for the install; the host applies it when they choose.

Moving to a new version works the same either way: files the host has not overridden resolve to the new version automatically, while customised files keep their overrides until reset. See Theme structure → file resolution.

Marketplace listing

Approved themes appear in the public marketplace, filterable by industry, price, and search, with previews and author info. The public listing is served from:

GET /public/themes            # list (search, industry, price, sort, per_page)
GET /public/themes/{slug}     # single theme with previews + authors

Give your theme a clear name, description, and demo URL in your partner dashboard so it presents well in the marketplace. Desktop and mobile previews are captured automatically from the demo URL; see Store previews.

Upload a custom theme (zip)

Hosts who want a bespoke theme for their own storefront don't go through the marketplace at all. In your admin, go to Themes → Manage themes → Upload theme and upload a .zip of the theme directory:

cd my-theme
zip -r ../my-theme.zip .

• The same theme.json contract applies: the theme's slug, name, and version are read from the manifest, and the upload is rejected if it's missing or invalid.
• Beyond the manifest, the only structural requirement is a layout/ directory at the archive root; there is no review step.
• The theme is private to your site: editable in the code editor, never listed in the marketplace.

Theme designers use this same upload on a development site to preview work-in-progress before pushing it with the CLI.

Checklist (marketplace)

• [ ] theme.json with slug, name, semver version.
• [ ] layout/theme.liquid present; page views render into it via content_for_layout.
• [ ] config/settings_schema.json declared for anything hosts should customise.
• [ ] CSS/JS assets in assets/css/, assets/js/, referenced at their /assets/… path. (Binary assets, images and fonts, aren't served from the theme package yet; see Assets.)
• [ ] locales/en.json included; optional thumbnail.(webp|jpg|jpeg|png) at the root or in assets/.
• [ ] Demo URL set in your partner dashboard so marketplace previews can be captured.
• [ ] stayblox theme validate passes with no errors.
• [ ] Version bumped in theme.json for each release.