Merchant storefront

All routes require:

Authorization: Bearer mk_live_<your_key>

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.

{
  "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.

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)

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