Recommendations¶

Create a recommendation from one of Hello Retail's best-practice algorithms, list the recommendations on a website, read and change the algorithm that decides which products they show, along with their settings, placement, Google Analytics events and context crawl config, edit the designs they render with, copy a design as a starting point, and point recommendations 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 recommendations on my website, then show the general settings and placement of the one on the cart page.

Set recommendation <KEY> to show 6 products on mobile only, and rename it "Cart upsell".

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

Read docs://crawl-strings/syntax, then make recommendation <KEY> read the brand from the .product-brand element so the strategy can filter on it.

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

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

Read docs://product-algorithms/format, then show me the algorithm behind recommendation <KEY> and explain what each step contributes.

Show me the best practice algorithms for a product page, then create one using "Related products".

recoms_list¶

List the recommendations of a customer website using Hello Retail. Returns LIVE and DRAFT recommendations by default; pass includeArchived=true to also include archived ones. Each row carries the key, name, type, state, whether it is a draft, the key of the design it renders with and when it last changed. Type and state are the enum names the update tools take, such as FRONT_PAGE and LIVE. Read the rest with recoms_getAlgorithm, recoms_getGeneralSettings, recoms_getGoogleAnalyticsSettings, recoms_getPlacement and recoms_getContextCrawlConfig.

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

{
  "recoms": [
    {
      "key": "<string>",
      "name": "<string>",
      "type": "FRONT_PAGE",
      "state": "LIVE",
      "draft": false,
      "designKey": "<string>",
      "lastModified": "<string>"
    }
  ]
}

recoms_create¶

Create a recommendation, the same way the dashboard's Create new menu does: pick the page it is for and one of Hello Retail's best-practice algorithms, and the recommendation starts with that algorithm's steps. Use recoms_listBestPracticeAlgorithms to see which algorithms a page type offers and what each one does.

The new recommendation is a DRAFT and shows nothing until it is published. It is named after the algorithm it started from, Retargeted - Box 1, and renaming it is recoms_updateGeneralSettings, the same second step as in the dashboard. It renders with the website's default design and attaches at its own default selector; placementDivExample is the element the shop pastes into the page where the recommendation should appear.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "recoms_create",
    "arguments": {
      "websiteUuid": "<string>",
      "type": "PRODUCT_PAGE",
      "algorithmName": "Related products"
    }
  }
}

{
  "id": "<string>",
  "key": "<string>",
  "name": "Related products - Box 1",
  "type": "PRODUCT_PAGE",
  "state": "DRAFT",
  "algorithmName": "Related products",
  "designKey": "<string>",
  "placementDivExample": "<div id=\"hr-recom-<key>\"></div>",
  "lastModified": "<string>"
}

recoms_getGeneralSettings¶

Read the general settings of a recommendation: name, type, number of products, the devices it shows on, load order, Retail Media mode, whether the template renders when no products are found, and whether it is locked. The values come back exactly as recoms_updateGeneralSettings accepts them.

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

{
  "key": "<string>",
  "state": "DRAFT",
  "name": "<string>",
  "type": "PRODUCT_PAGE",
  "productCount": 4,
  "responsiveMode": "BOTH",
  "priority": 5,
  "retailMediaInjectionMode": "ALL",
  "renderIfEmpty": false,
  "locked": false,
  "lastModified": "<string>"
}

recoms_updateGeneralSettings¶

Update the general settings of a recommendation, the fields of the General section in the editor. Updates are partial: omitted fields are left unchanged, but at least one must be provided. Editing a LIVE recommendation 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_getGeneralSettings first to read the current values. Publishing is not possible through this tool.

A few values are checked before anything is saved. The name must not be blank. The retired LEGACY type cannot be selected. You can show up to 20 products, or keep a higher count the recommendation already has. retailMediaInjectionMode requires Retail Media on your agreement; without it the call is refused and your assistant can ask Hello Retail to get in touch.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "recoms_updateGeneralSettings",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>",
      "productCount": 6,
      "responsiveMode": "MOBILE"
    }
  }
}

{
  "key": "<string>",
  "state": "DRAFT",
  "name": "<string>",
  "type": "PRODUCT_PAGE",
  "productCount": 6,
  "responsiveMode": "MOBILE",
  "priority": 5,
  "retailMediaInjectionMode": "ALL",
  "renderIfEmpty": false,
  "locked": false,
  "draftCreated": true,
  "lastModified": "<string>"
}

recoms_getAlgorithm¶

