Recommendations Connector

Get frequently-bought-together, related, trending and collaborative-filtering recommendations from your own order history, and record the views, clicks, cart adds, purchases and feedback that train and measure them.

Open in Claude

Browse 6 Recommendations actions database

On this page

What this connector is for Get Recommendations Record events How items are described Record Recommendation Feedback Common tasks Step Name Step Reference Execution Settings Caching

What this connector is for

Serves recommendations (frequently bought together, related by similarity, trending and, once order history exists, collaborative filtering) computed from your own store's order and interaction history. No connection is needed: recommendation sets belong to your store, the same way search indexes do.

A recommendation set (created and managed on the designer's Recommendations page, see Managing recommendations) holds the actual configuration: which strategies are on and how each is tuned, manual pin/exclude overrides, and whether an Index is attached for related-by-similarity. This connector reads from a set and feeds it events; it has no settings of its own beyond which set to use. Every action returns a plain result, read as {{<stepReference>.response.data.<field>}}.

Every action, with its fields, is listed in the action reference.

Get Recommendations

Reads recommendations for a product page or a whole cart.

A strategy must already be turned on for the set. Calling one that isn't, or calling any strategy on a set that has been deactivated in Settings, fails with a clear error rather than returning an empty list.
frequently_bought_together: items bought in the same order as the anchor.
collaborative_filtering: items bought by similar customers, even across separate orders.
related_by_similarity: items whose content is similar, answered live from a Search Index attached to the set. Works from day one with no order history; fails with a clear error if no Index is attached.
trending: what's selling now. The anchor is a scope rather than an item: "__global__" for store-wide, or "<facet>:<value>" such as "category:snowboards" if the strategy has a facet configured.
Cart items take precedence over a single anchor. Results are pooled across the cart and an item's score is summed across every cart item it's associated with, rewarding something complementary to several items over one that matches a single item strongly. Anything already in the cart is excluded.
Manual pins and excludes from the designer's Overrides tab are applied automatically.

Response:

{{<stepReference>.response.data.requestId}}: unique id for this call. Keep it and pass it to Record Recommendation Feedback if a shopper clicks or buys a returned item, so the Overview tab can attribute it.
{{<stepReference>.response.data.items}}: array of {itemKey, score}, best first. These are bare ids only; resolve title, price and image with a Search action or your own catalog lookup in a second step.

Record events

Record Product View, Record Product Click, Record Add To Cart and Record Purchase are fire-and-forget logging. They feed future recommendations, not the response to the request that triggered them. Each returns {{<stepReference>.response.data.recorded}}, the number of items recorded (always 1 for view and click).

Record Purchase is the data every precomputed strategy (frequently bought together, collaborative filtering, trending) learns from. Send it once per order with every item, or once per line item repeating the same Order ID; lines sharing an Order ID are grouped as one order. Leave the customer id empty for a guest checkout or anonymous visitor.

How items are described

Record Add To Cart and Record Purchase take Items in the same shape: a JSON array of {itemKey, quantity, price, attributes} objects, or a comma-separated list of item keys when only the key matters. A single item still goes in as a one-entry list. attributes is a free-form object of facets for that item, such as {"category":"snowboards"}, which lets trending's optional facet scoping read it back later. Currency is only meaningful when a price is set on an item.

Record Recommendation Feedback

Tells a set that a shopper clicked or bought an item that Get Recommendations returned, using that call's requestId. This feeds the click-through and conversion figures on the designer's Overview tab; without it, recommendations can be served but never measured. Attribution is best-effort: an unrecognised or expired requestId is still recorded, it just won't carry the strategy information for the per-strategy breakdown, so a real click is never rejected because its request aged out. Returns recorded (always 1).

Common tasks

Cross-sell on a product page, with measurement:

Get Recommendations (step "Get Cross Sell", reference getCrossSell) with strategy frequently_bought_together and the product as the anchor.
Return {{getCrossSell.response.data.items}} and {{getCrossSell.response.data.requestId}} to the storefront.
When the shopper clicks one, call Record Recommendation Feedback with type click and Request Id {{getCrossSell.response.data.requestId}}.
On checkout, call Record Purchase so the strategies keep learning.

Also applies here

Step Name

What it's for

Every step in a workflow gets a name — either one you set or a default based on the connector and action (e.g. "Get Order Details", "Send Welcome Email"). It's shown throughout the UI and in your execution history, and it's also the source for the step's Reference — a camelCase identifier auto-generated from the name (e.g. "Get Order Details" → getOrderDetails) — which is what you actually use in {{...}} expressions to read this step's output from later steps. See Step Reference.

Rules

Must be at least 2 characters, and 50 characters or fewer.
Must be unique within the workflow — reusing a name that's already taken will be rejected, with a suggested alternative (e.g. "Get Order Details 2").
Can't be empty.

Tips

Prefer a descriptive, human-readable name over a generic one — "Get Order Details" is easier to work with later than "HTTP Request 2", especially once a workflow has a dozen steps.
Renaming a step updates every reference to it elsewhere in the workflow automatically.

Step Reference

Syntax

Any input field can reference earlier data using {{expression}}. The expression is evaluated as JSONata — so simple dot-paths and more advanced queries (filters, functions) both work.

Referencing a step's output

Use the step's Reference — a camelCase identifier auto-generated from its Name (e.g. "Get Order Details" → getOrderDetails), shown read-only wherever the step's fields are configured — followed by the field path. Elsewhere in these docs this general pattern is written as {{<stepReference>.field.path}}:

text

{{getOrderDetails.response.data.id}}
{{getOrderDetails.response.status}}

The raw display name won't work here even though it's what you see in the UI — {{Get Order Details.response.data.id}} isn't valid, since a bare name containing spaces isn't a single JSONata identifier. Always use the camelCase Reference.

You can also reference steps by position instead of by reference:

text

{{steps[0].response.data.id}}

Referencing trigger data

text

{{trigger.headers.authorization}}
{{trigger.body.customerId}}
{{trigger.query.page}}
{{trigger.params.orderId}}
{{trigger.method}}
{{trigger.path}}

Referencing workflow variables

text

{{variables.myVariable}}

See Variables for the full list of variable types and more examples, including connection-type variables.

Referencing runtime variables

A separate, mutable namespace written by the Variable connector while a run is in progress — not the same as the workflow-level variables above:

text

{{runtimeVariables.myVariable}}

Notes

If an expression can't be resolved (a typo in a step name, a field that doesn't exist), it resolves to an empty string rather than failing the workflow — check your execution history if a value comes through blank.
Object values are automatically JSON-stringified when interpolated into a string field.

