Decision owner
Shopper
The named role remains accountable for the consequential decision.
Retail & E-commerce
Designed for Customer
Let a shopper describe a need in natural language and receive grounded product recommendations with live price, promotion, and fulfillment promise, while the basket and consent state stay authoritative in Cosmos DB.
Contract RET-01 · primary aggregate ShoppingSession · mode loading
Decision brief
This brief starts with the decision, evidence, and accountable owner. The guided workflow then shows how the recommendation was produced.
The evidence and control points that shape this recommendation.
Decision owner
Shopper
The named role remains accountable for the consequential decision.
Governed evidence
6 record types
Structured records and cited text ground the recommendation.
Workflow
5 controlled stages
Each transition records its input, output, status, and audit context.
Human controls
1 approval gate
Approval gates prevent the copilot from making consequential decisions.
A shopper asks for a waterproof running jacket under 150 dollars that can arrive before Saturday's race; the copilot retrieves three candidates, filters to the two promisable from the nearby fulfillment node, cites review evidence on breathability, applies a stackable 15 percent seasonal offer, and waits for the shopper to confirm before adding the jacket to the basket..
Let a shopper describe a need in natural language and receive grounded product recommendations with live price, promotion, and fulfillment promise, while the basket and consent state stay authoritative in Cosmos DB.
Committed cart lines and order handoff token gives Shopper the evidence needed to begin the final governed business outcome, with the decision trail retained for review.
Step 1 of 5
| Field | Value |
|---|
| Field | Value |
|---|
The output appears here immediately. More technical evidence remains available below.
The demonstration keeps deterministic controls, AI assistance, and approval separate.
Source systems enforce identity, workflow order, policy filters, and record updates.
Retrieval and generation assemble relevant evidence into a cited recommendation or draft.
Shopper verifies material claims and approves the consequential action.
Run the stages in order before using the Copilot. Every stage explains what happens, why it matters, the evidence it uses, and the complete API request and response.
Automated stage
What happens: Shopper performs capture shopping intent and constraints using Natural-language need with budget and occasion and produces Structured intent frame on the ShoppingSession. The transition is deterministic and does not require autonomous model approval.
Why it matters: Structured intent frame on the ShoppingSession gives Retrieval agent the evidence needed to begin Retrieve candidate SKUs with vector plus attribute filter, with the decision trail retained for review.
Loading relevant sample records.
Ready to run.
POST /api/domain/workflow/capture-shopping-intent-and-constraints
Run this API to see its formatted outcome.
| Field | Value |
|---|
| Field | Value |
|---|
Automated stage
What happens: Retrieval agent performs retrieve candidate skus with vector plus attribute filter using Intent frame and preference profile and produces Ranked ProductCard candidate set. The transition is deterministic and does not require autonomous model approval.
Why it matters: Ranked ProductCard candidate set gives Commerce validation service the evidence needed to begin Validate price, promotion, and availability, with the decision trail retained for review.
Loading relevant sample records.
Ready to run.
POST /api/domain/workflow/retrieve-candidate-sk-us-with-vector-plus-attribute-filter
Run this API to see its formatted outcome.
| Field | Value |
|---|
| Field | Value |
|---|
Automated stage
What happens: Commerce validation service performs validate price, promotion, and availability using Candidate SKU list and postal code and produces Priced, promisable shortlist. The transition is deterministic and does not require autonomous model approval.
Why it matters: Priced, promisable shortlist gives Shopping copilot the evidence needed to begin Present cited recommendation and fit rationale, with the decision trail retained for review.
Loading relevant sample records.
Ready to run.
POST /api/domain/workflow/validate-price-promotion-and-availability
Run this API to see its formatted outcome.
| Field | Value |
|---|
| Field | Value |
|---|
Automated stage
What happens: Shopping copilot performs present cited recommendation and fit rationale using Priced shortlist with review digests and produces Comparison answer with source citations. The transition is deterministic and does not require autonomous model approval.
Why it matters: Comparison answer with source citations gives Shopper the evidence needed to begin Confirm basket update or checkout handoff, with the decision trail retained for review.
Loading relevant sample records.
Ready to run.
POST /api/domain/workflow/present-cited-recommendation-and-fit-rationale
Run this API to see its formatted outcome.
| Field | Value |
|---|
| Field | Value |
|---|
Human approval required
What happens: Shopper performs confirm basket update or checkout handoff using Proposed cart mutation and produces Committed cart lines and order handoff token. A named human approver must review the evidence before the transition completes.
Why it matters: Committed cart lines and order handoff token gives Shopper the evidence needed to begin the final governed business outcome, with the decision trail retained for review.
Loading relevant sample records.
Ready to run.
POST /api/domain/workflow/confirm-basket-update-or-checkout-handoff
Run this API to see its formatted outcome.
| Field | Value |
|---|
| Field | Value |
|---|
Run a stage to see its explanation, evidence, full request, and full response.
Ask a question and receive an answer grounded in retrieved ShoppingSession evidence.
Select a starter question or enter your own.
Loaded live from /api/config, /api/domain/model, and
/api/domain/sample.
shoppingSessions/tenantId + /shopperIdA shopper asks for a waterproof running jacket under 150 dollars that can arrive before Saturday's race; the copilot retrieves three candidates, filters to the two promisable from the nearby fulfillment node, cites review evidence on breathability, applies a stackable 15 percent seasonal offer, and waits for the shopper to confirm before adding the jacket to the basket.
| Container | Role | Hierarchical partition key | Document types |
|---|---|---|---|
shoppingSessions |
Primary | /tenantId + /shopperId |
ShoppingSession, ConversationTurn, ShopperPreferenceProfile |
merchandisingCatalog |
Reference | /tenantId + /productCategoryId |
ProductCard, PromotionOffer |
inventoryPromise |
Reference | /tenantId + /skuId |
InventorySignal |
| Type | Container | Partition key | Identifier pattern | Embedding fields |
|---|---|---|---|---|
ShoppingSession |
shoppingSessions |
/tenantId + /shopperId |
session::{shopperId}::{sessionId} |
None |
ConversationTurn |
shoppingSessions |
/tenantId + /shopperId |
turn::{sessionId}::{turnSequence} |
utteranceVector |
ProductCard |
merchandisingCatalog |
/tenantId + /productCategoryId |
product::{productCategoryId}::{skuId} |
descriptionVector, reviewDigestVector |
InventorySignal |
inventoryPromise |
/tenantId + /skuId |
inventory::{skuId}::{fulfillmentNodeId} |
None |
PromotionOffer |
merchandisingCatalog |
/tenantId + /productCategoryId |
promo::{productCategoryId}::{promotionId} |
offerTextVector |
ShopperPreferenceProfile |
shoppingSessions |
/tenantId + /shopperId |
preference::{shopperId} |
affinityVector |
Rehydrate the current basket and the last turns for continuity across channels.
shoppingSessions
single-partition
SELECT * FROM c WHERE c.tenantId = @tenantId AND c.shopperId = @shopperId AND c.sessionId = @sessionId AND c.type IN ('ShoppingSession','ConversationTurn') ORDER BY c.turnSequence DESC
Knowledge-container query against inventoryPromise (bounded fan-out across the /tenantId + /skuId partitions named by the shortlist): filter ranked candidates to SKUs with available-to-promise at the shopper's preferred fulfilment nodes, as a bounded fan-out across the at most fifty shortlisted SKU partitions.
inventoryPromise
partition-key-fan-out
SELECT * FROM c WHERE c.tenantId = @tenantId AND c.skuId IN (@shortlistedSkuIds) AND c.type = 'InventorySignal' AND c.fulfillmentNodeId IN (@preferredNodeIds) AND c.availableToPromise > 0 ORDER BY c.promiseDateUtc ASC
Knowledge-container query against merchandisingCatalog (bounded fan-out across the /tenantId + /productCategoryId partitions named by the shortlist): return only offers currently in effect and stackable with the basket state, fanned out across the handful of product categories present in the basket.
merchandisingCatalog
partition-key-fan-out
SELECT * FROM c WHERE c.tenantId = @tenantId AND c.productCategoryId IN (@basketCategoryIds) AND c.type = 'PromotionOffer' AND c.effectiveFromUtc <= @nowUtc AND c.effectiveToUtc > @nowUtc ORDER BY c.effectiveToUtc ASC
Partition-key fan-out control-plane query: find sessions with value still in the cart that stalled, for follow-up messaging. It cannot carry the second partition key because recovery targets are unknown until every shopper partition is examined, so it runs as a tenant-scoped scheduled sweep off the interactive path, bounded by the ShoppingSession type inside a rolling 48-hour updatedUtc window, executed with MaxItemCount paging and continuation tokens.
shoppingSessions
partition-key-fan-out
SELECT * FROM c WHERE c.tenantId = @tenantId AND c.type = 'ShoppingSession' AND c.cartSubtotal > 0 AND c.updatedUtc < @staleThresholdUtc ORDER BY c.cartSubtotal DESC