The six moments

A recommendation can show up at six moments, from the product page to the thank-you page. In the API each moment is a surface with its own context.

The six, with what each one needs

Two names are misleading: cart is after add to cart, the popup right after a product goes in. carousel is the cart page.

Moment	`surface`	What the request needs
	`pdp`	the product being viewed
	`cart`	the product just added
	`carousel`	the cart
	`checkout`	the product, or the cart
	`in-checkout`	the cart
	`success-page`	the cart

pdp, cart and checkout start from the starting product, the one the shopper is viewing or just added. The other three read the cart. If the request lacks what its moment needs, you get an error naming the field.

The placement name

Every request also carries a placementKey: a label you define to know which spot in your store each request came from. It’s for your own traceability and internal control; it doesn’t change the recommendation.

pdp-related        cart-frequently-bought        checkout-last-chance

How to request it

const decision = await crossup.tryGetRecommendations({
  surface: "pdp",              // the moment
  placementKey: "pdp-related", // your label for the spot, for traceability
  contextItemId: item.id,      // the starting product; cart moments take cartItems
});

body := map[string]any{
    "connection_id":   connectionID,
    "surface":         "pdp",         // the moment
    "placement_key":   "pdp-related", // your label for the spot, for traceability
    "context_item_id": itemID,        // the starting product; cart moments take cart_items
}
// POST {base}/v1/recommendations · Authorization: Bearer spk_…

What you will see

A recommendation with results and, in context, the product or cart exactly as you sent it.

If you don’t see it

What happens	Why	What to do
Empty, “moment not turned on”	The store hasn’t turned that moment on	Turn it on in the admin, under Moments
Error “product missing”	The moment starts from a product	Send the starting product
A product in a cart moment	It’s recorded but doesn’t change the recommendation	Send the cart

Your first recommendation

From the key to the first recommendation, in 20 minutes.

Request recommendations with the SDK

Each moment, with its request.

Get started

Operate

The six moments

The six, with what each one needs

The placement name

How to request it

What you will see

If you don’t see it

Your first recommendation

Request recommendations with the SDK

​The six, with what each one needs

​The placement name

​How to request it

​What you will see

​If you don’t see it

Your first recommendation

Request recommendations with the SDK

The six, with what each one needs

The placement name

How to request it

What you will see

If you don’t see it