Signals and attribution

Every sale CrossUp brings in is proven by two things: what the shopper added from a recommendation, which arrives as a signal, and the order your store closed. The browser never says a purchase happened: the order does.

What counts as an attributed sale

It’s the value of the products the shopper added from a recommendation and actually bought. Attribution happens order by order. These don’t count:

the product the shopper had already picked;
recommendations that were dismissed;
orders without an accepted recommendation.

The seven signals

Signal	What happened
`impression`	The recommendation was shown
`click`	The shopper opened a recommended product
`add_to_cart`	Added units of that product to the cart
`remove_from_cart`	Removed it from the cart
`update_quantity`	Changed the units; zero means removing it
`checkout_started`	Headed to checkout. It records the moment, not the sale
`dismiss`	Closed the offer without taking it

Each signal carries its own change, never the whole cart. There’s no purchase signal.

How the sale is tied

Your store sends its cart id (cart_id) when asking for the recommendation and with the signals. With the SDK, once: the cartId option.
The cart signals say what the shopper added from each recommendation.
The order arrives from your platform —the CrossUp app or your connector— with that same id as its external_id. CrossUp matches the order against what was added and attributes the lines that were bought.

Without cart_id the recommendation still works, but that decision can’t be tied to any order. How the order has to arrive: The canonical model.

When to report each one

impression when the recommendation enters the screen, not when it’s generated.
click on the click, before navigating; the SDK sends it even if the page changes.
add_to_cart with the quantity added, not the line total.
checkout_started when the shopper heads to checkout, once.

How they’re sent

You report and move on: the SDK batches, sends and retries without holding up the page. Each track.* takes the recommendation you showed (in the API, Decision: the list of products recommended for that moment).

const crossup = createStorefront({
  apiKey: "spk_…",
  connectionId: "cn_…",
  cartId: () => cart?.id,                         // your store's cart id
});

crossup.track.impression(decision);              // it was shown
crossup.track.click(decision, result);           // opened a product
crossup.track.addToCart(decision, result, { quantity: 2 }); // added two units
crossup.track.checkoutStarted(decision);         // headed to checkout

// From a server. Up to 50 signals per send.
batch := map[string]any{"signals": []map[string]any{{
    "signal_id":   newID(),       // sig_…, stable: retrying doesn't duplicate
    "type":        "add_to_cart",
    "decision_id": decisionID,    // the decision that was shown
    "item_id":     itemID,
    "quantity":    2,             // the units added
    "cart_id":     cartID,        // the cart id in your store
    "occurred_at": now,           // RFC 3339, in UTC
}}}
// POST {base}/v1/connections/{cn}/storefront-signals · Authorization: Bearer spk_…

Retrying is safe: every signal has a stable id and a repeat isn’t duplicated. Each one gets its own answer, so a malformed signal doesn’t sink the batch.

What you will see

One response per signal: accepted, duplicate or rejected with a reason. In the SDK they reach onSignalResult.

What never travels

The visitor is an id made up by the SDK: never an email, a phone number or the platform’s customer id.

If you don’t see it

What happens	What it means	What to do
Rejected with `unknown_decision`	The recommendation isn’t from this store	Send the recommendation exactly as you got it
Error “batch too large”	More than 50 signals in one send	With the API, split it; the SDK already does
No attributed sales	`cart_id` is missing, or the order doesn’t arrive with that id	Send `cart_id` and check the order carries the same one as `external_id`

Report signals with the SDK

track.*: the seven signals and when to send each one.

Record signals via API

The operation, with a playground.

Get started

Operate

Signals and attribution

What counts as an attributed sale

The seven signals

How the sale is tied

When to report each one

How they’re sent

What you will see

What never travels

If you don’t see it

Report signals with the SDK

Record signals via API

​What counts as an attributed sale

​The seven signals

​How the sale is tied

​When to report each one

​How they’re sent

​What you will see

​What never travels

​If you don’t see it

Report signals with the SDK

Record signals via API

What counts as an attributed sale

The seven signals

How the sale is tied

When to report each one

How they’re sent

What you will see

What never travels

If you don’t see it