Docs
    GuidesAPI ReferenceBlog
    Sign inCreate account
    Overview

    Getting started

    Sign upAPI keysQuickstartLoad your catalog

    Integration

    Tracking EventsIdentity StitchingPersonalisation

    Production

    Errors & status codesRetries & rate limitsTypeScript SDKTroubleshooting

    Reference

    API ReferenceVersioningChangelog
    HomeDocumentationTracking Events
    Previous
    Load your catalog
    Next
    Identity Stitching

    Skip the ML, Ship the Revenue

    Product

    • How It Works
    • Features
    • For Startups
    • For Developers

    Developers

    • Documentation

    Company

    • Blog
    • Contact

    © 2026 Lehnz, Inc. All rights reserved.

    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_nameWhen to fire
    viewA product or item page loads
    searchA user submits a search query
    clickA user clicks a product from a list or recommendation
    add_to_cartA user adds an item to their cart
    remove_from_cartA user removes an item from their cart
    checkout_startA user begins the checkout flow
    purchaseA 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.

    FieldRequiredDescription
    user_idYesYour user's identifier. For anonymous visitors, use a generated ID stored in localStorage (see Identity Stitching).
    event_familyYesOne of exposure, engagement, conversion, or system. Use system for identify events; engagement or conversion for typical interactions.
    event_nameYesThe interaction type. Use a standard name from the table above, or a custom string.
    item_idNoThe item the user interacted with. Omit for search and page-level events.
    session_idNoGroups events from the same browsing session.
    recommendation_idNoThe ID returned by /recommend. Pass this when the item came from a recommendation to enable attribution.
    contextNoFree-form JSON for any additional metadata (page, referrer, price, etc.).
    previous_user_idNoRequired 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

    StatusMessageFix
    400Missing mandatory fieldsInclude user_id, event_family, and event_name
    400Invalid event_familyMust be one of exposure, engagement, conversion, system
    401Missing or invalid X-API-KEYCheck your key is valid and correctly formatted
    403Secret keys prohibited on public endpointsUse your publishable key (lehnz_pk_...) here

    What's next

    Identity Stitching

    Connect anonymous visitor behavior to authenticated user profiles.

    Recommendations

    Fetch personalized and item-based recommendations.