Read the algorithm of a recommendation: the ordered steps that fill it, the global filters every step draws through, and whether product variants count as one product. This is the Strategy section of the recommendation editor. productCount is the number of slots the steps fill, and filterableFields lists the product fields a filter or condition on this recommendation may name, which is the website's own filterable fields plus every field its context crawl config defines. matchesBestPractice names the best-practice algorithm the steps are still running unchanged, and is null once they have been tuned. Each step carries all of its possible fields, with the ones its productType does not use set to null. The format is documented in docs://product-algorithms/format; read it before making sense of what comes back. Edit with recoms_updateAlgorithm, or replace the steps wholesale with recoms_applyBestPracticeAlgorithm.

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

{
  "key": "<string>",
  "state": "LIVE",
  "type": "PRODUCT_PAGE",
  "productCount": 6,
  "filterByGroupingKey": true,
  "filters": [
    { "field": "inStock", "operator": "EQUALS", "value": "true" }
  ],
  "steps": [
    {
      "productType": "BOUGHT_TOGETHER",
      "productLimit": 0,
      "onlyOffers": false,
      "excludeProducts": false,
      "useAsContext": false,
      "filters": [],
      "condition": null,
      "skipDaysAgo": null,
      "numberDaysAgo": null,
      "numberReceipts": null,
      "skipReceipts": null,
      "productIds": null,
      "relatedTo": null,
      "searchTerm": null,
      "priceInfluence": 0.25
    },
    {
      "productType": "TOP",
      "productLimit": 0,
      "onlyOffers": false,
      "excludeProducts": false,
      "useAsContext": false,
      "filters": [
        { "field": "hierarchies", "operator": "IN", "value": "$hierarchies" }
      ],
      "condition": null,
      "skipDaysAgo": null,
      "numberDaysAgo": null,
      "numberReceipts": null,
      "skipReceipts": null,
      "productIds": null,
      "relatedTo": null,
      "searchTerm": null,
      "priceInfluence": null
    }
  ],
  "matchesBestPractice": "Related products",
  "filterableFields": ["pi.productCluster", "pi.budgetZone", "price", "inStock", "brand", "hierarchies"],
  "lastModified": "<string>"
}

recoms_updateAlgorithm¶

Change the algorithm of a recommendation. Read docs://product-algorithms/format first: it holds every step type with the extra fields it carries, the filter operators and $context expressions, the run conditions and worked examples. To start from a proven setup instead of writing steps by hand, use recoms_listBestPracticeAlgorithms and recoms_applyBestPracticeAlgorithm.

Updates are partial, and each argument replaces its part whole. Omitted arguments are left unchanged, but at least one must be given. Passing steps replaces every step, so read the current ones with recoms_getAlgorithm and send them back with your edits; a recommendation must keep at least one step, since one saved with none is read back as a default Top products box. An input the engine cannot run is refused with the path of the offending step, such as steps[1].searchTerm is not a field of a TOP step, and nothing is saved. Input that is storable but probably not what you meant, such as a filter on a field the website cannot filter on, is saved and reported in warnings.

Each step has these fields. Only the extras belonging to its own productType may be set; another type's extra is refused rather than ignored.

Each filter, global or per step, has these fields:

A literal has to match the catalogue exactly, and guessing it is the usual reason a filter matches nothing. productData_getFieldValues lists the values a field actually has — the only practical way to get a hierarchy right, since they are $-separated (kids$shoes is Kids > Shoes). It reads the search index, so it answers only for fields indexed for search and not at all for range fields like price.

A condition is one of five shapes:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "recoms_updateAlgorithm",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>",
      "steps": [
        {
          "productType": "RETARGETED",
          "productLimit": 3,
          "useAsContext": true,
          "skipDaysAgo": 1,
          "numberDaysAgo": 30
        },
        {
          "productType": "ALTERNATIVES",
          "priceInfluence": 0.5,
          "filters": [
            { "field": "price", "operator": "LESS_THAN", "value": "$user.avgPrice * 1.2" }
          ]
        },
        {
          "productType": "TOP",
          "filters": [
            { "field": "brand", "operator": "EQUALS", "value": "$user.bias.brand" }
          ],
          "condition": {
            "type": "COMPARE",
            "field": "user.bias.brand",
            "operator": "NE",
            "value": ""
          }
        }
      ],
      "filters": [
        { "field": "inStock", "operator": "EQUALS", "value": "true" }
      ]
    }
  }
}

