AI Personalization

Configure AI personalization behavior, embedding sync, and profile calculation at site scope.

Audience: Personalization teams tuning AI relevance controls in production storefronts.

Critical: Personalization config endpoints are under /api/v1/ai/sites/:siteId/* and require AI permission scopes.

AI Performance AI Studio Recommendation Strategies

Who This Page Is For

Use this page when you need to turn AI personalization on/off, tune weighting strategy, and run embedding/profile pipelines.

Quick Start (2-5 Minutes)

Read current AI config

Inspect active personalization configuration for a site.

GET /api/v1/ai/sites/:siteId/personalization-config

Update weighting strategy

Tune embedding/popularity/recency weights and fallback behavior.

PUT /api/v1/ai/sites/:siteId/personalization-config

Sync embeddings

Trigger embedding generation synchronization job.

POST /api/v1/ai/sites/:siteId/sync-embeddings

Calculate user profiles

Recompute user profiles used by AI personalization ranking.

POST /api/v1/ai/sites/:siteId/calculate-user-profiles

Monitor progress and coverage

Use sync-progress and embedding-stats endpoints for operational tracking.

GET /api/v1/ai/sites/:siteId/sync-progress
GET /api/v1/ai/sites/:siteId/embedding-stats

Personalization endpoints

GET  /api/v1/ai/sites/:siteId/personalization-config
PUT  /api/v1/ai/sites/:siteId/personalization-config
POST /api/v1/ai/sites/:siteId/sync-embeddings
GET  /api/v1/ai/sites/:siteId/embedding-stats
POST /api/v1/ai/sites/:siteId/calculate-user-profiles
GET  /api/v1/ai/sites/:siteId/sync-progress

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`isEnabled`	Optional	`boolean`	Update personalization config	Master toggle for AI personalization usage.
`embeddingWeight`	Optional	`0..1 number`	Update personalization config	Weight of embedding similarity signal.
`popularityWeight`	Optional	`0..1 number`	Update personalization config	Weight of popularity signal.
`recencyWeight`	Optional	`0..1 number`	Update personalization config	Weight of recency signal.
`coldStartStrategy`	Optional	`popular \| trending \| new_arrivals`	Update personalization config	Fallback strategy for sparse profiles.
`minProductsForAi`	Optional	`5..10000 number`	Update personalization config	Minimum product count required before AI mode engages.

Update config example

{
"isEnabled": true,
"embeddingWeight": 0.7,
"popularityWeight": 0.2,
"recencyWeight": 0.1,
"useFallback": true,
"coldStartStrategy": "trending",
"minProductsForAi": 20
}

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Need current AI config baseline	GET personalization-config	Read before changes.
Need to tune ranking behavior	PUT personalization-config	Primary control plane for AI weighting.
Need fresh embedding corpus	POST sync-embeddings	Regenerates embedding state after catalog changes.
Need profile refresh after identity changes	POST calculate-user-profiles	Rebuilds user profile vectors/signals.
Need operational sync visibility	GET sync-progress and embedding-stats	Tracks job state and coverage quality.

Common Errors and Fixes

Config update rejected

Cause: Weights out of 0..1 bounds or invalid coldStartStrategy value.

Fix: Use allowed ranges and enum values only.

Personalization quality drops after update

Cause: Overweighted popularity/recency and underweighted embeddings.

Fix: Rebalance weights and monitor performance endpoint trends.

Sync remains in progress too long

Cause: Large corpus or processing bottleneck.

Fix: Monitor sync-progress and plan updates during lower-load windows.

Coverage metrics low

Cause: Insufficient product/user data for profile generation.

Fix: Increase data completeness and rerun sync/profile calculation.

Production Checklist

AI config changes are versioned and approved before production rollout.Required
Weight values remain within controlled policy ranges.Required
Embedding sync and profile jobs are monitored after catalog updates.Required
Fallback strategy is explicitly set for cold-start cases.Required
Performance is reviewed after each major config change.Required