Update Storefront Header

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

photo is sparse-merged into the stored object — send only the keys you want to change. links replaces the whole array when sent ([] clears).

Clearable strings take "", not null — see Draft updates. Colors are six-digit hex (#RRGGBB).

The response is the same shape as Get Storefront with include=header. 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}/header

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
`layout`	string	`large` or `compact`
`logo_url`	string	Logo image URL, or `""` to clear. Absolute `http://` or `https://` only.
`photo`	object	Sparse-merged into the stored hero media. See Photo.
`image_style`	string	`basic`, `backdrop`, or `spotlight`
`image_rounding`	string	`none`, `s`, `m`, `l`, or `full`
`background_type`	string	`solid`, `gradient`, or `image`
`background_color`	string	Header background. `#RRGGBB`
`background_gradient_from`	string	Header gradient start. `#RRGGBB`
`background_gradient_to`	string	Header gradient end. `#RRGGBB`
`background_image_url`	string	Header background image URL, or `""` to clear
`background_blur`	integer	Blur amount (`min: 0`). No upper bound.
`title`	string	Header title (max 255), or `""` to clear
`bio`	string	Header bio (HTML or plain, max 10000), or `""` to clear
`font_family`	string	Header font name (free text, max 100)
`text_color`	string	Header text color. `#RRGGBB`
`show_links`	boolean	Whether social / website links are shown
`links`	array	Replaces the stored links. `[]` clears. See Link.

Every URL must be an absolute http:// or https:// URL, or "" to clear. Relative paths such as /images/logo.png return 422. Host a new image or video with Upload Media, then PATCH the returned file_url.

Photo

Sparse-merged. Omitted keys inside photo are left unchanged. Unknown keys return 422.

Parameter	Type	Description
`media_type`	string	`image`, `video`, or `iframe`
`src_url`	string	Hero image URL, or `""` to clear
`alt`	string	Alt text (max 1000), or `""` to clear
`video_src_url`	string	Hero video URL, or `""` to clear
`video_autoplay`	boolean	Whether the hero video autoplays
`video_controls`	boolean	Whether playback controls are shown
`video_loop`	boolean	Whether the hero video loops
`iframe_src_url`	string	Hero iframe URL, or `""` to clear
`is_hidden`	boolean	Whether the hero media is hidden
`fit`	string	`cover` or `contain`

Link

Each item replaces as a whole when links is sent. Unknown item keys return 422. link cannot be empty.

Parameter	Type	Required	Description
`type`	string	Yes	`facebook`, `instagram`, `x`, `linkedin`, `youtube`, `telegram`, `tiktok`, or `website`
`icon`	string	Yes	Icon token shown next to the link (max 100)
`link`	string	Yes	Absolute `http://` or `https://` URL

Example Requests

Change the title and merge one photo field (alt). Other photo keys stay as stored:

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

Replace social links:

curl -X PATCH "https://cart.easy.tools/api/v1/storefronts/b10f5980-d653-4494-ad1c-6a9d68c96d19/header" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "links": [
      {
        "type": "instagram",
        "icon": "instagram",
        "link": "https://www.instagram.com/mystudio/"
      }
    ]
  }'

Response

Success Response (200)

Returns the storefront with the merged header section. styles, 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=1788339528&signature=f893b3a702d3a04eeb5b1fd1b866ab1ed9dee52b780f8e7879460fc5c7c12071",
  "domains": [
    {
      "domain": "mysite.com",
      "status": "configured",
      "include_www": true
    }
  ],
  "created_at": "2026-03-12T10:00:00+00:00",
  "updated_at": "2026-09-02T09:58:48+00:00",
  "published_at": "2026-04-01T09:00:00+00:00",
  "styles": null,
  "header": {
    "layout": "large",
    "logo_url": "",
    "photo": {
      "media_type": "image",
      "src_url": "https://cdn.example.com/storefront-media/wBJ6CDIaHVVEUTBpsC8JJc2wrFvOWK04.webp",
      "alt": "Portrait",
      "video_src_url": "",
      "video_autoplay": true,
      "video_controls": false,
      "video_loop": true,
      "iframe_src_url": "",
      "is_hidden": false,
      "fit": "cover"
    },
    "image_style": "backdrop",
    "image_rounding": "full",
    "background_type": "image",
    "background_color": "#6366f1",
    "background_gradient_from": "#6366f1",
    "background_gradient_to": "#a855f7",
    "background_image_url": "https://cdn.example.com/storefront-media/wBJ6CDIaHVVEUTBpsC8JJc2wrFvOWK04.webp",
    "background_blur": 72,
    "title": "My Studio",
    "bio": "Portraits, weddings, and photography workshops.",
    "font_family": "Lora",
    "text_color": "#391106",
    "show_links": true,
    "links": [
      {
        "type": "instagram",
        "icon": "instagram",
        "link": "https://www.instagram.com/mystudio/"
      }
    ]
  },
  "settings": null,
  "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, an image_style outside the allowed values, a color that is not #RRGGBB, or a URL that is not absolute HTTP(S) (or "").

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

Request​

Path Parameters​

Request Body​

Photo​

Link​

Example Requests​

Response​

Success Response (200)​

Response Fields​

Error Responses​

Bad Request (400)​

Not Found Error (404)​

Validation Error (422 Unprocessable Entity)​

Unauthorized (401)​

Forbidden (403)​

Too Many Requests (429)​