Pages¶

Manage Hello Retail Pages end to end: the pages themselves (per-website product-listing pages, such as category or brand pages, that select products via filters and boosts) and the page designs they render with (the reusable HTML/Liquid, JS, and CSS templates plus filter and sorting settings, shared across all of the company's websites).

There are two ways to run Pages on your site:

1. The managed solution. Hello Retail renders the page on your site, using the page design's templates.
2. An API solution, built against the Pages REST API or the JavaScript SDK. Your frontend or server calls core.helloretail.com/serve/pages/{key} directly and renders the result itself. Request format: json to get the selected products as data (choose the returned fields with products.fields, down to just productNumber if you only want to look the products up in your own database), or format: html to get the design's rendered templates. These MCP tools don't run page loads; test against that live endpoint while you build.

The tools on this page matter to both integrations. A page's product filters, boosts, and out-of-stock setting decide which products the serve endpoint returns either way, and its design's filter and sorting settings define which facets and sort options the endpoint accepts and returns. Only the design's HTML/JS/CSS templates are specific to the managed solution and format: html.

Publishing is not possible through these tools. Edits land in DRAFT versions, and the serve endpoint returns the LIVE version of a page (unless a specific version id is requested, as described in the REST API doc), so nothing changes for visitors until the draft is published from My Hello Retail. Saving a design updates DRAFT page configs in place and creates a draft for LIVE ones; live pages keep serving the previous design version until their draft is published.

List the pages for my website and show which design each one uses.

Show the product filters on page <KEY> and explain which values the page expects at render time.

Copy the archived page design <KEY> and name the copy "Spring layout".

Show the product fields for my website, then add a brand filter to page design <KEY>.

Make the product titles larger in page design <KEY> and tell me which pages now have a draft to review.

listPageDesigns¶

List all page designs of a website's company, including archived ones. Returns each design's key, name, archived flag, whether filters and sorting are enabled, and when it was last modified. Use the key with getPageDesign or updatePageDesign. Archived designs are read-only; copy them with copyPageDesign to get an editable design.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "listPageDesigns",
    "arguments": {
      "websiteUuid": "<string>"
    }
  }
}

{
  "designs": [
    {
      "key": "<string>",
      "name": "<string>",
      "archived": false,
      "filtersEnabled": true,
      "sortingEnabled": false,
      "lastModified": "<string>"
    }
  ]
}

getPageDesign¶

Retrieve a page design: the HTML/Liquid, JS, and CSS templates plus the filter and sorting settings shown alongside the products. Use this before updatePageDesign to read the current state of the design.

Filter and sorting setting names refer to product fields; use getProductFields to see which fields exist. A filter's type decides how it renders: LIST and OBJECT offer the field's values as options, RANGE offers a min-max slider, BOOLEAN offers a two-way choice labeled by filteringText and negatedFilteringText (null for other types). A sort option offers a direction exactly when its ascendingText or descendingText is set.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getPageDesign",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>"
    }
  }
}

{
  "key": "<string>",
  "name": "<string>",
  "archived": false,
  "templateHtml": "<string>",
  "templateJs": "<string>",
  "templateCss": "<string>",
  "filtersEnabled": true,
  "sortingEnabled": true,
  "filterSettings": [
    {
      "name": "<string>",
      "type": "LIST",
      "title": "<string>",
      "filteringText": null,
      "negatedFilteringText": null
    }
  ],
  "sortingSettings": [
    {
      "name": "<string>",
      "title": "<string>",
      "ascendingText": "<string>",
      "descendingText": "<string>"
    }
  ],
  "lastModified": "<string>"
}

updatePageDesign¶

Update a page design. All fields are optional and updates are partial: omitted fields are left unchanged, but at least one must be provided. filterSettings and sortingSettings are full replacements of their respective lists. Archived designs cannot be edited; copy them first with copyPageDesign. Use getPageDesign first to read the current state before making changes.

Saving a design updates any DRAFT page configs using it in place, and automatically creates a draft for any LIVE page configs using it. The live pages keep serving the previous design version until their draft is published from the dashboard. The affected pages are reported in the result, each with an outcome of DRAFT_CREATED (the page was LIVE with no pending draft) or DRAFT_UPDATED (the page already had a draft, which was re-pointed in place).

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "updatePageDesign",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>",
      "templateCss": "<string>",
      "filterSettings": [
        {
          "name": "<string>",
          "type": "BOOLEAN",
          "title": "<string>",
          "filteringText": "<string>",
          "negatedFilteringText": "<string>"
        }
      ]
    }
  }
}

{
  "key": "<string>",
  "designId": 0,
  "name": "<string>",
  "affectedPages": [
    {
      "key": "<string>",
      "name": "<string>",
      "websiteUuid": "<string>",
      "outcome": "DRAFT_CREATED"
    }
  ],
  "lastModified": "<string>"
}

copyPageDesign¶

Copy a page design into a new, independent design. The copy starts from the source design's templates and filter/sorting settings but gets its own key, so it can be edited without affecting the original, and without affecting any pages, since no page config references the copy yet. This is the way to customize an archived design, which cannot be edited directly. Use listPageDesigns to find the source key and edit the copy with updatePageDesign.

The call fails when the company's Pages subscription has reached its design limit; contact Hello Retail to raise it.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "copyPageDesign",
    "arguments": {
      "websiteUuid": "<string>",
      "sourceKey": "<string>",
      "name": "<string>"
    }
  }
}

{
  "key": "<string>",
  "designId": 0,
  "name": "<string>",
  "sourceKey": "<string>",
  "lastModified": "<string>"
}

createPageDesign¶

