AI Shopping Assistant — User Guide

The AI Shopping Assistant interprets shopping goals expressed in natural language, searches the products visible on the current site, and keeps its written guidance, product cards, and comparison results in a conversation session. Both signed-in customers and anonymous visitors can use it; chat, session, comparison, and stop actions remain within the site's security and session-ownership rules.

1. Scope and access requirements

The assistant can help with the following tasks:

• search by intended use, recipient, budget, ingredient preference, or exclusion;
• retain context within one session so that a shopper can refine an earlier request;
• show product cards and recommendation reasons backed by the current retrieval result;
• produce a structured comparison of several products from one recommendation set;
• open product details, choose a purchasable variant, or add a recommendation to the cart; and
• create, rename, delete, and restore multiple sessions.

Select “AI Mode” in the storefront header search box to open the assistant. Signing in is optional, but anonymous and authenticated use have separate session identities and quotas. The “AI Mode” button appears only when store AI is enabled for the current site. When store AI is disabled, the page shows “Page Not Found” after the feature check finishes. This is not a sign-in error, and a storefront user cannot enable the feature.

AI recommendations assist with shopping decisions only. The assistant does not place orders, and a recommendation card is not a stock or price guarantee. The current product and variant state is fetched again before an add-to-cart operation.

2. Page layout and visible states

On desktop, the page has two primary regions: session history on the left and the conversation on the right. Recommendations are not a permanent third panel. They are embedded below the assistant message that produced them and can be expanded or collapsed. On mobile, history opens in a drawer while messages, product cards, and comparisons remain in the same scrolling area.

The page presents these states:

The quota summary distinguishes chat usage from product-comparison usage and shows used, limit, remaining, and the next reset time formatted for the current locale.

3. Sessions, history, and trash

3.1 Create, switch, and load history

“New session” creates an empty session immediately, with a default title in the current interface language. After the first normal message completes, the site may generate a more useful title if the title is still the default. A title-generation failure does not prevent the answer or recommendations from appearing.

Session history loads 20 items at a time and offers more when available. After switching sessions, messages load 60 at a time, with an action for older messages. Each assistant message retains its own recommendations and comparison groups, so reopening an older conversation does not reduce it to only the most recent product set.

3.2 Anonymous and authenticated sessions

Every session read and change is limited to the identity that owns the session:

• a signed-in session belongs to the current account and can be retrieved on another device signed in to the same account on that site;
• an anonymous session is tied to the current site and browser identity, so it is normally available only while that browser identity remains; and
• signing in changes the actor from the anonymous device to the account. Anonymous sessions are not automatically migrated or merged, and signing out does not expose account sessions to the anonymous actor.

Clearing site data or moving to another browser or device can make the earlier anonymous identity inaccessible. Do not use an anonymous session as the only long-term record of an important purchase decision.

3.3 Rename, delete, and restore

An active session title can be edited. An empty title cannot be saved, and a title may contain at most 60 characters.

Deleting an active session requires confirmation and first moves it to Trash:

• Restore returns the session to the active list;
• Delete permanently is available only in Trash and cannot be undone; and
• Empty Trash permanently deletes every trashed session owned by the current actor.

There is no fixed user-facing expiry countdown for a normal session. A session containing messages does not become an expired session merely because it has been open for a while.

3.4 Delete one message

When no stream is in progress, either a user message or an assistant message can be deleted individually. After confirmation, that message is removed permanently; it does not enter Trash, and the adjacent reply or question is not automatically removed. Deleting an assistant message that owns recommendations or comparison content also removes the ability to restore those cards from that message.

4. Ask and refine a question

4.1 Input rules and keyboard controls

The input displays the current character count and the limit configured for the site. The default is 1,000 characters, and the site can change it within the supported range. The page enforces the current limit. Press Enter to send and Shift+Enter for a new line. Sending is disabled for blank input, while generation or cart synchronization is running, or when chat quota is exhausted.

For a more stable result, include as many relevant constraints as possible:

• recipient or intended use, such as an age group, environment, or goal;
• an explicit budget or price range;
• required attributes, ingredients, variant details, or brand preferences;
• ingredients, allergens, or other conditions to exclude; and
• the number of candidates requested, or whether price, use case, or another attribute matters most.

For example: “Find something for office use under $200, exclude ingredient X, and give me three candidates with their differences.” In the same session, a follow-up such as “increase the budget to $300” or “exclude the first one” causes the system to search again using the stored conversation state.

4.2 Language and ordering requests

The assistant provides Chinese, English, and French replies according to the current site language. Product titles and subtitles prefer catalog translations for that language; completeness depends on the product data.

The current page has no separate “effectiveness / price low to high / price high to low” selector. Express a budget, minimum, maximum, or price priority in the message instead. The retrieval flow derives price constraints from explicit price language.

5. Thinking, gradual replies, and interruption recovery

After a message is submitted, the page enters a thinking state. The site can independently configure the timer, the displayed typical range, and the slow-response threshold. Without an override, the typical range is 20–60 seconds and the slow hint begins at 50 seconds. These are interface hints, not a completion deadline or service-level guarantee.

The response appears progressively. After a short connection break, the page automatically tries to recover it, with at most two recovery attempts. If it still does not finish, the page reports an error; text without a completion indication must not be treated as a complete answer.

When Stop is selected, the page ends the active generation and keeps the text already received. On success, generation state ends; if stopping fails, the page reports the failure. Stopping affects only the active generation; it does not delete the session or earlier messages.