{
  "key": "<string>",
  "state": "DRAFT",
  "filterByGroupingKey": true,
  "filters": [
    { "field": "inStock", "operator": "EQUALS", "value": "true" }
  ],
  "steps": [
    { "productType": "RETARGETED", "productLimit": 3, "useAsContext": true, "skipDaysAgo": 1, "numberDaysAgo": 30 },
    { "productType": "ALTERNATIVES", "priceInfluence": 0.5 },
    { "productType": "TOP" }
  ],
  "warnings": [],
  "draftCreated": true,
  "lastModified": "<string>"
}

recoms_listBestPracticeAlgorithms¶

List the algorithms Hello Retail recommends for a kind of recommendation: the step sequences the dashboard offers when a recommendation is created or its type is changed. Each entry carries a name, one line on which products it puts in the recommendation, and its steps, so you can apply it as it stands with recoms_applyBestPracticeAlgorithm or adapt it and write it back with recoms_updateAlgorithm. Which ones exist depends on the type: a product page can use the ones about the product on the page, a front page cannot.

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

{
  "type": "PRODUCT_PAGE",
  "typeTitle": "Product page",
  "algorithms": [
    {
      "name": "Retargeted",
      "description": "Products this visitor has looked at, topped up with related picks",
      "steps": [
        { "productType": "RETARGETED" },
        { "productType": "BOUGHT_WITH", "relatedTo": "RETARGETED" },
        { "productType": "VIEWED_WITH", "relatedTo": "RETARGETED" },
        { "productType": "TOP" }
      ]
    },
    {
      "name": "Related products",
      "description": "Bought and viewed together with the product on the page",
      "steps": [
        { "productType": "BOUGHT_TOGETHER" },
        { "productType": "RELATED", "filters": [{ "field": "hierarchies", "operator": "NOT_IN", "value": "$hierarchies" }] },
        { "productType": "RELATED" }
      ]
    }
  ]
}

recoms_applyBestPracticeAlgorithm¶

Replace the steps of a recommendation with one of Hello Retail's best practice algorithms for its type, by name. Use recoms_listBestPracticeAlgorithms to see the names and what each one does; an unknown name is refused and the available ones are listed back.

Only the steps are replaced. The recommendation's global filters and filterByGroupingKey are kept, since they are the shop's own rules rather than part of what the algorithm recommends. Adapt the result afterwards with recoms_updateAlgorithm if it needs the recommendation's own filters or limits.

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

{
  "key": "<string>",
  "state": "DRAFT",
  "name": "Related products",
  "steps": [
    { "productType": "BOUGHT_TOGETHER" },
    { "productType": "RELATED", "filters": [{ "field": "hierarchies", "operator": "NOT_IN", "value": "$hierarchies" }] },
    { "productType": "RELATED" }
  ],
  "warnings": [],
  "draftCreated": true,
  "lastModified": "<string>"
}

recoms_getGoogleAnalyticsSettings¶

Read the Google Analytics settings of a recommendation: whether it sends events, the category, action and label of the click event and of the view event, and the extra query parameters appended to product links. The values come back exactly as recoms_updateGoogleAnalyticsSettings accepts them.

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

{
  "key": "<string>",
  "state": "LIVE",
  "gaEventEnabled": true,
  "gaEventCategory": "helloretail",
  "gaEventAction": "Recom click",
  "gaEventLabel": "<string>",
  "gaViewEventCategory": "helloretail",
  "gaViewEventAction": "Recom view",
  "gaViewEventLabel": "<string>",
  "extraLinkParams": "",
  "lastModified": "<string>"
}

recoms_updateGoogleAnalyticsSettings¶

Update the Google Analytics settings of a recommendation, the fields of the Google Analytics section in the editor. Updates are partial: omitted fields are left unchanged, but at least one must be provided; pass an empty string to clear a text field. Labels are sent prefixed with the recommendation type's title, for example Product page - <label>. A new recommendation starts with category helloretail, actions Recom click and Recom view, and its name as both labels; the dashboard's UTM suggestion for extraLinkParams is utm_source=helloretail&utm_medium=productbox&utm_campaign=<url-encoded name>. Editing a LIVE recommendation automatically creates a draft and leaves it in DRAFT state for review. Use recoms_getGoogleAnalyticsSettings first to read the current values. Publishing is not possible through this tool.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "recoms_updateGoogleAnalyticsSettings",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>",
      "extraLinkParams": "utm_source=helloretail&utm_medium=productbox&utm_campaign=cart-upsell"
    }
  }
}