Execution Settings

Fire-and-forget

When enabled, the workflow doesn't wait for this step to complete before moving to the next one. Use it for steps whose result nothing downstream depends on — logging, analytics, notifications — so they don't add latency to the steps that matter.

Continue on error

When enabled, a failure in this step doesn't stop the workflow — execution continues to the next step. The failure is still recorded in the execution history; this just controls whether it's fatal.

Combine the two for steps that are genuinely optional to the outcome: fire-and-forget so they don't add latency, continue-on-error so a failure in them (e.g. an analytics endpoint being briefly down) doesn't take down an otherwise-successful workflow run.

Caching

What it does

When enabled, a step's result is cached for a configurable TTL (time-to-live, in seconds). If the step runs again with the same effective cache key before the TTL expires, the cached result is returned instead of re-running the step.

Configuring it

Enabled — turn caching on or off for this step.
TTL — how long (in seconds) a cached result stays valid.
Cache key template — an expression (supporting the same {{...}} step reference syntax used elsewhere) that determines what counts as "the same call". By default this is based on the step's resolved input; a custom template lets you cache more narrowly or broadly than that.

When to use it

Good candidates are steps that call something slow or rate-limited but return the same answer for the same input within a short window — a lookup against a rarely-changing external system, for example. Skip it for steps whose result must always be fresh (anything involving live inventory, pricing, or payment state).

Was this page helpful?

Last updated 9 October 2026