6. Recommendation scope and product cards

6.1 Where products come from

For an ordinary shopping request, retrieval prioritizes published products that are currently purchasable and have a sellable variant. Explicit wording can change the allowed catalog scope:

• requests such as “information only” or “it does not need to be purchasable” can broaden the search to visible catalog products;
• requests about “coming soon,” preorders, or market testing can include the corresponding preview or research products; and
• pregnancy, children, allergies, contraindications, or treatment language strengthens safety guidance without weakening catalog visibility or evidence rules.

Recommendations must come from the visible products and structured evidence returned by retrieval. Free-form model text cannot create a product or turn a name absent from the catalog into a clickable card.

6.2 What a card shows

Recommendations are stored per assistant message. A card can contain an image, title, price, optional subtitle, recommendation reason, focus badge, comparison checkbox, and purchase action. When the focus policy has enough evidence, it can label a best candidate, co-candidates, or finalists; it does not force a badge when evidence is insufficient.

Selecting the title or image opens product details. The card does not promise stock through static wording. Price and purchase state are checked again when the shopper acts.

6.3 When no product matches

When the current query requires clarification, the page opens a question-and-choice dialog instead of immediately broadening retrieval. Follow the displayed single- or multiple-choice instructions; the same session continues after confirmation, and the input is disabled while it continues. Cancel cannot bypass required clarification.

After clarification, if retrieval still has no eligible product, the site may run a scope-controlled broadened search using the identified goal:

• if broadened retrieval finds products, those candidates are returned with a note that the search was broadened;
• if it still finds nothing, the assistant gives a short consultative explanation and suggests how to adjust the conditions; and
• if the external model cannot produce that explanation, localized fixed safety copy is used.

“No result” means that no eligible candidate was found in the current site's visible scope under the current constraints. It does not prove that such a product does not exist anywhere.

7. Compare products

Select products inside one assistant message's recommendation section, then choose “Compare now.” At least two products are required. The site configures the maximum within a supported range of 2–8; the fallback is four. Once the maximum is selected, another checkbox does not change the selection and the quantity hint is highlighted.

Comparison results appear progressively and can provide:

Each new combination becomes a separate comparison group, identified by group markers beside its products. Selecting a marker reopens the stored comparison. The exact same product set in the same session and message can reuse its saved group without consuming another comparison use. If a new comparison fails, the page reports the comparison error while retaining recommendations and previous groups so that the shopper can retry later.

8. Add a recommendation to the cart

Purchase buttons come from structured commerce state, not words in the AI response:

Before adding, the page fetches current product, variant, price, and purchase status. If the variant was deactivated, availability changed, or a fresh choice is needed, the page reports that condition rather than forcing an outdated recommendation into the cart.

For an anonymous visitor, a successful add writes to the browser's local cart. For a signed-in user, it uses that account's cart. Signing in does not automatically merge the anonymous cart, so cart contents can differ before and after sign-in. Preview, research, and unavailable products can still be read or compared, but they are not guaranteed to proceed to checkout.

9. Quotas and dynamic limits

Chat and product comparison use separate weekly quotas; the number of sessions is not the usage unit. Defaults are shown below, and the site can adjust them for an anonymous visitor or account:

The week begins Monday at 00:00 UTC. The page converts the next week boundary to a date and time formatted for the current locale. When chat quota is exhausted, no new normal message can be sent. When comparison quota is exhausted, no new comparison can be generated, but history, saved same-set comparisons, and session management remain available.

Anonymous quota and sessions share the same device-identity boundary. Signing in switches to the account's quota and does not merge anonymous usage or sessions into the account.

10. Data, security, and disclaimer

• Prompts, replies, recommendation content, comparison groups, and usage records are stored on the site; they are not private drafts held only in the browser. Do not submit passwords, verification codes, payment credentials, medical records, or other unnecessary sensitive data in a prompt.
• Each identity can access only its own sessions. Clearing site data or changing browsers can make an anonymous session unavailable.
• AI suggestions are for shopping reference only. Consult a professional for medical issues. Recommendation reasons and comparisons do not replace product details, labels, instructions, or professional advice.

11. Troubleshooting and recovery

The page shows “Page Not Found”: Wait for the feature check to finish. If it remains, store AI is disabled for this site; contact the site administrator.

Thinking never finishes or a reply stops partway: The displayed typical range is only a hint. Wait for the current reply to finish, then resend a shorter, clearer question after an error. The page tries to recover twice but cannot guarantee recovery from every connection failure.

Recommendations do not match the request: Add the recipient, budget, required conditions, and exclusions in the same session. If price matters, give a range or say “prioritize lower-priced options”; the page has no independent sorting selector.

No recommendation cards appear: Read the assistant's adjustment advice and relax one nonessential condition before trying again. This result describes the current catalog and visibility scope, not the entire market.

An earlier session is missing: Check both Active and Trash and load older items. If the session was anonymous, confirm that site data was not cleared and that you did not switch browsers, devices, or to a signed-in actor. An empty session may also have been removed by the site.

Comparison is unavailable: Select at least two products in the same recommendation section without exceeding the displayed maximum, and check remaining comparison quota. If a group marker exists, open the saved result directly.

Add to cart fails or asks for another variant: Product state may have changed after recommendation generation. Select a currently sellable variant again or open product details for the latest price and availability.

Deleted content needs to be restored: A deleted active session can be restored from Trash. A permanently deleted session, emptied Trash, or an individually deleted message cannot be restored.

12. Current limits at a glance