Skip to content

Shopper personalization

Shopper personalization is an additive, default-off serving capability. It never changes a Recommendation Snapshot or queries a merchant data source while serving. The integrating Commerce Property supplies an authenticated principal, a signed property-scoped Shopper context, and ordered interactions.

Runtime boundaries

  • AuthorizationAndAbusePolicy validates the authenticated principal, property scope, role, and purpose-specific authorization assertion before Shopper state is read or written.
  • ShopperInteractionService commits the idempotency record, ordered ledger entry, lifecycle barrier, and compact Shopper Profile projection in one control-database transaction. Only then does it issue an Interaction Acknowledgement and causal token.
  • ShopperStateRepository owns retention, deterministic rebuild, suppression, deletion receipts, and full (data source, Commerce Property, Catalog, Shopper) isolation.
  • PersonalizedRecommendationService reads a bounded profile and reranks at most 100 eligible candidates from the current Snapshot by default. When a scope has a published opt-in ANN artifact, For You may instead retrieve eligible Catalog Items from that same generation. It preserves each retrieved candidate's Product ID, representation-specific score, low confidence, and ANN provenance while reranking; only rank changes.
  • PersonalizationCapabilityRegistry gates every enabled scope and API version. No configured capability preserves ordinary serving of the registered trained strategies (currently eleven).
  • The worker runs bounded expiry and deletion reconciliation independently of Training Runs.

The Serving API delegates candidate loading and fallback decisions to RecommendationServingService. SnapshotLaneLoader preserves lane-local candidates; ForYouCandidateLoader keeps its global union and Best Sellers fallback separate. The composition root chooses AuthorizedPersonalization only when the complete authorization/reranking runtime is available; otherwise UnavailablePersonalization supplies the ordinary fallback. HTTP status and telemetry translation remain in the API adapter. This changes code ownership without changing the authorization, capability negotiation, causal, or response contracts below.

HTTP contract

POST /v1/personalization/interactions accepts a strict payload containing catalog_id, opaque shopper_id, interaction_id, type, occurred_at, expected_sequence, and bounded item_ids. The closed V1 interaction vocabulary is viewed, cart_added, cart_removed, purchased, authorization_changed, opted_out, and deletion_requested.

The authenticated property is derived from Authorization: Bearer …; it cannot be supplied in the body. Personalization-Context is a short-lived signed value binding the same property and Catalog to the opaque Shopper ID and authorization assertion. Personalization-Version negotiates the enabled capability.

An accepted write returns its committed sequence, profile version, and a short-lived causal_token. An exact retry returns the original acknowledgement. Reusing the interaction ID with different content, or sending anything other than the exact next sequence, returns a typed 409 with the last committed watermark. A failed transaction never returns an acknowledgement.

Existing Serving API paths remain unchanged. Existing strategies opt in with personalize=true; the new global for-you strategy implies a personalization attempt. Personalized reads accept the same trusted context plus an optional Causal-Token. A valid causal token either observes at least its profile version within 100 ms or returns causal_not_observed; the service never silently serves a stale personalized order.

The additive personalization response member exposes only applied, not_requested, or fallback, an optional bounded fallback reason, and whether the causal requirement was observed. It never exposes a raw Shopper identifier, authorization details, profile features, versions, or score contributions. Unknown, unauthorized, opted-out, deleted, and missing-history cases retain a uniform recommendation response shape.

Candidate and profile behavior

Without ANN opt-in, existing strategies only reorder their own Snapshot candidates. for-you uses a deterministic, deduplicated union of Best Sellers, Most Viewed, and Trending from one serving-head Snapshot. Its ordinary fallback is Best Sellers, not the personalized union. Snapshot-scoped category and brand features have an additive companion table and repository contract; serving never reads the source Catalog. Training publishes Product ID, category, brand, and Recommendation Eligibility from the same consistent Catalog read as the recommendation results, including ineligible Items. Feature rows are staged in bounded batches before the serving head is activated; a failed publication preserves the previous head and removes staged features. Snapshot retention removes the associated features. Older snapshots without companion rows and Items with missing metadata still omit those terms safely. Category and brand concentration limits can use the published metadata; affinity terms additionally require populated Shopper Profile affinities, which the current interaction projection does not yet derive from Item interactions.

