Merchant store

All routes require:

Authorization: Bearer mk_live_<your_key>

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.

{
  "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 for presentation fields and payments 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)

Get started

Analytics

Checkout

Dashboard

Merchant API

Merchant API playground

Orders

Public catalog

Reference

Webhooks

Read

Update

Errors

​Read

​Update

​Errors

​Related

Read

Update

Errors

Related