Personalization

Simple terms

Personalization chooses a visitor-specific experience from ordered rules and signals.

Signal-driven storefront experiences with ordered rules, payloads, targeting, rollout controls, and decision debugging.

Routes

• /personalization

Implementation behavior

• Personalization rules evaluate visitor and store signals in order and return the first eligible experience.
• Experiences can use targeting, payload values, rollout percentage, and safe status controls.
• Decision debugger shows matched and rejected rules so teams can understand runtime behavior.
• The runtime uses the same event, segment, and signal foundation as experiments and flags.

How to use it

• Create personalization only after the signal or audience is trustworthy.
• Order specific rules above broad fallback rules.
• Roll out gradually and inspect decisions before expanding traffic.
• Use analytics and visitor trails to validate that the experience is reaching the intended group.

When not to use it

• Do not use personalization when you need a clean randomized A/B test result.
• Do not personalize from signals that are missing, noisy, or legally sensitive.
• Do not create broad rules above specific rules unless the broad rule is meant to catch most traffic.

Implementation source

• Pages live under src/app/(dashboard)/personalization.
• Handlers live under /api/personalizations plus activate, pause, and archive routes.
• Runtime decisions use segment, signal, rollout, and payload records tied to the active shop.

Data and API

• Personalization, rule, payload, segment, signal, and decision records.
• APIs under /api/personalizations, /api/personalizations/[id], /api/personalizations/[id]/activate, /api/personalizations/[id]/pause, and /api/personalizations/[id]/archive.
• Uses SDK events, store facts, visitor context, and segment rules.

Failure modes

• Wrong experience appears: rule order, broad targeting, or stale visitor signals.
• No experience appears: paused status, rollout exclusion, missing signal, or targeting miss.
• Hard-to-debug outcomes: use the decision debugger and visitor explorer together.

Audiences and experiences

Ordered audiences let one personalization show different experiences to different visitors. Each audience has its own targeting, rollout and experience. Audiences run in order; a matching audience can stop later ones from running, including when its visitor receives the holdback version.

The flag API and apex flags CLI can create experiences, replace the audience list and reorder audiences. Removing an audience keeps its performance history. The existing apex personalizations commands and personalization API paths keep their format and automatically use the current data after a personalization has moved to the flag model.