An opt-in ANN scope is an exception to the candidate-union limit for for-you: the worker builds one metadata or learned representation and eligible HNSW index from its consistent source read, then atomically stores it with the Recommendation Snapshot. The authorized bounded Shopper Profile supplies positive Item affinities for a normalized query; the existing projection weights purchases above views. Recent and negative Items cannot be returned. Missing, corrupt, or unusable ANN evidence falls back to the current bounded Snapshot path. The index never reads raw interactions and is not changed by acknowledged interactions between Training Runs; those interactions can change the request query. The same artifact can supply opt-in Similar Items retrieval. ANN distance is not calibrated recommendation confidence. An explicit ann.model = "two_tower" selects aggregate-pair-trained query/Item encoders instead of the default metadata SVD representation. Learned retrieval carries learned_retrieval evidence and ann_two_tower provenance; metadata retrieval carries metadata_similarity and ann_metadata. Both receive low confidence. The query encoder is exported for NumPy serving; no PyTorch training occurs in the API. Read the ANN engineering explanation for training bounds, cold-load behavior, and qualification limits.

Configured contextual Swimlanes also consume authorized typed recent-view and recent-purchase projections, separately from For You. They use bounded published co-view/co-purchase neighborhoods as candidate sources and reserve eligible recent-view history for the terminal fill step. They preserve configured step order instead of applying the personalized lane scorer across steps. See Swimlane resolution.

The deterministic scorer combines normalized Snapshot rank with bounded item, category, and brand affinities, then applies seen, negative, and recent-item penalties and concentration limits. Product ID is the final tie-breaker. Missing feature rows are safe and simply omit those feature terms.

Shopper History defaults to a maximum of 90 days; deployment configuration may shorten it. The Shopper Profile is disposable and rebuildable from retained ledger entries. Opt-out creates an immediate no-use barrier. Deletion creates an immediate barrier and a durable receipt, after which bounded worker reconciliation purges the ledger, general idempotency records, and profile while retaining only the minimal tombstone required to prevent resurrection and replay the deletion acknowledgement.

Simulation, evaluation, and experiments

Simulation Scenario personalization journeys use deterministic synthetic Shopper, Session, and interaction identities derived from the scenario seed and logical time. The journey adapter calls production-shaped Interaction and Serving seams and records only a safe alias, acknowledgement watermark, Snapshot ID, bounded outcome, causal observation, and rank delta. Recommendation-feedback journeys are explicitly excluded from independent relevance claims.

Offline evaluation splits chronologically within a property/Catalog/Shopper boundary and rejects future-derived features. It compares the non-personalized Snapshot baseline with for-you or permitted reranking using Recall@K, NDCG@K, coverage-related slices, and minimum-count suppression. Experiment assignment is default-off, stable for permitted units, versioned, and requires exposure before outcome attribution. Offline and synthetic results are proxy/correctness evidence only; conversion, revenue, retention, attribution, or causal uplift require controlled production evidence.

Deployment and rollback

The deployment JSON contains a personalization group with scope capabilities, env-backed property credentials, accepted policy versions, and an env-backed signing secret. Secret values are resolved only during API runtime construction and are excluded from configuration fingerprints and representations. Enabled scopes require a signing secret of at least 32 bytes.

Service-owned credential fingerprints, causal-token Shopper bindings, experiment assignments and exposure correlation use SHA3-512 (HMAC-SHA3-512 where keyed). Newly issued causal tokens and Personalization-Context values carry version 2 and reject version 1; both are short-lived, so deployments should refresh in-flight contexts and acknowledgements across this transition.

Rollout remains an operational gate: synthetic validation, internal simulation, allowlisted write-only traffic, read shadowing, small exposure, then experiment-gated expansion. Rollback disables read/write admission immediately but continues expiry, opt-out, and deletion reconciliation. No production exposure is approved by this implementation alone; privacy inventory, threat model, controller/counsel review, encryption/key policy, runbooks, and production-equivalent verification remain release prerequisites.