Pages¶

Manage Hello Retail Pages end to end: the page configs (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).

Like the search tools, both resources are edited through per-facet tools: a design splits into its templates (pages_getDesign/pages_updateDesign), filter settings (pages_getDesignFilters/pages_updateDesignFilters), and sorting settings (pages_getDesignSorting/pages_updateDesignSorting); a page config into its core settings (pages_getConfig/pages_updateConfig), product filters (pages_getConfigProductFilters/pages_updateConfigProductFilters), and boosts (pages_getConfigProductBoosts/pages_updateConfigProductBoosts).

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 config'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.

Tips & tricks¶

Pick the card that matches what you're doing. Each prompt is ready to paste into your assistant.

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

Show the product filters on page config <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 page configs now have a draft to review.

Page designs¶

pages_listDesigns¶

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 pages_getDesign (templates), pages_getDesignFilters, and pages_getDesignSorting. Archived designs are read-only; copy them with pages_copyDesign to get an editable design.

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

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

pages_getDesign¶

Retrieve a page design's templates: the HTML/Liquid, JS, and CSS the design renders page configs with. The filter and sorting settings shown alongside the products are separate facets; read them with pages_getDesignFilters and pages_getDesignSorting. Use this before pages_updateDesign to read the current state of the templates.

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

{
  "key": "<string>",
  "name": "<string>",
  "archived": false,
  "templateHtml": "<string>",
  "templateJs": "<string>",
  "templateCss": "<string>",
  "lastModified": "<string>"
}

pages_updateDesign¶

Update a page design's name and templates. All fields are optional and updates are partial: omitted fields are left unchanged, but at least one must be provided. Filter and sorting settings are separate facets; update them with pages_updateDesignFilters and pages_updateDesignSorting. Archived designs cannot be edited; copy them first with pages_copyDesign. Use pages_getDesign 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 page configs are reported in the result, each with an outcome of DRAFT_CREATED (the page config was LIVE with no pending draft) or DRAFT_UPDATED (it already had a draft, which was re-pointed in place).

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

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

pages_getDesignFilters¶

Get the filter settings of a page design: whether visitors are offered filters on page configs using the design, and the ordered list of filters they can narrow the products by. Use this before pages_updateDesignFilters to read the current state.

Filter names refer to product fields; use dataFields_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).

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

{
  "filtersEnabled": true,
  "filterSettings": [
    {
      "name": "<string>",
      "type": "LIST",
      "title": "<string>",
      "filteringText": null,
      "negatedFilteringText": null
    }
  ]
}

pages_updateDesignFilters¶

Update the filter settings of a page design: toggle whether visitors are offered filters, and/or replace the complete list of filters. At least one of the two must be provided; filterSettings replaces the current list in full — pass an empty list to clear it. Archived designs cannot be edited; copy them first with pages_copyDesign. Use pages_getDesignFilters first to read the current state before making changes.

Saving follows the same draft rules as pages_updateDesign: DRAFT page configs using the design are updated in place, LIVE ones get a draft and keep serving unchanged, and the affected page configs are reported in the result.

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

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

pages_getDesignSorting¶

Get the sorting settings of a page design: whether visitors are offered sort options on page configs using the design, and the ordered list of sort options. Use this before pages_updateDesignSorting to read the current state.

Sort option names refer to product fields; use dataFields_getProductFields to see which fields exist. A sort option offers a direction exactly when its ascendingText or descendingText is set.

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

{
  "sortingEnabled": true,
  "sortingSettings": [
    {
      "name": "<string>",
      "title": "<string>",
      "ascendingText": "<string>",
      "descendingText": "<string>"
    }
  ]
}

pages_updateDesignSorting¶

Update the sorting settings of a page design: toggle whether visitors are offered sort options, and/or replace the complete list of sort options. At least one of the two must be provided; sortingSettings replaces the current list in full — pass an empty list to clear it. Archived designs cannot be edited; copy them first with pages_copyDesign. Use pages_getDesignSorting first to read the current state before making changes.

Saving follows the same draft rules as pages_updateDesign: DRAFT page configs using the design are updated in place, LIVE ones get a draft and keep serving unchanged, and the affected page configs are reported in the result.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pages_updateDesignSorting",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>",
      "sortingEnabled": true,
      "sortingSettings": [
        {
          "name": "<string>",
          "ascendingText": "<string>",
          "descendingText": "<string>"
        }
      ]
    }
  }
}

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

pages_copyDesign¶

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 page configs, since none references the copy yet. This is the way to customize an archived design, which cannot be edited directly. Use pages_listDesigns to find the source key and edit the copy with pages_updateDesign.

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": "pages_copyDesign",
    "arguments": {
      "websiteUuid": "<string>",
      "sourceKey": "<string>",
      "name": "<string>"
    }
  }
}

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

pages_createDesign¶

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 its templates with pages_updateDesign and its filter/sorting settings with pages_updateDesignFilters and pages_updateDesignSorting. No page config references it yet, so editing it affects nothing until a page config is pointed at it. To start from an existing design instead, use pages_copyDesign.

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": "pages_createDesign",
    "arguments": {
      "websiteUuid": "<string>",
      "name": "<string>"
    }
  }
}

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

