Reorder Storefront Blocks

Rewrite the display order of every draft widget on a storefront (Creator page).

The body must list every current block exactly once, including hidden ones. order is the value that is stored: it must be a permutation of 1 through N (N is the current widget count). Array position is ignored — an item with "order": 2 becomes second even if it is first in items.

Do not send layout, config, or is_hidden here. Extra or missing UUIDs return 422, not 404. An empty page accepts { "items": [] }.

The response is { items, preview_url } — full Block objects in the new display order, with no pagination. Visitors still see the last published page at public_url until Publish Storefront.

Request

POST /storefronts/{id}/blocks/reorder

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Storefront UUID

Request Body

Unknown top-level or per-item keys are rejected.

Parameter	Type	Required	Description
items	array	Yes	One entry per current widget. Empty only when the storefront has no widgets.
items[].id	string	Yes	Block UUID of this storefront. Each id must appear exactly once.
items[].order	integer	Yes	Display order, 1 through N. The set of values must equal {1, 2, …, N}. Duplicate, gap, 0, or negative returns 422.

Example Request

Swap the two widgets on this storefront. Array position does not matter: the product is listed first with "order": 2. A storefront with more widgets must include every current id (hidden ones too) with a permutation of 1..N.

curl -X POST "https://cart.easy.tools/api/v1/storefronts/b10f5980-d653-4494-ad1c-6a9d68c96d19/blocks/reorder" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "id": "566cf11d-e6e2-4485-a828-e1b3d7da10a5", "order": 2 },
      { "id": "fa9116f5-ecea-4d31-96c1-dd421be48d4d", "order": 1 }
    ]
  }'

Response

Success Response (200)

Returns every widget in the new display order, plus a fresh preview_url. Get Storefront Blocks still omits preview_url.

Hidden widgets are included; there is no pagination key.

{
  "items": [
    {
      "id": "fa9116f5-ecea-4d31-96c1-dd421be48d4d",
      "type": "space",
      "layout": "space-sm",
      "order": 1,
      "is_hidden": false,
      "is_hidden_on_mobile": false,
      "config": {
        "use_block_padding": false,
        "use_block_surface": false,
        "is_block_highlighted": false
      }
    },
    {
      "id": "566cf11d-e6e2-4485-a828-e1b3d7da10a5",
      "type": "product",
      "layout": "6x3",
      "order": 2,
      "is_hidden": false,
      "is_hidden_on_mobile": false,
      "config": {
        "use_block_padding": true,
        "use_block_surface": true,
        "is_block_highlighted": true,
        "product_id": "3288e647-aab0-4289-957f-dac92e9b3ffe",
        "ownership_status": "hide_owned",
        "cta_label": { "value": "Get the newest", "is_hidden": false },
        "owned_cta_label": "Open"
      }
    }
  ],
  "preview_url": "https://cart.easy.tools/storefront-preview/b10f5980-d653-4494-ad1c-6a9d68c96d19?expires=1788349726&signature=4c2a2b070865fd9cbfedecbff226e96d2e6ee64f089f86f6756751c038751967"
}

A storefront with no widgets returns "items": [] and still includes preview_url.

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

Response Fields

Each item is a Block object. The list is not paginated.

Field	Type	Nullable	Description
items	array	No	Full widget list in display order (order ascending). Hidden widgets stay.
preview_url	string	No	Temporary signed URL of the saved draft. Top-level sibling of items, not on each block. Expires after about one hour.

Error Responses

Bad Request (400)

Returned when {id} is not a UUID.

{
  "message": "Invalid storefront ID"
}

Not Found Error (404)

Returned when the storefront UUID does not exist, belongs to another store, or points at a deleted storefront. An unknown block UUID in items is 422, not this error.

{
  "message": "Storefront not found"
}

Validation Error (422 Unprocessable Entity)

Returned for an unknown key, a missing or non-array items, a malformed item id, a duplicate id, an items list that is not exactly the current set of blocks, or order values that are not a permutation of 1 through N.

{
  "message": "The items list must include every block of this storefront exactly once.",
  "errors": {
    "items": [
      "The items list must include every block of this storefront exactly once."
    ]
  }
}

{ "items": [] } when the storefront has widgets returns that same completeness error. order 3 on a two-widget page returns The order values must be a permutation of 1 through 2.

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