Send the product-list-view event every time:
A user visits a category listing page (e.g., categoryA > categoryB).
A user visits a brand listing page (e.g., brandA > brandB).
The user changes sorting, applies filters, or navigates to a different page.
Category Listing
For the complete list of all fields (including optional ones), where to get each value, refer to Common Properties.
Field | Value | Notes |
|---|---|---|
eventType | "product-list-view" | Required. Always this value |
source | "category-listing" or "brand-listing" | Required. For category or brand pages |
listValue | "categoryA~categoryB" | Required. Tilde-separated hierarchy. Must not be blank |
userId | Unique user ID | Optional. No spaces. Defaults to "default" |
platform | required, oneof: desktop-web, mobile-web, tablet-web, ios, android, other | Platform used by the user |
integrationType | required, oneof: api, web, sdk, app | Type of integration. For API integrations, send "api" |
traceId | required, excludes_space | Unique trace identifier created for the current query. Use this as the primary identifier |
SessionId | excludes_space | Browser/app session identifier. Must not contain spaces |
sorting | oneof_sorting, excludes_space | Sorting method used. Must be a valid sorting option and must not contain spaces. Unlike search events, sorting is not required for page view events. |
resultCount | required, min=0 | Number of results returned |
itemsPerPage | Items per page (integer) | Optional |
totalPages | Total number of pages (integer) | Optional |
currentPage | Current page number (integer) | Optional |
products | required, min=1 | List of products displayed on the page. At least 1 product is required |
referrer | required, url | Source URL of the referring page |
createdAt | RFC 3339 | Time when the event is created |
campId | Campaign ID (integer) | Optional. Defaults to 999999 |
variationId | Variation ID (integer) | Optional. Defaults to 999999 |
sessionId | Browser/app session ID | Optional. No spaces |
strategyId | Strategy identifier | Optional. No spaces |
facets | List of facets | Optional. Required if any facet is selected |
searchSessionId | Session ID | Optional. Deprecated → use traceId instead. Falls back bidirectionally with traceId |
Refer to Common Properties for further details.
Sample Request
curl --location --request POST 'https://eurekaevent.api.useinsider.com/api/v1/events' \
--header 'x-auth-token: YOUR_AUTH_TOKEN' \
--header 'x-partner-config-key: YOUR_PARTNERID-YOUR_LOCALE' \
--header 'Content-Type: application/json' \
--data-raw '{
"eventType": "product-list-view",
"source": "category-listing",
"listValue": "categoryA~categoryB",
"traceId": "trace-abc-123",
"platform": "desktop-web",
"integrationType": "api",
"referrer": "https://example.com/category/categoryA",
"resultCount": 120,
"itemsPerPage": 24,
"totalPages": 5,
"currentPage": 1,
"sorting": "Relevancy",
"createdAt": "2025-11-25T10:30:00Z",
"products": [
{
"id": "product-001",
"groupCode": "group-1",
"price": 999.99,
"currency": "USD",
"displayPosition": 1
},
{
"id": "product-002",
"groupCode": "group-2",
"price": 1299.99,
"currency": "USD",
"displayPosition": 2
}
]
}'Brand Listing
For brand listing pages, set source to "brand-listing":
curl --location --request POST 'https://eurekaevent.api.useinsider.com/api/v1/events' \
--header 'x-auth-token: YOUR_AUTH_TOKEN' \
--header 'x-partner-config-key: YOUR_PARTNERID-YOUR_LOCALE' \
--header 'Content-Type: application/json' \
--data-raw '{
"eventType": "product-list-view",
"source": "brand-listing",
"listValue": "brandA",
"traceId": "trace-brand-456",
"platform": "desktop-web",
"integrationType": "api",
"referrer": "https://example.com/brand/brandA",
"resultCount": 50,
"createdAt": "2025-11-25T11:00:00Z",
"products": [
{
"id": "product-010",
"price": 499.99,
"currency": "USD",
"displayPosition": 1
}
]
}'listValue Format
Format | Example | Description |
|---|---|---|
Hierarchical | "categoryA~categoryB~categoryC" | Tilde-separated levels |
Flat | "flat category example" | Plain text, no separator |
The API internally splits tilde-separated values: "categoryA~categoryB" → ["categoryA", "categoryB"]
traceId Requirement
Required for every product-list-view event
Must be unique per page request, generate a new one each time
Same traceId should be reused across sorting/filter/pagination changes within the same page session
Subsequent click and add-to-cart events should reference this traceId
All Product Fields
Each product in the products array:
Field | Required | Notes |
|---|---|---|
id | Yes | Product identifier. No spaces |
groupCode | No | Variant group code. No spaces. Needed for group-level analytics |
price | Yes | Min: 0 |
convertedPrice | No | Converted price in preferred currency. Min: 0. Falls back to price |
currency | Yes | ISO 4217 (e.g., "USD"). No spaces |
preferredCurrency | No | Main currency of your site. No spaces. Falls back to currency |
displayPosition | No | Position on the page (1-indexed) |
position | No | Legacy position field. Use displayPosition instead. Retained for backward compatibility |
isMerchandisedItem | No | true if positioned by merchandising rules. Defaults to false |
Refer to Common Properties for further details.