Developer docs
Event tracking
Send searches, views, cart adds, purchases and returns from the browser or app, and tie them to the results that led to them.
Events tell Solenya what shoppers did after seeing results. On indexes whose tracking_mechanism is event_based, view_item events build each shopper's preferences. Solenya also uses events to measure how results perform.
Endpoint#
POST https://api.solenya.ai/v1/track/eventUnlike the rest of the API, this is a plain form post (application/x-www-form-urlencoded), not GraphQL. That lets the browser send it with navigator.sendBeacon, which still delivers when the shopper leaves the page, and it works from any website without extra setup.
Authentication#
The token goes in an access_token form field (RFC 6750 ยง2.2), not the Authorization header.
In browsers and apps, use a publishable key (API keys). It belongs to one index, so events land on that index. Any other token, such as a secret key used from your backend, must also send solenya_index_uuid.
Request fields#
| Field | Required | Value |
|---|---|---|
access_token | Yes | A publishable key, or another token |
solenya_user_uuid | Yes | The shopper ID, the same one sent as Solenya-User-UUID on item queries |
events | Yes | A JSON-encoded list of one or more events |
solenya_index_uuid | When the token isn't tied to one index | The index the events belong to. Ignored when the token is tied to one index. |
Sending events#
From the browser:
const body = new URLSearchParams({
access_token: SOLENYA_PUBLISHABLE_KEY,
solenya_user_uuid: getShopperId(),
events: JSON.stringify([
{ type: "view_item", item: { selector: "id", eq: "SKU-001" } },
]),
});
navigator.sendBeacon("https://api.solenya.ai/v1/track/event", body);With curl, which also shows you the response:
curl -X POST https://api.solenya.ai/v1/track/event \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "access_token=<publishable_key>" \
-d "solenya_user_uuid=<user_uuid>" \
--data-urlencode 'events=[{"type":"view_item","item":{"selector":"id","eq":"SKU-001"}}]'A valid request returns 202 Accepted:
{
"success": true,
"message": "Tracked 1 event(s).",
"events_tracked": 1,
"events_failed": 0
}A request with an invalid event returns 422 with the reason, and none of its events are tracked. sendBeacon never shows you the response, and a browser fetch from your site can't read it either. While you build, send the same body with curl or from your server to see any 422.
Event types#
type | Records |
|---|---|
search | The shopper ran a search |
view_item_list | A list of products was shown |
view_item | The shopper opened a product |
click_element | The shopper clicked something on the page, such as a filter |
add_to_cart | A product went into the cart |
add_to_wishlist | A product went onto the wishlist |
begin_checkout | Checkout started |
purchase_item | A product was bought |
return_item | A bought unit was returned |
view_experiment | The shopper saw a variant of an A/B test you run yourself |
There is also an update_size_profile event for size-based ranking, which Solenya sets up with you. Ask Solenya before sending it.
Naming products#
Events about products carry an item with a selector (id or item_group_id) and exactly one of eq (one value) or in_ (a list of up to 50):
{ "selector": "id", "eq": "SKU-001" }{ "selector": "id", "in_": ["SKU-001", "SKU-002"] }In event JSON the list key is
in_, with an underscore. GraphQL item queries spell itin. Anitemwith its list under"in", without aselector, or with botheqandin_fails validation.
search#
{
"type": "search",
"search_term": "red running shoes",
"image_count": 0,
"filters": "size:9,colour:red",
"result_count": 128
}filters is your own summary of the filters applied.
view_item_list#
{
"type": "view_item_list",
"item": { "selector": "id", "in_": ["SKU-123", "SKU-456", "SKU-901"] },
"list_id": "search-results",
"list_name": "Search results",
"query_uuid": "6f1c2b8e-4d3a-4e5f-9a7b-1c2d3e4f5a6b",
"position": 1
}in_ is in display order: the product at index i was shown at rank position + i. Send a page of more than 50 products as several view_item_list events in one request, each with its own position (1, 51, ...).
view_item#
{
"type": "view_item",
"item": { "selector": "id", "eq": "SKU-456" },
"query_uuid": "6f1c2b8e-4d3a-4e5f-9a7b-1c2d3e4f5a6b",
"position": 2
}click_element#
{
"type": "click_element",
"element": "size_filter",
"value": "9",
"context": "facet_sidebar"
}add_to_cart, add_to_wishlist, begin_checkout#
These record intent, not revenue. quantity defaults to 1.
{
"type": "add_to_cart",
"item": { "selector": "id", "eq": "SKU-901" },
"quantity": 1,
"cart_value": "89.99 USD"
}{
"type": "add_to_wishlist",
"item": { "selector": "id", "eq": "SKU-901" },
"wishlist_value": "89.99 USD"
}{
"type": "begin_checkout",
"item": { "selector": "id", "in_": ["SKU-901", "SKU-123"] },
"checkout_id": "CART-42",
"checkout_value": "139.98 USD"
}purchase_item#
price is an amount with at most two decimals, a space, and an upper-case currency code, such as "10.99 USD".
{
"type": "purchase_item",
"transaction_id": "TXN-001",
"price": "99.99 USD",
"item": { "selector": "item_group_id", "eq": "ADI_GN2901_BLANK" }
}return_item#
Send one event per returned unit. item must name the unit with selector: "id" and eq. reason is your own reason code, and transaction_id links the return to the purchase when you know it.
{
"type": "return_item",
"item": { "selector": "id", "eq": "SKU-001" },
"reason": "too_small",
"transaction_id": "TXN-001"
}view_experiment#
For an A/B test you run yourself, send this whenever a shopper sees a variant.
{
"type": "view_experiment",
"name": "checkout_v2",
"variant": "treatment"
}Field limits#
| Field | Limit |
|---|---|
item.in_ | Up to 50 ids |
quantity (add_to_cart) | 1 to 1000 |
search_term | Up to 10,000 characters |
image_count | 0 to 10 |
filters | Up to 4096 characters |
list_id, list_name | Up to 128 and 256 characters |
element, value, context | Up to 128, 512 and 256 characters |
reason, transaction_id (return_item), checkout_id | Up to 128 characters |
Prices (price, cart_value, wishlist_value, checkout_value) | At most two decimals, then a space and an upper-case currency code |
Attribution#
Every event type except return_item takes two optional fields that tie the event to the result page that led to it. Send them whenever the shopper got there from Solenya results: Solenya's click-through figures count only events that carry them.
| Field | Value |
|---|---|
query_uuid | page_info.query_uuid from the results. It names one page, not a search session: the next page has a different value. |
position | The product's 1-based rank in those results. On view_item_list, the rank of the first product in in_. |
Device metadata (optional)#
Every event takes an optional device object:
{
"type": "view_item",
"item": { "selector": "id", "eq": "SKU-001" },
"device": {
"category": "mobile",
"language": "en-US",
"screen_resolution": "1280x2856",
"operating_system": "Android",
"operating_system_version": "14",
"model": "Pixel 9 Pro",
"brand": "Google",
"browser": "Chrome",
"browser_version": "136.0.7103.60"
}
}Check that events arrive#
users returns a shopper's latest events. It needs the user:read:* scope, which secret API keys have. A shopper appears only after an item query with their ID, or, on an event_based index, a view_item event.
query ShopperEvents {
users(filter_term: { where: { record: { uuid: { eq: { value: "<user_uuid>" } } } } }) {
page(page_size: 1) {
rows {
record {
uuid
events(limit: 20) {
event_type
timestamp
item_selector
item_eq
query_uuid
position
}
}
}
}
}
}The full reference, with every field, is at api.solenya.ai/v1/track/docs.