> ## 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 storefront

> Read and update storefront presentation 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}/storefront
PATCH /api/merchant/v1/stores/{storeId}/storefront
PUT   /api/merchant/v1/stores/{storeId}/storefront
```

Scopes: `storefront:read` · `storefront:write`. Ceiling `configureStorefront`.

`PUT` is the same handler as `PATCH`.

## Read

`GET` returns the storefront configuration, builder pages, and the current theme pointer.

```json theme={null}
{
  "id": "cm...",
  "publicId": "STR-...",
  "name": "Northwind",
  "subdomain": "northwind",
  "logo": null,
  "favicon": null,
  "background": null,
  "embedColor": null,
  "description": null,
  "currency": "USD",
  "hideNameInHeader": false,
  "liveSalesPopupsEnabled": false,
  "liveProductStatsEnabled": false,
  "liveSalesPopupsScope": "product",
  "discordUrl": null,
  "youtubeUrl": null,
  "telegramUrl": null,
  "tiktokUrl": null,
  "instagramUrl": null,
  "privacyPolicy": null,
  "termsOfService": null,
  "refundPolicy": null,
  "googleAnalyticsId": null,
  "googleTagManagerId": null,
  "googleSiteVerification": null,
  "metaPixelId": null,
  "tiktokPixelId": null,
  "crispWebsiteId": null,
  "tawkToId": null,
  "affiliateEnabled": false,
  "affiliatePercentage": 0,
  "notificationConfig": null,
  "paymentOptionsConfig": null,
  "paymentNotesConfig": null,
  "taxConfig": null,
  "ticketConfig": null,
  "pages": [
    {
      "id": "cm...",
      "slug": "index",
      "title": "Home",
      "status": "draft",
      "updatedAt": "2026-09-21T00:00:00.000Z"
    }
  ],
  "themeTemplateId": null,
  "themeSlug": null,
  "themeName": null
}
```

| Field | Type |
| - | - |
| `id` | string |
| `publicId` | string |
| `name` | string |
| `subdomain` | string |
| `logo`, `favicon`, `background` | string or null |
| `embedColor` | string or null |
| `description` | string or null |
| `currency` | string |
| `hideNameInHeader` | boolean |
| `liveSalesPopupsEnabled` | boolean |
| `liveProductStatsEnabled` | boolean |
| `liveSalesPopupsScope` | string (`product` or `store`) |
| `discordUrl`, `youtubeUrl`, `telegramUrl`, `tiktokUrl`, `instagramUrl` | string or null |
| `privacyPolicy`, `termsOfService`, `refundPolicy` | string or null |
| `googleAnalyticsId`, `googleTagManagerId`, `googleSiteVerification` | string or null |
| `metaPixelId`, `tiktokPixelId`, `crispWebsiteId`, `tawkToId` | string or null |
| `affiliateEnabled` | boolean |
| `affiliatePercentage` | number or null |
| `notificationConfig`, `paymentOptionsConfig`, `paymentNotesConfig` | JSON or null |
| `taxConfig`, `ticketConfig` | JSON or null |
| `pages` | array |
| `themeTemplateId`, `themeSlug`, `themeName` | string or null |

Each `pages` item is `id`, `slug`, `title`, `status` (string), and `updatedAt` (ISO-8601). `pages` is `[]` when the store has no builder pages.

Gateway secret columns on the store row are not selected. `paymentOptionsConfig` and `paymentNotesConfig` are the stored JSON blobs and are read-only on this route. Store identity fields `name`, `subdomain`, `currency`, `description`, `logo`, `favicon`, `background`, and `embedColor` are read-only here. Update them with [Merchant store](https://docs.joinmarkt.com/api-reference/merchant-store.md).

## Update

`PATCH` and `PUT` are partial. Unknown keys are ignored, including `storeId`. At least one field below is required. The response is the same object as `GET`.

| Field | Type | Rules |
| - | - | - |
| `hideNameInHeader` | boolean | |
| `discordUrl`, `youtubeUrl`, `telegramUrl`, `tiktokUrl`, `instagramUrl` | string or null | Max 500 characters. Empty clears the value |
| `privacyPolicy`, `termsOfService`, `refundPolicy` | string or null | Max 100000 characters. Empty clears the value |
| `googleAnalyticsId` | string or null | Max 64. `G-…`, `UA-…-…`, or `GT-…`. Empty clears it |
| `googleTagManagerId` | string or null | Max 64. `GTM-` plus 4–12 letters or digits. Empty clears it |
| `googleSiteVerification` | string or null | Max 200. Token, or the `content` of a google-site-verification meta tag (10–120 of `A–Z`, `a–z`, `0–9`, `_`, `-`). Empty clears it |
| `metaPixelId` | string or null | Max 64. 5–20 digits. Empty clears it |
| `tiktokPixelId` | string or null | Max 64. 10–64 letters or digits. Empty clears it |
| `crispWebsiteId` | string or null | Max 64. UUID. Empty clears it |
| `tawkToId` | string or null | Max 200. `propertyId/widgetId`, a `tawk.to/chat/…/…` link, or an `embed.tawk.to` URL. A property id alone is rejected. Empty clears it |
| `affiliateEnabled` | boolean | |
| `affiliatePercentage` | number or null | 0–100. Numeric strings are coerced. `0` is stored as null |
| `ticketConfig` | JSON | Normalized on save. Invalid settings return `400` |
| `taxConfig` | JSON | Normalized on save. Invalid settings return `400` |

`liveSalesPopupsEnabled`, `liveProductStatsEnabled`, `liveSalesPopupsScope`, `notificationConfig`, `paymentOptionsConfig`, and `paymentNotesConfig` are returned by `GET` and are not in the update schema.

## Errors

| Status | Meaning |
| - | - |
| 400 | Invalid JSON, a non-object body, no updatable fields, or a field failed validation |
| 401 | Missing, invalid, expired, or revoked token |
| 403 | Scope or shop not allowed for this key |
| 404 | Store not found |
| 429 | Rate limit exceeded (120 requests per 60 seconds) |

## Related

* [Merchant themes](https://docs.joinmarkt.com/api-reference/merchant-themes.md)
* [Merchant store](https://docs.joinmarkt.com/api-reference/merchant-store.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.