Create a new page design from the built-in default template (HTML/Liquid, JS, and CSS). The new design has filters and sorting disabled and no filter or sorting settings; customize it with updatePageDesign. No page config references it yet, so editing it affects nothing until a page is pointed at it. To start from an existing design instead, use copyPageDesign.

The call fails when the company's Pages subscription has reached its design limit; contact Hello Retail to raise it.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "createPageDesign",
    "arguments": {
      "websiteUuid": "<string>",
      "name": "<string>"
    }
  }
}

{
  "key": "<string>",
  "designId": 0,
  "name": "<string>",
  "lastModified": "<string>"
}

listPages¶

List the pages of a website. One entry is returned per page; when a page has both a LIVE and a DRAFT version, the DRAFT (the version the update tools edit) is returned, with liveVersionExists indicating a LIVE version is serving. Pass includeArchived: true to also include archived pages. Use the key with getPage or updatePage, and the designKey with getPageDesign or updatePageDesign.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "listPages",
    "arguments": {
      "websiteUuid": "<string>"
    }
  }
}

{
  "pages": [
    {
      "key": "<string>",
      "name": "<string>",
      "state": "DRAFT",
      "liveVersionExists": true,
      "archived": false,
      "designKey": "<string>",
      "showOutOfStockProducts": false,
      "productScoreBoost": 0,
      "lastModified": "<string>"
    }
  ]
}

getPage¶

Retrieve the full configuration of a page: the design it renders with, the product filters selecting which products appear, the product and personalized boosts ordering them, and the Google Analytics event settings (read-only in these tools). Returns the DRAFT version when one exists (the version the update tools edit), otherwise the LIVE version; liveVersionExists indicates whether a LIVE version is serving. Use this before updatePage to read the current state.

A product filter's valueType decides where its value comes from: LITERAL filters compare against the stored value, while INPUT filters compare against a value supplied at render time, keyed by the filter's field name, by the page's embed script or by the params object of a REST API request. Filter and boost field names refer to product fields; use getProductFields to see which fields exist. urlOverrideCount reports how many URL-specific overrides the page has; overrides are managed in the dashboard.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getPage",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>"
    }
  }
}

{
  "key": "<string>",
  "name": "<string>",
  "state": "DRAFT",
  "liveVersionExists": true,
  "archived": false,
  "designKey": "<string>",
  "showOutOfStockProducts": false,
  "productScoreBoost": 0,
  "filteredByGroupingKey": false,
  "productFilters": [
    {
      "field": "<string>",
      "operator": "EQ",
      "valueType": "LITERAL",
      "value": "<string>"
    }
  ],
  "productBoosts": [
    {
      "field": "<string>",
      "value": "<string>",
      "boost": 0
    }
  ],
  "personalizedBoosts": [
    {
      "field": "<string>",
      "boost": 0
    }
  ],
  "urlOverrideCount": 0,
  "gaEvents": {
    "enabled": false,
    "clickCategory": "<string>",
    "clickAction": "<string>",
    "clickLabel": "<string>",
    "viewCategory": "<string>",
    "viewAction": "<string>",
    "viewLabel": "<string>"
  },
  "lastModified": "<string>"
}

updatePage¶

Update a page. All fields are optional and updates are partial: omitted fields are left unchanged, but at least one must be provided. productFilters, productBoosts, and personalizedBoosts are full replacements of their respective lists; pass an empty list to clear one. Use getPage first to read the current state before making changes.

The edit never touches the serving version: a LIVE page gets a draft created with the changes (draftCreated: true in the result), and a page that already has a draft gets that draft edited. The saved version is always left in DRAFT state, for review and publishing in the dashboard.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "updatePage",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>",
      "productFilters": [
        {
          "field": "<string>",
          "operator": "EQ",
          "valueType": "LITERAL",
          "value": "<string>"
        }
      ]
    }
  }
}

{
  "key": "<string>",
  "name": "<string>",
  "state": "DRAFT",
  "draftCreated": true,
  "designKey": "<string>",
  "lastModified": "<string>"
}

createPage¶

Create a new page: a product-listing page that selects products via filters and boosts and renders them with a page design. The page is created in DRAFT state and serves nothing until published from the dashboard. Use listPageDesigns to find a design key (or create one with createPageDesign), and getProductFields for the product fields available to filters and boosts.

The call fails when the website has no active Pages subscription or its page limit is reached; contact Hello Retail in either case.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "createPage",
    "arguments": {
      "websiteUuid": "<string>",
      "name": "<string>",
      "designKey": "<string>",
      "productFilters": [
        {
          "field": "hierarchies",
          "operator": "ANY",
          "valueType": "INPUT"
        }
      ]
    }
  }
}

{
  "key": "<string>",
  "name": "<string>",
  "state": "DRAFT",
  "designKey": "<string>",
  "lastModified": "<string>"
}

copyPage¶

Copy a page into a new, independent page. The copy starts from the source page's full configuration (filters, boosts, GA settings, design) but gets its own key and is created in DRAFT state, so it serves nothing until published from the dashboard. The copy can target another website of the same company (targetWebsiteUuid) and can be pointed at a different design (designKey) in the same call. Use listPages to find the source key.

The call fails when the target website has no active Pages subscription or its page limit is reached; contact Hello Retail in either case.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "copyPage",
    "arguments": {
      "websiteUuid": "<string>",
      "sourceKey": "<string>",
      "targetWebsiteUuid": "<string>"
    }
  }
}

{
  "key": "<string>",
  "name": "<string>",
  "state": "DRAFT",
  "sourceKey": "<string>",
  "websiteUuid": "<string>",
  "designKey": "<string>",
  "lastModified": "<string>"
}