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://ingestion.lehnz.com/api/v1/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 the number of 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; `engagement` or `conversion` for typical interactions.
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.
session_id	No	Groups events from the same browsing session.
recommendation_id	No	The ID returned by `/recommend`. Pass this when the item came from a recommendation to enable attribution.
context	No	Free-form JSON for any additional metadata (page, referrer, price, 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 — typically available within seconds.

Code examples

terminal

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

track.ts

async function trackEvent(
  userId: string,
  eventName: string,
  itemId?: string,
  metadata?: Record<string, unknown>
) {
  await fetch('https://ingestion.lehnz.com/api/v1/events/ingest', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': process.env.NEXT_PUBLIC_LEHNZ_PUBLISHABLE_KEY!,
    },
    body: JSON.stringify([{
      user_id: userId,
      event_name: eventName,
      item_id: itemId,
      session_id: sessionStorage.getItem('lehnz_session_id') ?? undefined,
      context: metadata,
    }]),
    keepalive: true, // fires even on page navigation/unload
  });
}
 
// Usage
await trackEvent(getUserId(), 'view', product.id);
await trackEvent(getUserId(), 'purchase', product.id, { price: 49.99, quantity: 1 });

track.py

import requests
 
def track_event(user_id, event_name, item_id=None, metadata=None):
    requests.post(
        'https://ingestion.lehnz.com/api/v1/events/ingest',
        headers={
            'X-API-KEY': 'lehnz_pk_YOUR_KEY',
            'Content-Type': 'application/json',
        },
        json=[{
            'user_id': user_id,
            'event_name': event_name,
            'item_id': item_id,
            'context': metadata or {},
        }],
    )
 
# Usage
track_event('usr_123', 'purchase', 'prod_456', {'price': 49.99})

Recommendation attribution

When a user interacts with an item that was shown as a recommendation, include recommendation_id in the event. This closes the attribution loop and tells lehnz which recommendations are driving real conversions.

attribution.ts

// Fetch recommendations → attach recommendation_id to each item
const recs = await fetch('https://recommendations.lehnz.com/recommend', {
  method: 'POST',
  headers: { 'X-API-KEY': process.env.NEXT_PUBLIC_LEHNZ_PUBLISHABLE_KEY!, 'Content-Type': 'application/json' },
  body: JSON.stringify({ user_id: getUserId(), limit: 12 }),
}).then(r => r.json());
 
const products = await getProductsByIds(recs.all_item_ids);
const tagged = products.map(p => ({ ...p, recommendationId: recs.recommendation_id }));
 
// When the user clicks or purchases one of those items:
await trackEvent(getUserId(), 'click', product.id);   // without attribution
 
await fetch('https://ingestion.lehnz.com/api/v1/events/ingest', {
  method: 'POST',
  headers: { 'X-API-KEY': '...', 'Content-Type': 'application/json' },
  body: JSON.stringify([{
    user_id: getUserId(),
    event_name: 'purchase',
    item_id: product.id,
    recommendation_id: product.recommendationId, // closes the attribution loop
    context: { price: product.price },
  }]),
  keepalive: true,
});

Errors

Status	Message	Fix
`400`	Missing mandatory fields	Include `user_id`, `event_family`, and `event_name`
`400`	Invalid `event_family`	Must be one of `exposure`, `engagement`, `conversion`, `system`
`401`	Missing or invalid `X-API-KEY`	Check your key is valid and correctly formatted
`403`	Secret keys prohibited on public endpoints	Use your publishable key (`lehnz_pk_...`) here