Integration

Tracking Events

Every event you send teaches lehnz more about what your users want. Richer signal leads to better recommendations.

Standard event names

`event_name`	When to fire
`view`	A product or item page loads
`search`	A user submits a search query
`click`	A user clicks a product from a list or recommendation
`add_to_cart`	A user adds an item to their cart
`remove_from_cart`	A user removes an item from their cart
`checkout_start`	A user begins the checkout flow
`purchase`	A transaction completes successfully

Custom event names are also accepted. Lehnz scores them using the event_family weight (engagement or conversion).

Endpoint

POSThttps://api.lehnz.com/v1/ingest/events/ingest

Use your publishable key (lehnz_pk_...). It is safe to call from the browser.

Request body

Send a single event object or an array. Arrays are preferred: they reduce HTTP requests and help you stay within rate limits.

Field	Required	Description
user_id	Yes	Your user's identifier. For anonymous visitors, use a generated ID stored in localStorage (see Identity Stitching).
event_family	Yes	One of `exposure`, `engagement`, `conversion`, or `system`. Use `system` for `identify` events.
event_name	Yes	The interaction type. Use a standard name from the table above, or a custom string.
item_id	No	The item the user interacted with. Omit for search and page-level events.
recommendation_id	No	The `recommendation_id` returned by `/v1/recommend`. Pass this when the item came from a recommendation to enable attribution.
context	No	Free-form JSON for additional metadata (page, referrer, price, session, etc.).
previous_user_id	No	Required only for `identify` events. The anonymous ID being merged into the authenticated profile.

Response (202 Accepted)

202 means events were accepted into the processing queue. They are typically available within seconds.

Send events

curl -X POST https://api.lehnz.com/v1/ingest/events/ingest \
  -H "X-API-KEY: lehnz_pk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {"user_id": "usr_1","event_family": "exposure","event_name": "view","item_id": "prod_1"},
    {"user_id": "usr_1","event_family": "conversion","event_name": "purchase","item_id": "prod_1","context":{"price":49.99}}
  ]'

Recommendation attribution

When a user interacts with an item served by a recommendation, include recommendation_id in the event. This tells lehnz which recommendations are driving real conversions.

# Echo recommendation_id when the interaction came from a recommendation.
curl -X POST https://api.lehnz.com/v1/ingest/events/ingest \
  -H "X-API-KEY: lehnz_pk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"user_id": "usr_1","event_family": "conversion","event_name": "purchase","item_id": "prod_1","recommendation_id": "550e8400-e29b-41d4-a716-446655440000","context":{"price":49.99}}]'

Identity stitching

At sign-in, send a single identify event (with event_family: "system" and previous_user_id) to merge the anonymous user's history into their authenticated profile. This transfers all pre-login behavioral signal so recommendations stay coherent across sessions. See Identity Stitching for the full four-step contract, server-side mechanics, and common mistakes.

Errors follow the standard envelope. See Errors & troubleshooting.