Your first recommendation in 20 minutes

By the end of this page you’ll have a CrossUp recommendation in your store and an accepted signal. You need your catalog in CrossUp, through the app or a connector, and twenty minutes.

Generate your key in the admin

In the admin: Settings → Keys for your storefront → Generate key. Copy the key and your connection identifier. The key goes in the browser: why that’s safe.

Can’t find the connection identifier? Ask support: there’s one per store.

Install the SDK, or get ready to call the API

In JavaScript, the SDK handles the visitor, the signal queue and retries. From any other language the API is enough: HTTP, JSON and the key in Authorization.

npm install @crossup/storefront

The package on npm: @crossup/storefront.

Request a recommendation

Tell CrossUp which moment the shopper is in and with what context. The recommendation comes back (in the API, Decision: the list of products recommended for that moment).

import { createStorefront } from "@crossup/storefront";

const crossup = createStorefront({ apiKey: "spk_…", connectionId: "cn_…" });

const decision = await crossup.tryGetRecommendations({
  surface: "pdp",              // the moment
  placementKey: "pdp-related", // the placement name
  contextItemId: item.id,      // the product the shopper is viewing
});
// null if something failed; results may be empty. Both are normal.

body := map[string]any{
    "connection_id":   "cn_…",
    "surface":         "pdp",         // the moment
    "placement_key":   "pdp-related", // the placement name
    "context_item_id": itemID,        // the product the shopper is viewing
}
req, _ := http.NewRequest("POST", base+"/v1/recommendations", toJSON(body))
req.Header.Set("Authorization", "Bearer spk_…")
resp, err := http.DefaultClient.Do(req)
// 200 with the decision; empty results are valid too.

Use the recommendation

Every product comes complete, no extra call. The design is yours, with two rules: if it’s empty, show nothing; if there’s no price, don’t show $ 0.

for (const result of decision?.results ?? []) {
  const product = result.product;
  if (!product) continue;               // couldn't be read: skip it
  // product.item.title               → by language: { en: "T-shirt" }
  // product.variants[0]?.price       → amount as text, or no price
  // product.availability[0]?.sellable → a text like "in_stock"; never a boolean
}

for _, result := range decision.Results {
    if result.Product == nil { continue } // couldn't be read: skip it
    // Price is nil when there's no price; Sellable is a text, never a boolean
}

Report the first signal

Without signals, CrossUp can’t tell the recommendation was seen or that it sold. Report when it’s shown and when the shopper opens it.

crossup.track.impression(decision);          // it was shown
crossup.track.click(decision, result);       // the shopper opened a product
// Neither waits on the network or throws: call and move on.

// From a server, the one that matters most: the purchase, when the order closes.
// POST {base}/v1/connections/{cn}/storefront-signals (fields in Signals and attribution)

What you will see

On your page, the recommended products in your design. In the Network tab, a request that returns a decision_id (the recommendation’s id) and, a few seconds later, a signal send that returns accepted.

If you don’t see it

What happens	What it means	What to do
`401`	The key didn’t arrive or isn’t valid	Check the header and that it isn’t revoked
`403`	The connection belongs to another store	Use the identifier from the same store
`404`	The product doesn’t exist or belongs to another store	Check the key before the id
`429`	More than 60 requests per minute	Wait for what `Retry-After` says
Empty, with a reason	The moment isn’t on, or there’s no offer	Check the reason in `reason_codes`
`null` from the SDK	Network down, timeout or engine unavailable	Nothing: the page carries on

Signals and attribution

The seven signals and how the sale is measured.

Request recommendations

Each moment with its request and what comes back.

Get started

Operate

Your first recommendation in 20 minutes

What you will see

If you don’t see it

Signals and attribution

Request recommendations

​What you will see

​If you don’t see it

Signals and attribution

Request recommendations

What you will see

If you don’t see it