---
title: Event reference
description: Every field on the events you send to Luigi's Box AI — the shared envelope, interactions and transactions.
slug: analytics/event-reference
docKind: reference
hub: luigisbox-ai
---

Field-level reference for the events accepted by `POST /events/v1/events`. For how to send
them, see [Sending events](/analytics/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](/analytics/overview/#what-you-report-and-what-you-dont).

## 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](/analytics/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](/analytics/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:

```json
{
  "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:

```json
{
  "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` |

```json
{
  "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](/analytics/references/) covers which one to
pick and what happens when a reference resolves to nothing.

## See also

- [Object references](/analytics/references/) — the reference format in full
- [Sending events](/analytics/sending-events/) — the calls and the patterns
- [Analytics overview](/analytics/overview/) — what the data is used for
- [API Reference](/api/)