Skip to main content
Every event in a POST /beacon batch is validated against a schema chosen by its event_type field. Events that don’t match their schema are dropped from the batch.

​
Common fields

These fields are accepted on every event. Server-enriched fields (geo, device, browser, OS) are added automatically — don’t send them.
​
string
required
Unique identifier for the event. Use a ULID or UUID generated client-side. Required for deduplication.
​
string
required
The event discriminator. Must be one of the values listed in Supported event types.
​
string
required
ISO 8601 timestamp of when the event occurred (e.g., "2026-06-01T14:30:00Z"). Accepted as either an ISO string or a Date-parseable value; stored in UTC.
​
string
required
Anonymized session identifier for the shopper’s visit. Should be stable for the duration of a session and rotate at session expiry.
​
string
Logged-in customer identifier. null or omitted for guests.
​
string
The token returned by Search, Browse, or Blocks. Required to attribute downstream product_click, product_view, add_to_cart, and block_view events back to the originating request.
​
string
"web" or "app". Optional. If omitted, the worker infers it from User-Agent and the X-Requested-With header.
​
number
Shopify product ID. Required for product-scoped events (see below).
​
number
Shopify variant ID.
​
string
Collection handle. Required for collection_view.
​
number
1-indexed position in the result set. Required for product_click, product_impression, product_hover, product_touch.
​
string
UTM source.
​
string
UTM medium.
​
string
UTM campaign.
​
object
Free-form additional context (e.g., A/B test bucket, page template, locale). Defaults to {}.

​
Server-enriched fields

Don’t set these — the worker fills them in:

​
Supported event types

Engagement events (fired from the storefront): Request events (typically sent server-side by the platform, not the storefront — included here for completeness):
Storefront integrations should generally only send the engagement events in the first table. The request events are emitted by the Layers platform itself.

​
Validation rules

  • event_id, event_type, timestamp, session_id are required on every event.
  • event_type must be one of the values above. Unknown types are dropped.
  • Type-specific required fields above must be present; missing them causes the individual event to be dropped (the batch still ingests).
  • The batch must contain between 1 and 100 events. Outside that range, the entire request fails with 422.

​
Next steps