API reference

The public, unauthenticated endpoints third-party tooling can use. All live off the API base under /public/*, so no store context is required.

Base URL is environment-driven. In production it is the platform API host; your CLI resolves it automatically.

`GET /public/themes`

The bundle-derived theme catalog. Returns the available themes with their listing metadata (name, tagline, description, tags, preview image, screenshots).


GET /public/themes
Cache-Control: public, max-age=300

Response: an array of theme listings.

`GET /public/marketplace/themes`

The marketplace catalog - the one the public marketplace site renders. Only PUBLISHED listings, ordered by name.


GET /public/marketplace/themes
GET /public/marketplace/themes/:slug
Cache-Control: public, max-age=120

Each entry:

Field	Type	Notes
`id`, `slug`, `name`	string
`tagline`, `description`, `category`	string \| null
`tags`	string[]
`premium`	boolean	Paid listing.
`pricePaise`	number \| null	Null or 0 means free.
`previewImage`	string \| null	Resolved to a full public URL.
`screenshots`	string[]	Resolved full URLs.
`authorName`	string
`authorType`	`FIRST_PARTY` \| `THIRD_PARTY`	First-party listings are badged Official.
`verified`	boolean	The live version passed human review. Always true for first-party.
`verifiedAt`	string \| null	When the live version was approved.
`currentVersion`	string \| null

`GET /public/themes/:slug/preview/:template`

Renders a template from a theme over its bundled dummy sample-data/*.json - no tenant, no database, no customer data. Returns text/html.


GET /public/themes/:slug/preview/:template?version=1.0.0

Param	In	Notes
`slug`	path	The theme slug.
`template`	path	`index`, `product`, `collection`, `search`, `page`, `wishlist`, `404`, …
`version`	query	Optional. Pins a published version; omit for latest.

The preview’s bundle assets are served from /assets/:slug/:version/* - the exact path the asset_url filter emits - so the rendered HTML is fully styled.

See Preview & sample data for the fixture shapes.

Developer endpoints

These are the endpoints the developer portal and the qm CLI call. Use them directly if you want to submit from your own CI.

`POST /marketplace/authors/register`


POST /marketplace/authors/register
Content-Type: application/json
 
{ "email": "you@studio.com", "name": "Your Studio", "password": "min 8 chars" }

Returns { token, apiToken, author }. token is a 12-hour session JWT; apiToken (qmt_…) is long-lived and is what you put in CI. Registering sends a welcome email and a verification email. An email already registered → 409.

`POST /marketplace/authors/login`


POST /marketplace/authors/login
{ "email": "you@studio.com", "password": "…" }

Returns { token, author }.

`POST /marketplace/authors/verify`


POST /marketplace/authors/verify
{ "token": "<the token from your verification email link>" }

The portal’s /verify?token=… page calls this for you. An invalid or already-used token → 400.

`POST /marketplace/authors/resend-verification`

Requires auth. Regenerates the token and resends. Returns 503 if the mail provider rejected the send, so a success response means the mail really went out.

`POST /marketplace/themes/submit`

Requires auth, and requires a verified email - otherwise 403 Verify your email before submitting a theme.

Two request shapes:


POST /marketplace/themes/submit
Authorization: Bearer <token or apiToken>
Content-Type: multipart/form-data
 
bundle=@my-theme.zip          # form field MUST be named "bundle", max 25 MB


POST /marketplace/themes/submit
Authorization: Bearer <token or apiToken>
Content-Type: application/json
 
{ "stagingBundleS3Key": "submissions/<authorId>/<slug>/<version>.zip" }

The response carries the full automated-gate verdict, so CI can fail on it:


{
  "submissionId": "…", "themeId": "…", "versionId": "…",
  "gate": {
    "pass": false,
    "parser":   { "pass": true, "errors": [] },
    "preview":  { "pass": false, "templates": { "index": { "pass": false, "error": "…" } } },
    "security": { "pass": true, "findings": [] }
  }
}

A 200 does not mean accepted - check gate.pass. When it is false the submission is parked as CHANGES_REQUESTED and no reviewer sees it.

Errors worth handling: 400 malformed bundle / missing name or version in theme.json; 409 the slug belongs to another author.

`GET /marketplace/themes/mine`

Requires auth. Your submissions, newest first, each with its gate result, status, reviewer notes and version.

Context schema (machine-readable)

The Liquid context object shapes are published as a machine-readable JSON document:

/context-schema.json

It describes every object a theme can read - shop, product, collection, cart, linklists, settings, and the per-page extras - with field names, types, nullability, and notes. It is derived from the platform’s render-engine context interfaces, so it stays accurate to what your theme actually receives.


{
  "title": "Quickmerce Liquid Context Schema",
  "version": "1.0.0",
  "objects": [
    {
      "name": "product",
      "description": "The product on a product page ...",
      "fields": [
        { "name": "price", "type": "number", "description": "Lowest variant price. In paise ..." }
      ]
    }
  ]
}

Use it to power editor autocomplete, type generation, or a schema validator for your own tooling. The human-readable version of the same information is the Liquid context reference.

Notes carried in the schema

All *price fields on product / variant / cart are in paise (₹1 = 100 paise); render with the money filter.
collection.facets.priceRange and active_filters.min/maxPrice are in rupees, not paise.
Both main-menu and footer-menu linklist handles are guaranteed to resolve.