Object references

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 both take this form:

<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:

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	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: 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 — the calls that carry a reference
• Event reference — every field on every event
• Object lookup — resolve references on demand
• Catalog object model — the fields an object carries