---
title: Object Identity
description: How object identity works in Luigi's Box and why it matters for data integrity and AI learning.
slug: platform-foundations/identity
docKind: concept
hub: platform-foundations
---

Object Identity is the cornerstone of the Luigi's Box feedback loop.

The "Identity" is a unique string (numerical or textual) used to unambiguously identify a specific item in your catalog — whether it is a product, category, brand, or article.

:::caution
**The Golden Rule:** The Identity must be **unique** across all types and **immutable** (it should never change).
:::

## Why identity matters

Object identity controls two critical processes in Luigi's Box: **Updates** and **Pairing**.

### Updates and deduplication

Object identities serve as primary keys in our database. When you use the [Indexing APIs](/indexing/api/v1/content-update/) to send data, we use the `identity` to decide whether to create a new item or update an existing one.

<div class="lb-mermaid-frame"><pre class="mermaid">flowchart TD
A["Incoming item with ID 123"]
A --> B{"Does ID 123 exist?"}
B -- Yes --> C["Update existing item"]
B -- No --> D["Create new item"]</pre></div>

**The trap of mutable IDs**

If you use a mutable value (like a URL) as an ID, you risk creating duplicates.

- **Day 1:** You send Product A with ID `url-1`. (Created)
- **Day 2:** You change the URL. You send Product A with ID `url-2`. (Created as **Duplicate**)
- **Result:** You now have two versions of the same product. The history is split, and search relevance suffers.

:::tip
**Best Practice:** Always use an internal, immutable ID (such as a database Primary Key or SKU) rather than a URL.
:::

### Pairing

"Pairing" is the process of matching a user's action (Analytics) to a specific item in the data you indexed (Catalog).

For the AI to learn from user behavior, the **ID sent in the analytics event** must match the **ID provided in the product feed** exactly.

<div class="lb-mermaid-frame"><pre class="mermaid">flowchart LR
A["Analytics event"]
B["Product feed"]
C{"Pairing check"}
D["Learning signal"]
E["Signal ignored"]
A -- "Sends ID 123" --> C
B -- "Sends ID 123" --> C
C -- Match --> D
C -- Mismatch --> E</pre></div>

**Common pairing errors**

| Catalog ID | Analytics ID               | Result      | Reason                     |
| :--------- | :------------------------- | :---------- | :------------------------- |
| `12345`    | `12345`                    | ✓ **Match** | Perfect alignment.         |
| `12345`    | `SKU_12345`                | ✕ **Fail**  | Prefix mismatch.           |
| `12345`    | `https://site.com/p/12345` | ✕ **Fail**  | Sending URL instead of ID. |

:::danger
**Check your status:** You can check your pairing health in the Luigi's Box application under **Catalog browser > Data quality checks**. You should aim for near 100% pairing.
:::

---

## Migrate from URLs to immutable IDs

Historically, it was common to use URLs as object identities. However, because URLs often change (e.g., SEO updates, category restructuring), this causes data loss. When a URL changes, the product effectively becomes a "new" item, losing all historical ranking and behavioral data.

If you are currently using URLs as IDs, we strongly recommend migrating to immutable IDs (like SKUs).

:::danger
**Stop:** Do not attempt this migration without coordinating with us. Contact support to ensure your historical data is preserved.
:::

The migration involves three steps:

### Step 1: Model migration

We need to ensure the AI doesn't lose its memory.

- **Option A (ID exists in data):** If your current feed already contains the new ID in a separate field, we can rebuild models internally.
- **Option B (Mapping File):** If not, provide us with a CSV mapping file (Column A: `Old URL`, Column B: `New ID`). We will use this to transfer the historical data.

### Step 2: Update analytics

You must stop sending URLs in your tracking events.

- **Events API:** Update your backend calls to send the new ID.
- **DataLayer/Script:** You must expose the new ID in your frontend code so our script can grab it. See the [Product Identification](/lbx-integration/requirements/product-identification/) guide.

### Step 3: Reindex catalog

- **Content Updates API:** You must delete the old objects (by URL) and send the new objects (by ID).
- **Feeds:** We will manage the reindex for you by reprocessing the full feed.

---

## Summary checklist

A valid Identity must be:

- **Unique** across all object types (a Category cannot have the same ID as a Product).
- **Immutable** (it never changes for the lifetime of the object).
- **Consistent** (the same string is used in both the Catalog Feed and the Analytics layer).