Object Identity

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 to send data, we use the identity to decide whether to create a new item or update an existing one.

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"]

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.

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

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 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).