Signals and attribution

Every sale CrossUp brings in is proven by a signal. Without the purchase signal, that sale doesn’t show up in your admin.

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
`purchase`	The store closed the order with that product in it
`dismiss`	Closed the offer without taking it

Each signal carries its own change, never the whole cart.

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.
purchase on the thank-you page, once, with your store’s order id.

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).

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

// On the thank-you page, with the recommended products that were bought.
crossup.track.purchase(decision, { orderExternalId: order.id, items: [{ result, quantity: 2 }] });

// From a server, the purchase. Up to 50 signals per send.
batch := map[string]any{"signals": []map[string]any{{
    "signal_id":         newID(),       // stable: retrying doesn't duplicate
    "type":              "purchase",
    "decision_id":       decisionID,    // the decision that was shown
    "item_id":           itemID,
    "order_external_id": orderID,       // the order 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	The purchase signal is missing	Send `purchase` with the order 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

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

​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

When to report each one

How they’re sent

What you will see

What never travels

If you don’t see it