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

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

Scopes: `store:read` (GET also accepts `widget:read`) · `store:update`. Ceiling `manageSettings`.

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

## Read

`GET` returns the store identity fields only.

```json theme={null}
{
  "id": "cm...",
  "name": "Northwind",
  "subdomain": "northwind",
  "currency": "USD",
  "description": null,
  "logo": null,
  "favicon": null,
  "background": null,
  "embedColor": null
}
```

| Field | Type |
| - | - |
| `id` | string |
| `name` | string |
| `subdomain` | string |
| `currency` | string |
| `description` | string or null |
| `logo` | string or null |
| `favicon` | string or null |
| `background` | string or null |
| `embedColor` | string or null |

`logo`, `favicon`, and `background` are normalized media URLs. `embedColor` is a lowercase `#rrggbb`, or null when unset or not a 6-digit hex.

## Update

`PATCH` and `PUT` are partial. Omitted fields stay as they are. Unknown keys are ignored, including `storeId` in the JSON body. At least one field below is required.

| Field | Type | Rules |
| - | - | - |
| `name` | string | Trimmed, 1–200 characters |
| `subdomain` | string | Trimmed, 1–63 characters. A duplicate returns `400` (`Subdomain already exists`) |
| `logo` | string or null | Max 500 characters. Empty clears it |
| `favicon` | string or null | Max 500 characters. Empty clears it |
| `background` | string or null | Max 500 characters. Empty clears it |
| `embedColor` | string or null | Max 32 characters. A non-empty value must be `#RRGGBB`. Empty clears it |
| `description` | string or null | Max 20000 characters. Empty clears it |
| `currency` | string | 3 letters. Must be a platform currency code. Stored uppercase |

The response is the same object as `GET`.

Payment secrets, pixels, and social URLs are not accepted here. Use [storefront](https://docs.joinmarkt.com/api-reference/merchant-storefront.md) for presentation fields and [payments](https://docs.joinmarkt.com/api-reference/merchant-payments.md) for gateways.

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