Recommendations¶

Review recommendation boxes, edit their designs, copy a design as a starting point, control where each box is placed on the page, and point boxes at a different design.

Tips & tricks¶

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

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.

Copy the design used by recommendation box <KEY>, make the product titles larger in the copy, and point that box at it.

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

recoms_getDesign¶

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

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

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

recoms_updateDesign¶

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 recoms_getDesign 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": "recoms_updateDesign",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>"
    }
  }
}

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

recoms_listDesigns¶

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 recoms_getDesign or recoms_updateDesign. Archived and standard designs are read-only; copy them with recoms_copyDesign to get an editable design.

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

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

recoms_copyDesign¶

Copy a recommendation design into a new, independent design for a customer website using Hello Retail. The copy starts from the source design's template and styles but gets its own key, so it can be edited without affecting the original. This is useful for customizing a standard or archived design, which cannot be edited directly. Use recoms_listDesigns to find the source key, edit the copy with recoms_updateDesign, and point boxes at it with recoms_updateBoxesDesign.

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

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

recoms_listBoxes¶

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 recoms_getDesign or recoms_updateDesign to inspect or edit that design, or point boxes at a different design with recoms_updateBoxesDesign. Each box also includes its placement (selector, selectorMode, insertMode, and usingDefaultSelector); change it with recoms_updateBoxPlacement.

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

recoms_updateBoxPlacement¶

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 recoms_listBoxes first to read the current placement. Publishing is not possible through this tool.

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

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

recoms_updateBoxesDesign¶

Assign a different design to one or more recommendation boxes of a customer website using Hello Retail. Every listed box is pointed at the design with the given key; use one call for bulk reassignments such as design rollouts, instead of calling once per box. Boxes already using the design are reported UNCHANGED and left untouched, so re-running the same call is safe. Editing a LIVE box automatically creates a draft and leaves it in DRAFT state for review; the per-box draftCreated field tells you when that happened. Use recoms_listBoxes to find box keys and recoms_listDesigns to find design keys; copy a design first with recoms_copyDesign to point boxes at an editable variant. Boxes cannot be pointed at an archived design. Publishing is not possible through this tool.

All boxes are checked before anything is written, so a bad key fails the whole call without changing any box. If a save fails midway, the error says how many boxes earlier in the list were already updated; retry with only the remaining boxes rather than the full list.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "recoms_updateBoxesDesign",
    "arguments": {
      "websiteUuid": "<string>",
      "designKey": "<string>",
      "boxKeys": ["<string>", "<string>"]
    }
  }
}

{
  "designKey": "<string>",
  "boxes": [
    {
      "key": "<string>",
      "state": "<string>",
      "outcome": "UPDATED",
      "draftCreated": true,
      "lastModified": "<string>"
    },
    {
      "key": "<string>",
      "state": "<string>",
      "outcome": "UNCHANGED",
      "draftCreated": false,
      "lastModified": "<string>"
    }
  ]
}