Event reference

Field-level reference for the events accepted by POST /events/v1/events. For how to send them, see Sending events.

There are two event types, covering three things to report: a click, a cart addition, and a completed order. The results a surface returned are recorded when the discovery request is served — you do not send them. See What you report, and what you don’t.

Shared envelope

Present on both event types.

Field	Type	Required	Notes
type	string	Yes	interaction or transaction
channel_id	string	Yes	lbn_ + 6 characters
event_id	string	No	Generated if omitted. Set it yourself for idempotent retries.
event_timestamp	integer	No	Unix seconds. Receipt time if omitted.
catalog_id	string	No	lbc_ + 6 characters
user_id	string	No	Your opaque key for a signed-in shopper
consent_granted	boolean	No	Defaults to false
currency	string	No	ISO currency code
platform	string	No	Your own vocabulary — web, ios, …
referrer	string	No	Referring URL. Truncated at 1000 characters.
context	object	No	Flat map, string keys to string values
ab_test	boolean	No	Whether this belongs to your own A/B test
variant	string	No	Which variant of it
app_version	string	No
api_version	string	No	Defaults to "1"

The visitor is not an envelope field — it travels in the required X-Lbx-Visitor-Id header. See Sending events.

Field rules

Rule	Detail
Identifiers	channel_id must match lbn_ + 6 Crockford base32 characters; catalog_id the same with lbc_
References	<type>/<field>:<value>, all three parts non-empty — see Object references
Booleans	Only true, false, "true", "false". 1 and 0 are rejected.
context	Values must be strings. Nested objects are rejected.
URLs	Truncated at 1000 characters rather than rejected

interaction

Covers both clicks and cart additions; interaction_type distinguishes them.

Field	Type	Required	Notes
reference	string	Yes	The object acted on
interaction_type	string	Yes	click, add_to_cart, … — your own vocabulary
listing_ab_test	boolean	Yes	Whether this came from a result set under an A/B test
url	string	No	Where it happened
count	integer	No	Quantity, for cart actions
price	number	No	Unit price. Must be ≥ 0.

Keep interaction_type values stable — reporting groups on the exact string, so renaming one splits its history in two.

A click:

{
  "type": "interaction",
  "channel_id": "lbn_4hj9tv",
  "reference": "product/@id:product/sku-1001",
  "interaction_type": "click",
  "listing_ab_test": false,
  "consent_granted": true
}

A cart addition:

{
  "type": "interaction",
  "channel_id": "lbn_4hj9tv",
  "reference": "product/sku:ABC-123",
  "interaction_type": "add_to_cart",
  "listing_ab_test": false,
  "consent_granted": true,
  "count": 2,
  "price": 29.9
}

transaction

Field	Type	Required	Notes
items	array	Yes	At least one item
listing_ab_test	boolean	Yes
url	string	No

Each item:

Field	Type	Required	Notes
reference	string	Yes
title	string	Yes
count	integer	Yes	Quantity
total_price	number	Yes	Line total, not unit price
was_discounted	boolean	No	Defaults to false
was_volume_discounted	boolean	No	Defaults to false

{
  "type": "transaction",
  "channel_id": "lbn_4hj9tv",
  "currency": "EUR",
  "listing_ab_test": false,
  "consent_granted": true,
  "items": [
    { "reference": "product/sku:ABC-123", "title": "Blue Cotton T-Shirt", "count": 2, "total_price": 59.8 }
  ]
}

Send it when the order completes. A server-side order handler is a slightly more reliable place for it than the browser, but either works.

Object references

Every reference is three parts — <type>/<field>:<value> — and any field the object carries can be the field. Object references covers which one to pick and what happens when a reference resolves to nothing.

See also

• Object references — the reference format in full
• Sending events — the calls and the patterns
• Analytics overview — what the data is used for
• API Reference