Get Storefront Blocks

Retrieve the draft widgets of a storefront (Creator page), in display order.

The list is the complete layout: there is no sort, query, type, or is_hidden filter. Hidden widgets stay so they can be unhidden later. Default per_page is 100, so a typical page fits in one response.

An existing storefront with no widgets returns 200 and "items": []. A missing storefront returns 404. This nested list does not include preview_url — see Draft preview.

The item shape matches Get Storefront with include=blocks.

Request

GET /storefronts/{id}/blocks

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Storefront UUID

Query Parameters

Parameter	Type	Required	Default	Description
page	integer	No	1	Page number for pagination. Out-of-range values are clamped to a valid page.
per_page	integer	No	100	Items per page (min: 1, max: 100).

There are no other query parameters. A non-integer or out-of-range per_page returns a 400 (see Bad Request).

Widgets are returned in order ascending (starting at 1).

Every response includes the total in pagination.total.

Example Request

curl -X GET "https://cart.easy.tools/api/v1/storefronts/b10f5980-d653-4494-ad1c-6a9d68c96d19/blocks" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Success Response (200)

Returns a paginated list of draft widgets.

{
  "items": [
    {
      "id": "566cf11d-e6e2-4485-a828-e1b3d7da10a5",
      "type": "product",
      "layout": "6x3",
      "order": 1,
      "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"
      }
    },
    {
      "id": "fa9116f5-ecea-4d31-96c1-dd421be48d4d",
      "type": "space",
      "layout": "space-sm",
      "order": 2,
      "is_hidden": false,
      "is_hidden_on_mobile": false,
      "config": {
        "use_block_padding": false,
        "use_block_surface": false,
        "is_block_highlighted": false
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "per_page": 100,
    "total": 2
  }
}

Product references in config (product_id, and collection items[].product_id) are product UUIDs. A product that no longer exists is returned as null.

Response Fields

Each item is a Block object.

Pagination Object

Field	Type	Description
current_page	integer	Current page number.
total_pages	integer	Total number of pages.
per_page	integer	Effective page size (echoes the per_page request parameter).
total	integer	Total number of widgets on this storefront, including hidden ones.

Error Responses

Bad Request (400)

Returned when {id} is not a UUID, or when per_page is out of range.

{
  "message": "Invalid storefront ID"
}

{
  "message": "Invalid value for 'per_page': '0'"
}

Not Found Error (404)

Returned when the storefront UUID does not exist, belongs to another store, or points at a deleted storefront. An empty page is not this error — it is 200 with "items": [].

{
  "message": "Storefront not found"
}

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