Personalization

Personalization tailors a slate to the shopper in front of it, using what they have done recently in this channel. It is on by default and turned off per request with "personalize": false.

The three inputs

Input	Where	Identifies
X-Lbx-Visitor-Id	Header, required on every discovery request	This browser, over the long term
user_id	Body field, optional	The signed-in shopper, across their devices
personalize	Body field, default true	Whether to personalize this request

curl -X POST 'https://api.eu1.luigisbox.ai/discovery/v1/search?channel_id=lbn_4hj9tv&surface_id=lbs_search_main' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Lbx-Visitor-Id: 8f14e45f-ea0f-4b5c-9a1d-2b3c4d5e6f70' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "product",
    "query": "running shoes",
    "personalize": true,
    "user_id": "customer-88213"
  }'

personalize is also your consent signal

personalize asserts two things at once: personalize this answer, and this shopper has consented to behavioural personalization. The flag is recorded on the ranking record for the request, so it governs both what the shopper sees and what the request may be used for afterwards.

Read it from your consent manager on every request rather than relying on the default:

// Read consent from your own consent manager — never hardcode it.
const personalize = consentManager.hasAnalyticsConsent();

The default assumes consent

An omitted personalize is treated like "personalize": true, so a request that leaves it out is recorded as consented. Send "personalize": false for a shopper who has not consented — that is the only thing that keeps the request out of behavioural personalization.

The corresponding flag on analytics events is consent_granted. Read both from the same source, so a shopper’s choice is applied consistently on the request and on the event that reports it. See Sending events.

Identify the browser correctly

X-Lbx-Visitor-Id is required on every discovery request whether or not you personalize, and it is the input personalization depends on most.

• Generate it once per browser and persist it — a UUID in a first-party cookie or localStorage.
• Keep it stable across token refreshes, page loads and sessions. A visitor ID that changes per page load makes every visit look like a new shopper.
• Never generate it server-side. If your backend calls discovery, your frontend produces the value and your backend forwards it verbatim. A server-generated ID collapses every shopper into one.
• Reset it on sign-out if a shared device is a realistic concern for your storefront.

function visitorId() {
  let id = localStorage.getItem('lbx_visitor_id');
  if (!id) {
    id = crypto.randomUUID();
    localStorage.setItem('lbx_visitor_id', id);
  }
  return id;
}

Adding user_id when the shopper signs in

user_id is your own stable customer key. Sending it lets a signed-in shopper’s history follow them between devices — the phone they browsed on and the laptop they buy on.

• Send it only while the shopper is authenticated in your storefront.
• Use a stable internal key, not an email address or anything else that identifies a person. Luigi’s Box treats it as an opaque string; you decide what it reveals.
• Omit it, or send it blank, for anonymous traffic. Both are treated as anonymous.
• Keep sending X-Lbx-Visitor-Id as well. The two are complementary, not alternatives.

Where to turn it on

Personalization helps most where a shopper’s intent is broad and the catalog is large, and least where they have already been specific.

Placement	Personalize?	Why
Homepage recommendations	Yes	Nothing else to go on
Search with a broad query — “shoes”	Yes	Many valid answers; recent behaviour breaks the tie
Search with a precise query — a SKU	Little effect	One right answer already
Category listing	Often	Ordering within a large category
Cart cross-sell	Yes	The cart plus history beats the cart alone
Explicit sort — “price, low to high”	No effect on order	The shopper asked for a specific ordering

Send true wherever you have consent; the surface decides how much to use.

Measuring it

Personalized and non-personalized traffic are reported separately; compare them, or run an A/B test on the surface, to size the effect. Both need analytics events flowing: without clicks, cart additions and purchases, there is nothing to personalize from and nothing to measure with.

See also

• Requests and responses — visitor and session identifiers
• Sending events — the consent_granted flag
• Recommendations · Search
• Analytics overview