Event Types Catalog

Event Types

Canonical event dictionary accepted by strict public event ingestion.

Audience: Frontend and backend teams instrumenting Selwise tracking contracts.

Critical: /api/v1/public/sites/:siteKey/events/batch accepts only canonical names listed on this page and rejects invalid entries per event (partial batch acceptance).

Client Event Reference API Endpoints Search Analytics

Who This Page Is For

Use this page when implementing event tracking and validating that emitted event names match the accepted canonical set.

Quick Start (2-5 Minutes)

Choose canonical event name

Select event from the approved catalog below.

Unknown names are rejected per event by strict ingestion.

Emit via public batch endpoint

Send events through siteKey-scoped public tracking endpoint.

POST /api/v1/public/sites/:siteKey/events/batch

Use matching metadata shape

Attach product/cart/order/search metadata by event intent.

Validate payload fields against client-api data-layer contracts.

Track order using order endpoint where needed

Use order ingestion for transaction-specific flows.

POST /api/v1/public/sites/:siteKey/orders

Audit event breakdown

Verify event volume and distribution in analytics endpoints.

GET /api/v1/analytics/events/breakdown?siteId=SITE_ID&days=30

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`name`	Required	`CanonicalEventName`	events/batch payload	Must be one of 48 canonical names listed below.
`entityType`	Required	`string`	events/batch payload	Entity context (for example product, category, campaign). Events are rejected when entityType is missing.
`entityId`	Optional	`string`	events/batch payload	Entity identifier associated with event.
`metadata`	Optional	`object`	events/batch payload	Event-specific attributes (price, query, filters, order context, etc.).

Canonical events (48)

page_view
virtual_page_view
widget_view
category_view
product_view
product_click
product_impression
product_dwell_time
add_to_cart
remove_from_cart
update_cart
cart_abandon
cart_restore
checkout_begin
checkout_progress
checkout_option
purchase
user_signup
user_login
user_logout
user_update
search_instant_open
search_query
search_filter
search_sort
search_page
search_results
search_zero_results
search_close
impression
click
close
view
hover
scroll
slider_navigate
slider_swipe
widget_impression
script_injected
script_error
identify
category_filter
recent_search_click
popular_search_click
popular_category_click
popular_product_click
wishlist
custom_event

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Need product impression/click tracking	product_impression/product_click	Product discovery and recommendation analytics.
Need checkout stage tracking	checkout_begin/checkout_progress/checkout_option	Funnel stage instrumentation.
Need search behavior tracking	*search_ canonical family**	Search KPI and quality analysis.
Need recommendation engagement tracking	impression/click with `entityType: recommendation`	Canonical recommendation aliases are not accepted.
Need script injection telemetry	script_injected/script_error	Operational script health tracking.

Common Errors and Fixes

Unsupported event name error

Cause: Event alias or typo not in canonical list.

Fix: Use exact canonical name from this catalog.

Event accepted but analytics incomplete

Cause: Missing metadata fields required for downstream interpretation.

Fix: Provide richer metadata per event type contract.

Purchase tracking mismatch

Cause: Mixing generic purchase event with order ingestion contract incorrectly.

Fix: Use order endpoint for transactional payloads when appropriate.

Search analytics missing expected actions

Cause: Only query events emitted, missing click/filter/sort events.

Fix: Emit full search event family from UI interactions.

Production Checklist

Event names are validated against canonical set before deployment.Required
Event payload metadata is standardized by event family.Required
Search/recommendation/order events are all instrumented end-to-end.Required
Unsupported aliases are blocked in client instrumentation layer.Required
Analytics breakdown checks are part of release verification.Required