Merchant themes

All routes require:

Authorization: Bearer mk_live_<your_key>

GET  /api/merchant/v1/stores/{storeId}/themes
POST /api/merchant/v1/stores/{storeId}/themes/apply

Scopes: theme:read · theme:write. Ceiling editDesign. To build or edit a theme, see Themes.

List themes

GET /api/merchant/v1/stores/{storeId}/themes

Scope: theme:read. Every active theme template is listed, including an uploaded template when it is active. The template document, isPremium, and priceCents are omitted.

{
  "themes": [
    {
      "id": "cm...",
      "slug": "glitch",
      "name": "Glitch",
      "description": "Catalog theme",
      "category": "storefront",
      "tags": [],
      "previewImage": "https://...",
      "previewTablet": null,
      "previewMobile": null,
      "features": [],
      "docs": null,
      "sortOrder": 0,
      "createdAt": "2026-09-21T00:00:00.000Z"
    }
  ],
  "current": {
    "themeTemplateId": null,
    "themeSlug": null,
    "themeName": null,
    "publishedAt": null
  }
}

Field	Type
`themes`	array. `[]` when no theme template is active
`themes[].id`, `slug`, `name`, `description`, `category`	string
`themes[].tags`, `features`	string array
`themes[].previewImage`	string
`themes[].previewTablet`, `previewMobile`, `docs`	string or null
`themes[].sortOrder`	number
`themes[].createdAt`	ISO-8601
`current`	object when the store row exists, or null when that row is missing
`current.themeTemplateId`, `themeSlug`, `themeName`	string or null
`current.publishedAt`	ISO-8601 or null. Last theme publish time on the store

Apply a theme

POST /api/merchant/v1/stores/{storeId}/themes/apply

Scope: theme:write. Send themeId or themeSlug (at least one). If both are sent, themeId is used. The lookup does not require the template to be active. publish is optional.

Field	Type	Rules
`themeId`	string	Trimmed, 1–100 characters
`themeSlug`	string	Trimmed, 1–200 characters
`publish`	boolean	Omitted or `true` publishes. `false` leaves the new theme as a draft

{ "themeSlug": "glitch", "publish": false }

Applying replaces the index page draft with a fresh copy of the template. Previous builder edits on that page are not copied. That page’s published document is cleared. Other pages stay as they are. Live storefront artifacts stay until a publish runs.

{
  "ok": true,
  "storeId": "cm...",
  "published": false,
  "engine": "vite",
  "fileCount": 12,
  "themeFamily": "unknown"
}

Field	Type
`ok`	`true`
`storeId`	string
`published`	boolean. `true` only when publish was requested and the store has a subdomain
`engine`	string. `vite` when the theme document has no engine
`fileCount`	number
`themeFamily`	`uploaded` or `unknown`

The key’s user must also have dashboard editDesign on the store. Otherwise apply returns 403.

Errors

Status	Meaning
400	Invalid JSON, a non-object body, neither `themeId` nor `themeSlug`, or the theme document is invalid
401	Missing, invalid, expired, or revoked token
403	Scope, shop, or `editDesign` not allowed
404	Store or theme not found
429	Rate limit exceeded (120 requests per 60 seconds)

Get started

Analytics

Checkout

Dashboard

Merchant API

Merchant API playground

Orders

Public catalog

Reference

Webhooks

List themes

Apply a theme

Errors

​List themes

​Apply a theme

​Errors

​Related

List themes

Apply a theme

Errors

Related