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 (2–40 chars, lowercase letters/digits/dashes), name (max 100 chars), semver version.
• Ownership — the slug isn't owned by another account, and the version hasn't already been released.
• Structure — layouts/app.twig and pages.twig must exist. Each config/*.json file (settings_schema.json, blocks.json, templates.json, menu.json) must be valid JSON; missing ones are warnings (defaults will be empty).
• Twig — every .twig file is linted against the platform's templating surface. Syntax errors and unknown functions/filters are reported with file and line number.
• Quality (warnings) — a thumbnail.(jpg|png|webp) for the store listing (at the theme root or in assets/), and a lang/en.json so storefront strings don't fall back to raw keys.

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 — it shows each version's 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.

Approved and rejected versions are immutable. Bump version in theme.json and push again; drafts can be re-pushed freely while you iterate.

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

Installed sites keep their own editable copy of your files, pinned to the version they installed. 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.

Either way, moving to a new version Files a host has not overridden pick up the new version automatically; files they've customised 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, thumbnail, previews, and an author so it presents well in the marketplace.

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 layouts/ 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.
• [ ] layouts/app.twig and pages.twig present; templates extend a layout.
• [ ] config/settings_schema.json declared for anything hosts should customise.
• [ ] Assets in assets/css/, assets/js/, assets/images/, assets/fonts/, referenced via theme_asset() by their inner path.
• [ ] thumbnail.(jpg|png|webp) (root or assets/) and lang/en.json included.
• [ ] stayblox theme validate passes with no errors.
• [ ] Version bumped in theme.json for each release.