{
  "key": "<string>",
  "state": "DRAFT",
  "gaEventEnabled": true,
  "gaEventCategory": "helloretail",
  "gaEventAction": "Recom click",
  "gaEventLabel": "<string>",
  "gaViewEventCategory": "helloretail",
  "gaViewEventAction": "Recom view",
  "gaViewEventLabel": "<string>",
  "extraLinkParams": "utm_source=helloretail&utm_medium=productbox&utm_campaign=cart-upsell",
  "draftCreated": true,
  "lastModified": "<string>"
}

recoms_getPlacement¶

Read where and how a recommendation is placed on the page: the CSS selector it attaches to, the selectorMode deciding when that selector is evaluated, the insertMode deciding how it is inserted relative to the matched element, whether the selector is the default one, what that default is, and placementDivExample, the <div id="hr-recom-<key>"></div> you paste into your page where the recommendation should render by default. Change the first three with recoms_updatePlacement.

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

{
  "key": "<string>",
  "state": "LIVE",
  "selector": "#hr-recom-<key>",
  "selectorMode": "NORMAL",
  "insertMode": "REPLACE",
  "usingDefaultSelector": true,
  "defaultSelector": "#hr-recom-<key>",
  "placementDivExample": "<div id=\"hr-recom-<key>\"></div>",
  "lastModified": "<string>"
}

recoms_updatePlacement¶

Update where a recommendation is placed on the page: the CSS selector it attaches to, the selectorMode deciding when that selector is evaluated, and the insertMode deciding how it is inserted relative to the matched element. These fields only matter when Hello Retail renders the recommendation 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 recommendation 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_getPlacement first to read the current placement. Publishing is not possible through this tool.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "recoms_updatePlacement",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>",
      "selector": ".product-description",
      "insertMode": "AFTER"
    }
  }
}

{
  "key": "<string>",
  "state": "DRAFT",
  "selector": ".product-description",
  "selectorMode": "NORMAL",
  "insertMode": "AFTER",
  "draftCreated": true,
  "lastModified": "<string>"
}

recoms_getContextCrawlConfig¶

Read the context crawl config of a recommendation as crawl strings. The config runs in the visitor's browser on the page the recommendation renders on and extracts values from it; every field it defines is available to the recommendation's strategy as a filter value, $input.<field>. crawlStrings is an empty string when the recommendation crawls nothing, and null when the stored config cannot be rendered as crawl strings, in which case recoms_updateContextCrawlConfig cannot edit it either. fieldNames lists the fields the config defines. The syntax is documented in docs://crawl-strings/syntax.

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

{
  "key": "<string>",
  "state": "LIVE",
  "crawlStrings": "brand: $(\".product-brand\").text().trim()\nprice: $(\".price\").text().replace(\",\", \".\")",
  "fieldNames": ["brand", "price"]
}

recoms_updateContextCrawlConfig¶

Replace the context crawl config of a recommendation with the given crawl strings; pass an empty string to remove it. Read docs://crawl-strings/syntax first: it holds the line shape, the field names a recommendation may define, selectors, processors and annotations. The text is parsed server-side, and the first syntax error rejects the call with its line, so nothing is saved. Deprecated field names still parse and come back in warnings. Editing a LIVE recommendation automatically creates a draft and leaves it in DRAFT state for review. Use recoms_getContextCrawlConfig first to read the current config. Publishing is not possible through this tool.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "recoms_updateContextCrawlConfig",
    "arguments": {
      "websiteUuid": "<string>",
      "key": "<string>",
      "crawlStrings": "brand: $(\".product-brand\").text().trim()"
    }
  }
}

{
  "key": "<string>",
  "state": "DRAFT",
  "crawlStrings": "brand: $(\".product-brand\").text().trim()",
  "fieldNames": ["brand"],
  "warnings": [],
  "draftCreated": true,
  "lastModified": "<string>"
}

recoms_updateSelectedDesign¶

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

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

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

{
  "designKey": "<string>",
  "recoms": [
    {
      "key": "<string>",
      "state": "DRAFT",
      "outcome": "UPDATED",
      "draftCreated": true,
      "lastModified": "<string>"
    },
    {
      "key": "<string>",
      "state": "LIVE",
      "outcome": "UNCHANGED",
      "draftCreated": false,
      "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_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) that recommendations render with. 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 recommendation 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>",
      "templateStyles": "<string>"
    }
  }
}

{
  "key": "<string>",
  "designId": 0,
  "title": "<string>",
  "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 recommendations at it with recoms_updateSelectedDesign.

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