Analytics

Record a storefront analytics event

Records a first-party storefront analytics event — a page view or the start of a browsing session. These events power Store Analytics: traffic, audience, the conversion funnel, and revenue-by-source reporting that the merchant views in their dashboard.

Fire this from the storefront on each route change. Send session_start for the first event of a new browsing session and page_view for each page thereafter. Provide a stable visitor_id (persisted in the browser, e.g. localStorage) so returning visitors are recognised, and a session_id per browsing session (the same identifier you use for an anonymous cart) so events group into a session.

The device, browser, operating system, and approximate location (country/region) are derived automatically from the request — you do not send them. Pass only the path (the pathname; query strings are ignored), the referrer, and any UTM campaign parameters present on the landing URL. Publishable keys are accepted, so the call can be made directly from the browser. The request is processed best-effort and returns immediately; it never blocks the page.

POST

analytics

collect

curl --request POST \
  --url https://api.tybritelabs.com/v1/analytics/collect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "event_type": "session_start",
  "visitor_id": "v_8f2a1c",
  "session_id": "7c1f0e8a-2b3c-4d5e-9f01-23456789abcd",
  "path": "/",
  "referrer": "https://www.google.com/",
  "utm_source": "google",
  "utm_medium": "organic"
}
'

{
  "recorded": true
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "details": "The 'email' field is required"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this API key. Please slow down and try again shortly.",
    "remaining": 0,
    "reset": 1706198400
  }
}

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred"
  }
}

Authorizations

Authorization

string

header

required

API Key Authentication

Use your API key in the Authorization header:

Authorization: Bearer tybrite_sk_live_YOUR_KEY

Key Types:

Secret Keys (Server-Side Only):

Format: tybrite_sk_live_* (production) or tybrite_sk_test_* (sandbox)
Full read/write access to all endpoints
⚠️ NEVER expose in client-side code or public repositories
Required for: write operations, authentication, payment verification, AI recommendations

Publishable Keys (Client-Safe):

Format: tybrite_pk_live_* (production) or tybrite_pk_test_* (sandbox)
Read-only access (GET requests only, plus POST semantic search)
✅ Safe for client-side JavaScript, mobile apps, and public code
Allowed for: browsing products, search, CMS content, pricing queries

Endpoint-Specific Requirements:

Authentication endpoints (/v1/auth/*): Secret key required
Payment verification (POST /v1/payments/verify): Secret key required
AI Recommendations (POST /v1/recommendations): Secret key required
Semantic Search (POST /v1/search): Both key types allowed (read-only operation)
All write operations: Secret key required
All read operations: Both key types allowed

Using a publishable key for restricted operations returns 403 Forbidden.

Body

application/json

event_type

enum<string>

required

session_start for the first event of a session, page_view on each route change, and page_close (with duration_ms) fired on page hide to capture dwell time — send it with navigator.sendBeacon from a visibilitychange / pagehide handler so it survives the page unload.

For the CMS conversion funnel: post_view / lookbook_view when a shopper opens a blog post / shoppable lookbook (send content_id), and content_click when they click through to a product from inside that content (send content_id + content_product_id). To close the funnel, pass content_id (+ content_type) in the order's attribution at checkout — see the Orders API.

search records what a shopper searched for. Send it with search_query and the search_result_count the search returned, so a merchant can see which searches their catalogue answers badly. The term is normalised before it is stored, and a search event is never associated with a customer.

search_result_click records which result the shopper clicked. Send it with the same search_query, the search_result_product_id they clicked, and its search_result_position in the list as shown. This is what makes merchandising measurable: without it, a rule can only be judged by whether searches matching it happened to convert, which counts a shopper who ignored the featured product exactly the same as one who clicked it.

Available options:

page_view,

session_start,

page_close,

post_view,

lookbook_view,

content_click,

search,

search_result_click

visitor_id

string

required

A stable per-visitor identifier persisted in the browser (e.g. localStorage). Used to distinguish new vs returning visitors.

session_id

string

required

The shopper's browsing-session identifier (same concept as the anonymous cart session). May also be sent as the x-session-id header.

search_query

string

The shopper's search term. Required when event_type is search, ignored otherwise. Leading, trailing and repeated whitespace is collapsed and the term is lowercased before storage, so casing and spacing do not fragment the reporting. May also be sent as q.

Maximum string length: 200

string

Alias for search_query. Accepted so a storefront can reuse the same field name it sends to the search endpoint; search_query takes precedence when both are given.

Maximum string length: 200

search_result_product_id

string<uuid>

The product the shopper clicked. Required when event_type is search_result_click — a click with no product cannot be attributed to anything.

search_result_position

integer

Its 1-based position in the results as they were shown. Optional, but worth sending: it is what distinguishes a product that was clicked because it was featured from one that would have been found anyway.

Required range: x >= 1

search_result_count

integer

How many results the search returned. Send 0 when it returned none — that is the signal a merchant most needs, marking a search the catalogue could not answer at all. Only meaningful when event_type is search.

Required range: x >= 0

path

string

The page path being viewed. Only the pathname is stored; any query string is discarded.

referrer

string

The document referrer, when present.

utm_source

string

utm_medium

string

utm_campaign

string

utm_term

string

utm_content

string

duration_ms

integer

Time spent on the page in milliseconds. Send with a page_close event to power average time-on-page and session-duration metrics.

customer_id

string<uuid>

The signed-in shopper, when known.

content_id

string

For post_view / lookbook_view / content_click — the CMS post or lookbook id. (Also accepted as cms_content_id.)

cms_content_id

string

Alias of content_id. Send one or the other, not both.

content_product_id

string<uuid>

For content_click — the product the shopper clicked through to from inside the content. Required (with content_id) on a content_click.

Response

The event was accepted.

recorded

boolean

curl --request POST \
  --url https://api.tybritelabs.com/v1/analytics/collect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "event_type": "session_start",
  "visitor_id": "v_8f2a1c",
  "session_id": "7c1f0e8a-2b3c-4d5e-9f01-23456789abcd",
  "path": "/",
  "referrer": "https://www.google.com/",
  "utm_source": "google",
  "utm_medium": "organic"
}
'

{
  "recorded": true
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "details": "The 'email' field is required"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this API key. Please slow down and try again shortly.",
    "remaining": 0,
    "reset": 1706198400
  }
}

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred"
  }
}

Reference

System

Products

Taxonomy

Orders

Payments

Cart & Wishlist

Marketplace

Recommendations

Discovery

Events

Tax

Analytics

Search

Authentication

Customers

Gift Cards

Promotions

CMS

Pricing

Messaging

Shipping

GC Connect

Reviews

Returns

Disputes

B2B

Webhooks

Ingestion

Sandbox

Record a storefront analytics event

Authorizations

Body

Response