> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinmarkt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchant themes

> List catalog themes and apply one to a store with a Bearer API key.

All routes require:

```txt theme={null}
Authorization: Bearer mk_live_<your_key>
```

```http theme={null}
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](https://docs.joinmarkt.com/themes/overview.md).

## List themes

```http theme={null}
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.

```json theme={null}
{
  "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

```http theme={null}
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 |

```json theme={null}
{ "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.

```json theme={null}
{
  "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) |

## Related

* [Merchant storefront](https://docs.joinmarkt.com/api-reference/merchant-storefront.md)
* [API keys](https://docs.joinmarkt.com/developers/api-keys.md)
* [Authentication](https://docs.joinmarkt.com/api-reference/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.