Recommendations¶

Review recommendation boxes, edit their designs, and control where each box is placed on the page.

List the recommendation boxes for my website, then show the design for one of them.

Show the HTML and CSS for recommendation design <KEY> on my website.

Move recommendation box <KEY> so it appears right after the element matching .product-description.

getRecommendationDesign¶

Retrieve the design (template and styles) for a customer website using Hello Retail. Use this before updateRecommendationDesign to read the current state of the design.

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

{
  "key": "<string>",
  "title": "<string>",
  "templateCode": "<string>",
  "templateStyles": "<string>"
}

updateRecommendationDesign¶

Update the design (template and styles) of a recommendation box for a customer website using Hello Retail. Edits the design with the given key. templateCode and templateStyles are optional and updates are partial: omitted fields are left unchanged, but at least one of them must be provided. Saving a design automatically creates a draft of any LIVE boxes using it, leaving them in DRAFT state for review. Use getRecommendationDesign first to read the current state before making changes. Publishing is not possible through this tool.

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

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

listRecommendationDesigns¶

List all designs available to a website: the company's custom designs (including archived ones) and the shared standard designs. Returns key, title, archived/standard flags and last-modified for each design. Use the key with getRecommendationDesign or updateRecommendationDesign. Archived and standard designs are read-only.

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

{
  "designs": [
    {
      "key": "<string>",
      "title": "<string>",
      "archived": false,
      "standard": false,
      "lastModified": "<string>"
    }
  ]
}

listRecommendationBoxes¶

List recommendation boxes for a customer website using Hello Retail. Returns LIVE and DRAFT boxes by default; pass includeArchived=true to also include archived boxes. Each box's designKey identifies the design it renders with; use it with getRecommendationDesign or updateRecommendationDesign to inspect or edit that design. Each box also includes its placement (selector, selectorMode, insertMode, and usingDefaultSelector); change it with updateRecommendationBoxPlacement.

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

{
  "boxes": [
    {
      "key": "<string>",
      "name": "<string>",
      "type": "<string>",
      "state": "<string>",
      "draft": false,
      "designKey": "<string>",
      "selector": "<string>",
      "selectorMode": "<string>",
      "insertMode": "<string>",
      "usingDefaultSelector": false,
      "lastModified": "<string>"
    }
  ]
}

updateRecommendationBoxPlacement¶

Update where a recommendation box is placed on the page for a customer website using Hello Retail: the CSS selector the box attaches to, the selectorMode deciding when that selector is evaluated, and the insertMode deciding how the box is inserted relative to the matched element. These fields only matter when Hello Retail renders the box with a managed template; they have no effect if you fetch recommendations through the API and render them yourself. Updates are partial: omitted fields are left unchanged, but at least one of them must be provided. Passing an empty string as selector resets it to the default #hr-recom-<key>. Editing a LIVE box automatically creates a draft and leaves it in DRAFT state for review; if the key already has a draft, that draft is edited instead. The draftCreated field in the response tells you whether a new draft was created. Use listRecommendationBoxes first to read the current placement. Publishing is not possible through this tool.

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

{
  "key": "<string>",
  "state": "<string>",
  "selector": "<string>",
  "selectorMode": "<string>",
  "insertMode": "<string>",
  "draftCreated": false,
  "lastModified": "<string>"
}