Request recommendations

You send the moment, the placement and the shopper’s context; a recommendation comes back with full products, ready to display.

The request

const decision = await crossup.tryGetRecommendations({
  surface: "cart",                        // right after adding to the cart
  placementKey: "cart-frequently-bought", // your label for the spot, for traceability
  contextItemId: added.id,                // the product just added
  cartItems: cart.lines.map(toCartItem),  // the cart, as it is
});

What each moment needs: The six moments.

RecommendationSurface

required

pdp, cart (right after adding to the cart), carousel (the cart page), checkout, in-checkout or success-page.

string

required

A label you define to know where the request came from. It’s for your own traceability; it doesn’t change the recommendation.

string

The starting product. Required in , and, without a cart, in .

CartItem[]

{ item_id, variant_id, quantity } per line. Omitted is the same as empty. Required in the cart moments.

Visitor | false

A visitor for this request only, or false to not send one. By default, the instance’s.

isShooterSurface(surface) tells you whether the moment starts from a product.

What comes back

The recommendation comes back (in the API, Decision: the list of products recommended for that moment).

decision.decision_id   // unique per response; signals reference it
decision.results       // in order, with position from 1
decision.reason_codes  // why it came back this way
decision.context       // the product or the cart you sent

const { product } = decision.results[0];
product?.item.title                // per language: { en: "T-shirt" }
product?.variants[0]?.price        // amount as text, or no price
product?.availability[0]?.sellable // text, never a boolean

product carries the item, categories, variants with prices and availability: enough to display it. If it couldn’t be read, it’s missing and that result is skipped. There is no score: the order is the ranking.

The description travels as the platform sends it. Tiendanube sends HTML: sanitize it before inserting it.

Read the catalog

For a result without product, or a product outside the recommendation:

const product = await crossup.tryGetCatalogItem("itm_…"); // or null

The title is per language, sellable is text and a missing quantity isn’t zero: Read a catalog item.

Report signals

What comes after displaying the recommendation.

The six moments

What each moment’s request needs.

​The request

​What comes back

​Read the catalog

Report signals

The six moments

The request

What comes back

Read the catalog