Page configs¶

pages_listConfigs¶

List the page configs of a website. One entry is returned per page config; when it 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 page configs. Use the key with pages_getConfig or pages_updateConfig, and the designKey with pages_getDesign or pages_updateDesign.

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

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

pages_getConfig¶

Retrieve the core settings of a page config: the design it renders with, whether out-of-stock products are shown, the product score boost, and the Google Analytics event settings (read-only in these tools). The product selection is split into separate facets; read the product filters with pages_getConfigProductFilters and the boosts with pages_getConfigProductBoosts. 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 pages_updateConfig to read the current state.

urlOverrideCount reports how many URL-specific overrides the page config has; overrides are managed in the dashboard.

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

{
  "key": "<string>",
  "name": "<string>",
  "state": "DRAFT",
  "liveVersionExists": true,
  "archived": false,
  "designKey": "<string>",
  "showOutOfStockProducts": false,
  "productScoreBoost": 0,
  "filteredByGroupingKey": false,
  "urlOverrideCount": 0,
  "gaEvents": {
    "enabled": false,
    "clickCategory": "<string>",
    "clickAction": "<string>",
    "clickLabel": "<string>",
    "viewCategory": "<string>",
    "viewAction": "<string>",
    "viewLabel": "<string>"
  },
  "lastModified": "<string>"
}

pages_updateConfig¶

Update the core settings of a page config: its name, the design it renders with, whether out-of-stock products are shown, and the product score boost. All fields are optional and updates are partial: omitted fields are left unchanged, but at least one must be provided. The product selection is split into separate facets; update the product filters with pages_updateConfigProductFilters and the boosts with pages_updateConfigProductBoosts. Use pages_getConfig first to read the current state before making changes.

The edit never touches the serving version: a LIVE page config gets a draft created with the changes (draftCreated: true in the result), and one 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": "pages_updateConfig",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>",
      "designKey": "<string>"
    }
  }
}

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

pages_getConfigProductFilters¶

Get the product filters of a page config: the ordered list of conditions selecting which products appear on the page. Use this before pages_updateConfigProductFilters 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 field names refer to product fields; use dataFields_getProductFields to see which fields exist.

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

{
  "productFilters": [
    {
      "field": "<string>",
      "operator": "EQ",
      "valueType": "LITERAL",
      "value": "<string>"
    }
  ]
}

pages_updateConfigProductFilters¶

Replace the product filters of a page config: the conditions selecting which products appear on the page. The given list replaces the current one in full; pass an empty list to clear it. Use pages_getConfigProductFilters first to read the current state before making changes.

The edit never touches the serving version: a LIVE page config gets a draft created with the changes, and one that already has a draft gets that draft edited.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pages_updateConfigProductFilters",
    "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>"
}

pages_getConfigProductBoosts¶

Get the boosts of a page config: the product boosts (products whose field matches a value are boosted by an amount) and personalized boosts (products matching the visitor's affinity for a field are boosted by an amount) ordering the page's products. Use this before pages_updateConfigProductBoosts to read the current state.

Boost field names refer to product fields; use dataFields_getProductFields to see which fields exist.

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

{
  "productBoosts": [
    {
      "field": "<string>",
      "value": "<string>",
      "boost": 0
    }
  ],
  "personalizedBoosts": [
    {
      "field": "<string>",
      "boost": 0
    }
  ]
}

pages_updateConfigProductBoosts¶

Replace the boosts of a page config: the product boosts and/or personalized boosts ordering the page's products. At least one of the two lists must be provided; each given list replaces the current one in full — pass an empty list to clear it, omit it to leave it unchanged. Use pages_getConfigProductBoosts first to read the current state before making changes.

The edit never touches the serving version: a LIVE page config gets a draft created with the changes, and one that already has a draft gets that draft edited.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pages_updateConfigProductBoosts",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>",
      "productBoosts": [
        {
          "field": "<string>",
          "value": "<string>",
          "boost": 0
        }
      ]
    }
  }
}

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

pages_createConfig¶

Create a new page config: a product-listing page that selects products via filters and boosts and renders them with a page design. The page config is created in DRAFT state and serves nothing until published from the dashboard. Use pages_listDesigns to find a design key (or create one with pages_createDesign), and dataFields_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": "pages_createConfig",
    "arguments": {
      "websiteUuid": "<string>",
      "name": "<string>",
      "designKey": "<string>",
      "productFilters": [
        {
          "field": "hierarchies",
          "operator": "ANY",
          "valueType": "INPUT"
        }
      ]
    }
  }
}

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

pages_copyConfig¶

Copy a page config into a new, independent page config. The copy starts from the source'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 pages_listConfigs 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": "pages_copyConfig",
    "arguments": {
      "websiteUuid": "<string>",
      "sourceKey": "<string>",
      "targetWebsiteUuid": "<string>"
    }
  }
}

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