---
title: Object references
description: How every analytics event ties back to a catalog object — the <type>/<field>:<value> form, which field to name, and what happens when one does not resolve.
slug: analytics/references
docKind: concept
hub: luigisbox-ai
---

Every event you report is about something in your catalog: a product that was clicked, a
product that went into a cart, the lines of a completed order. A **reference** is how the
event says which object it means.

It is a single string, and it is the same string everywhere — analytics events and
[object lookup](/discovery/objects/) both take this form:

```text
<type>/<field>:<value>
```

| Part | Is | Example |
|---|---|---|
| `<type>` | The object type | `product` |
| `<field>` | A field on that object | `sku` |
| `<value>` | The value that field holds | `ABC-123` |

So `product/sku:ABC-123` means *the product whose `sku` is `ABC-123`*. Luigi's Box looks
that object up in your catalog and joins the event to it.

## Any field, not just the id

A reference does **not** have to name the object's id. It can name any field the object
carries, so you can send whatever identifier the page you are instrumenting already has:

```text
product/@id:product/sku-1001      the id Luigi's Box returned
product/sku:ABC-123               your SKU
product/ean:5901234123457         a barcode
product/slug:blue-cotton-t-shirt  a URL slug
category/@id:category/summer      a category
```

All five name a catalog object, and all five are equally valid. Nothing needs to be
configured for a field to be referenceable — if the object has it, you can reference by it.

A product page usually knows its SKU, barcode or slug rather than the id Luigi's Box
assigned; reference by the field the page has.

Two consequences:

- **Your checkout can send SKUs.** An order handler that knows nothing about Luigi's Box
  can still report a transaction, because `product/sku:<the sku it already has>` is a
  complete reference.
- **Different pages can use different fields.** A search results page can reference by
  `@id`, straight from the response, while a cart page references by `sku`. They join to
  the same object.

## Which field to pick

Prefer, in order:

1. **`@id`, when you have it** — the value discovery returned, used verbatim. It is
   resolved without a lookup.
2. **A unique business identifier** — `sku`, `ean`, `mpn`. What your own systems key on.
3. **Anything else the object carries**, when the page has nothing else.

The one requirement is **uniqueness**: a reference is meant to name one object. If two
products share a `color`, then `product/color:blue` is not a reference to either of them,
and the two surfaces treat that differently:

| Surface | On an ambiguous reference |
|---|---|
| Analytics events | One of the matches is used |
| [Object lookup](/discovery/objects/) | Rejected |

## References are catalog-scoped

The same reference resolves against the catalog the event belongs to. `product/sku:ABC-123`
in one catalog and the same string in another are two different objects — so a reference is
only meaningful together with its channel and catalog.

## When a reference does not resolve

Events are accepted asynchronously, so a reference that names nothing is not an error you
see at send time. The event is recorded either way — but it is not joined to a catalog
object, which means:

- it does not appear in anything reported per object,
- it contributes nothing to what ranking learns about that object.

Both fail without an error, so verify references early. The usual causes:

| Cause | Looks like |
|---|---|
| The field name is wrong | Nothing joins, for every event of that kind |
| The value is formatted differently than in the catalog | Leading zeros, casing, a prefix your feed strips |
| The object is not in the catalog | A product that is not in the feed, or not yet indexed |
| The type is wrong | `product/…` for something indexed as `article` |

To check a reference, use [object lookup](/discovery/objects/): it takes the same
references and returns what each one resolves to.

## Writing the string

| Rule | Detail |
|---|---|
| All three parts | Must be non-empty |
| `<type>` and `<field>` | No `/` and no `:` |
| `<value>` | Anything, including `/` and `:` — everything after the first `:` is the value |

The last rule is why `product/@id:product/sku-1001` is valid: the value is
`product/sku-1001`, slashes and all. A value containing a colon is also valid —
`product/slug:spring:2026` reads as the slug `spring:2026`.

## See also

- [Sending events](/analytics/sending-events/) — the calls that carry a reference
- [Event reference](/analytics/event-reference/) — every field on every event
- [Object lookup](/discovery/objects/) — resolve references on demand
- [Catalog object model](/concepts/catalog-object-model/) — the fields an object carries