Event Tracking

Overview

The recommendation engine improves over time by learning from shopper interactions. The storefront widget tracks events automatically, but you can also send events via the API for headless storefronts or custom integrations.

Track Event

POST /api/events

Request Body

{
  "type": "click",
  "productId": "gid://shopify/Product/123456",
  "sessionId": "abc-123",
  "customerId": "gid://shopify/Customer/789",
  "widgetId": "widget-product-page",
  "metadata": {}
}

Event Types

Type	Description	When to Send
impression	Recommendations were displayed to the shopper	Widget renders
click	Shopper clicked a recommended product	Product card click
add_to_cart	Shopper added a recommended product to cart	Add-to-cart action
purchase	Recommended product was purchased	Order confirmation
dismiss	Shopper dismissed a recommendation	Dismiss/hide action
save	Shopper saved a recommendation for later	Save/bookmark action

Fields

Field	Type	Required	Description
type	string	Yes	Event type (see above)
productId	string	Yes	The Shopify product ID
sessionId	string	Yes	Unique session identifier
customerId	string	No	Shopify customer ID (if logged in)
widgetId	string	No	The widget placement that generated the event
metadata	object	No	Additional context (e.g., position in carousel)

Response

{
  "success": true,
  "eventId": "evt_abc123"
}

Batch Events

For high-volume tracking, you can send multiple events in a single request:

POST /api/events/batch

{
  "events": [
    { "type": "impression", "productId": "123", "sessionId": "abc" },
    { "type": "click", "productId": "456", "sessionId": "abc" }
  ]
}

Maximum 100 events per batch request.