Update Storefront Styles

Sparse-update the saved draft styles of a storefront (Creator page). Omitted keys are left unchanged. Unknown keys return 422.

The response is the same shape as Get Storefront with include=styles: identity, a fresh preview_url, the merged styles object, and the other section keys as null. Visitors still see the last published page at public_url until Publish Storefront.

theme_id is stored as an integer tag. It does not copy a branding theme's colors or fonts — send brand_color, font_family, and rounding keys for a visual change. Colors are six-digit hex (#RRGGBB).

An empty body is a 200 with no change.

Request

PATCH /storefronts/{id}/styles

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
theme_id	integer | null	Branding-theme integer tag. Does not apply a palette. null clears the tag.
background_type	string	solid or gradient
highlighted_background_type	string	solid or gradient
storefront_rounding	string	none, s, m, l, or xl
block_rounding	string	none, s, m, l, or xl
image_rounding	string	none, s, m, l, or xl
form_rounding	string	none, s, m, l, or xl
button_rounding	string	none, s, m, l, or full (no xl)
storefront_shadow	string	none, s, m, l, or xl
block_shadow	string	none, s, m, l, or xl
storefront_padding	string	none, s, m, l, or xl
block_padding	string	none, s, m, l, or xl
grid_gap	string	none, s, m, l, or xl
storefront_card_show_background	boolean	Whether the page card shows a background fill
storefront_show_border	boolean	Whether the page card shows a border
block_show_border	boolean	Whether blocks show a border
block_show_background	boolean	Whether blocks show a background fill
font_family	string	Google font name (free text, max 100)
background	string	Page background. #RRGGBB
background_gradient_to	string	Page background gradient end. #RRGGBB
storefront_background	string	Page card background. #RRGGBB
font_color	string	Default text color. #RRGGBB
block_font_color	string	Block text color. #RRGGBB
brand_color	string	Brand / accent color. #RRGGBB
storefront_border_color	string	Page card border. #RRGGBB
block_background	string	Block background. #RRGGBB
block_border_color	string	Block border. #RRGGBB
highlighted_background	string	Highlighted-block background. #RRGGBB
highlighted_background_gradient_to	string	Highlighted-block gradient end. #RRGGBB
highlighted_font_color	string	Highlighted-block text. #RRGGBB
button_background	string	Button background. #RRGGBB
button_color	string	Button text. #RRGGBB
form_border_color	string	Form-field border. #RRGGBB

Short hex such as #fff returns 422.

Example Request

curl -X PATCH "https://cart.easy.tools/api/v1/storefronts/b10f5980-d653-4494-ad1c-6a9d68c96d19/styles" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_color": "#101828",
    "button_rounding": "full"
  }'

Response

Success Response (200)

Returns the storefront with the merged styles section. header, settings, 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=1788339515&signature=6cab2c21cfc065f69abfd5d072ff027775b604e14485aa5ed94d313ced1e1c3b",
  "domains": [
    {
      "domain": "mysite.com",
      "status": "configured",
      "include_www": true
    }
  ],
  "created_at": "2026-03-12T10:00:00+00:00",
  "updated_at": "2026-09-02T09:58:35+00:00",
  "published_at": "2026-04-01T09:00:00+00:00",
  "styles": {
    "theme_id": 35,
    "background_type": "solid",
    "background": "#f3f1ed",
    "background_gradient_to": "#f3f1ed",
    "storefront_background": "#e7e3da",
    "storefront_card_show_background": true,
    "font_color": "#391106",
    "block_font_color": "#391106",
    "font_family": "Lora",
    "brand_color": "#101828",
    "storefront_rounding": "xl",
    "storefront_shadow": "none",
    "storefront_show_border": false,
    "storefront_border_color": "#391106",
    "storefront_padding": "m",
    "grid_gap": "l",
    "block_background": "#f3f1ed",
    "block_rounding": "xl",
    "block_show_border": false,
    "block_show_background": true,
    "block_border_color": "#391106",
    "block_shadow": "none",
    "block_padding": "xl",
    "highlighted_background_type": "solid",
    "highlighted_background": "#8f7761",
    "highlighted_background_gradient_to": "#C5D0DF",
    "highlighted_font_color": "#e7e3da",
    "image_rounding": "l",
    "button_background": "#e7e3da",
    "button_color": "#391106",
    "button_rounding": "full",
    "form_border_color": "#391106",
    "form_rounding": "l"
  },
  "header": null,
  "settings": null,
  "blocks": null
}

preview_url is a fresh signature on every write. The expires / signature query in this example will already be stale; the shape is what matters. 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, a color that is not #RRGGBB, or a token outside the allowlist.

{
  "message": "The not_a_style_key field is not allowed.",
  "errors": {
    "not_a_style_key": [
      "The not_a_style_key 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."
}