Update Storefront Settings

Sparse-update the saved draft settings of a storefront (Creator page). Omitted keys are left unchanged. Unknown keys at any nesting level return 422.

external_analytics is not writable and is never returned. Stored analytics pixels are left untouched. privacy_easylegal is sparse-merged.

Clearable strings take "", not null — see Draft updates. privacy_easylegal.footer_id accepts a UUID, or null to clear. This response omits it. Read it on Get Storefront with include=footer_id — see Easylegal footer.

The response is the same shape as Get Storefront with include=settings. Visitors still see the last published page at public_url until Publish Storefront.

An empty body is a 200 with no change.

Request

PATCH /storefronts/{id}/settings

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Storefront UUID

Request Body

All fields are optional. Only include the keys you want to change. Unknown keys are rejected.

Parameter	Type	Description
page_title	string	SEO page title (max 255), or "" to clear
page_description	string	SEO page description (max 10000), or "" to clear
page_language	string	auto, en, or pl
checkout_open_mode	string	default or popup
og_image_url	string	Open Graph image URL, or "" to clear. Absolute http:// or https:// only.
favicon_url	string	Favicon URL, or "" to clear
webclip_url	string	Apple webclip URL, or "" to clear
privacy_url	string	Privacy-policy URL, or "" to clear
privacy_easylegal	object	Sparse-merged Easylegal footer. See Privacy Easylegal.

external_analytics is not an allowed key. Sending it returns 422. Relative paths such as /images/og.png return 422. Host a new image with Upload Media, then PATCH the returned file_url.

Privacy Easylegal

Sparse-merged. Omitted keys inside privacy_easylegal are left unchanged. Unknown keys (including policy_url) return 422.

footer_id accepts a UUID, or null to clear. Omit the key to leave the stored footer. An integer returns 422 and that patch is not saved. A UUID that is not a legal footer on your account returns 422, and nothing in the patch is saved. This response does not include footer_id. Get Storefront returns the UUID only when include=footer_id is set — see Easylegal footer.

Parameter	Type	Description
enabled	boolean	Whether the Easylegal privacy footer is enabled
footer_id	string | null	Legal footer UUID. Omit to leave the stored value. null clears it. An integer returns 422. Omitted from this response.

Example Requests

curl -X PATCH "https://cart.easy.tools/api/v1/storefronts/b10f5980-d653-4494-ad1c-6a9d68c96d19/settings" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "page_title": "My Studio",
    "page_language": "en"
  }'

Clear SEO title and description. The stored values are empty strings:

curl -X PATCH "https://cart.easy.tools/api/v1/storefronts/b10f5980-d653-4494-ad1c-6a9d68c96d19/settings" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "page_title": "",
    "page_description": ""
  }'

Response

Success Response (200)

Returns the storefront with the merged settings section, the same shape as include=settings. Analytics pixel configuration and privacy_easylegal.footer_id are not included. styles, header, and blocks are null. preview_url is a fresh signature of the saved draft.

{
  "id": "b10f5980-d653-4494-ad1c-6a9d68c96d19",
  "slug": "my-studio",
  "name": "My Studio",
  "status": "published",
  "public_url": "https://mysite.com/",
  "preview_url": "https://cart.easy.tools/storefront-preview/b10f5980-d653-4494-ad1c-6a9d68c96d19?expires=1788339527&signature=a02df227825d463d9ebf133f2087920af72122d905db8600860b5de23df0e3e0",
  "domains": [
    {
      "domain": "mysite.com",
      "status": "configured",
      "include_www": true
    }
  ],
  "created_at": "2026-03-12T10:00:00+00:00",
  "updated_at": "2026-09-02T09:58:47+00:00",
  "published_at": "2026-04-01T09:00:00+00:00",
  "styles": null,
  "header": null,
  "settings": {
    "page_title": "My Studio",
    "page_description": "Portraits, weddings, and photography workshops.",
    "page_language": "en",
    "checkout_open_mode": "default",
    "og_image_url": "",
    "favicon_url": "",
    "webclip_url": "",
    "privacy_url": "",
    "privacy_easylegal": {
      "enabled": false
    }
  },
  "blocks": null
}

preview_url is a fresh signature on every write. See Draft preview.

Response Fields

Identity, URLs, timestamps, and included sections are documented on the Storefront Object. Nested Domain lives there too.

Error Responses

Bad Request (400)

Returned when {id} is not a UUID.

{
  "message": "Invalid storefront ID"
}

Not Found Error (404)

Returned when the UUID does not exist, belongs to another store, or points at a deleted storefront.

{
  "message": "Storefront not found"
}

Validation Error (422 Unprocessable Entity)

Returned for an unknown key (including external_analytics), a URL that is not absolute HTTP(S) (or ""), a token outside the allowlist, an integer privacy_easylegal.footer_id, or a footer_id that is not a legal footer on your account. The patch is not saved.

{
  "message": "The external_analytics field is not allowed.",
  "errors": {
    "external_analytics": [
      "The external_analytics field is not allowed."
    ]
  }
}

Unauthorized (401)

{
  "message": "Unauthenticated."
}

Forbidden (403)

Returned when your API key has not been granted access to the requested store.

{
  "message": "You do not have API access to the requested store."
}

Too Many Requests (429)

Returned when you exceed the rate limit. The Retry-After response header gives the number of seconds to wait.

{
  "message": "Too many requests. Please retry after 60 seconds."
}