Shopping Muse

👍

New Shopping Muse via API is coming soon!

We’re making product discovery smarter, more intuitive, and effortless with API-based conversational assistant experiences.

For the request structure and examples, see the API reference.

The Shopping Muse API, part of the Search endpoint, powers conversational product discovery experiences using advanced deep learning and LLM models. It supports natural language interactions and personalized shopping guidance across a range of commerce applications, such as chat-based interfaces, guided product finders, dynamic questionnaires, conversational recommendations, and generative search experiences.

The API processes user inputs in real time, identifying intent and contextual cues to deliver highly relevant, personalized product suggestions. It's similar to the Choose API, and shares the same behavior and functionality in the following areas:

• Data centers and security
• Working with API keys
• Managing sessions and users: Necessary for accurately counting users and searches, and ensuring that metric attributions are reliable and consistent.
• Tracking product engagements (clicks): Necessary for measuring engagement with search results (that is, clicks on product tiles and adding items to the cart or wishlist, for example) and accurately reflecting the measurement in the main dashboard report.

However, some objects are structured a bit differently, particularly in the query (see the API Reference for details). The main distinction of the Search endpoint lies in its use of the query object, which is needed to execute search requests.

However, some objects are structured a bit differently, particularly in the query object. See the API Reference for details.

Query object (request)

chatId field (request & response)

Shopping Muse is a stateless API, meaning it does not retain chat history or user data between requests. However, to maintain conversational continuity and support secure session transitions, the API utilizes a chatId. This identifier contains the necessary context to keep the conversation coherent and relevant across multiple interactions.

When initiating a conversation, the first request must not include achatId field. (Note: the API does not support sending an empty chatId; simply omit the field entirely.) In the response to this initial request, a chatId will be provided.

From that point forward, you must include the chatId from the previous response in every subsequent request. For example:

• First request: no chatId
• First response: contains chatId_1
• Second request: include chatId_1
• Second response: contains chatId_2
• Third request: include chatId_2, and so on.

This mechanism ensures that Shopping Muse can maintain context across a stateless architecture.

Widgets object (response)

The widgets array inside the payload.data object groups recommended products into separate collections. Each widget includes a title representing the collection's name and a slots array containing the recommended products. Each slot in the response includes:

• SKU: The unique identifier for the product.
• productData: An object containing all product attributes, as provided in the product feed.
• slotId: A unique identifier representing the slot's contents within this specific recommendations response.

The slotId must be retained for accurate click reporting. When a click event is reported with the corresponding slotId, the backend can retrieve all contextual information related to that slot.

{ 
  "widgets": [ 
    { 
      "title": "Sleek Professional", 
      "slots": [ 
        { "slotId": "slot-abc123", "sku": "SKU_1" }, 
        { "slotId": "slot-def456", "sku": "SKU_2" }, 
        { "slotId": "slot-ghi789", "sku": "SKU_3" }, 
        ... 
      ] 
    }, 
    { 
      "title": "Sparkling Glamour", 
      "slots": [ 
        { "slotId": "slot-xyz111", "sku": "SKU_11" }, 
        { "slotId": "slot-xyz112", "sku": "SKU_12" }, 
        { "slotId": "slot-xyz113", "sku": "SKU_13" }, 
        ... 
      ] 
    } 
  ] 
} 

Support field (response)

Besides responding with products, Shopping Muse can also identify when a user is in need of customer support. When this is detected, the API response will include a support field within payload.data. You can use this flag to trigger a handoff to your customer service channels, such as support contact, support page or chat and guide the user appropriately.

{ 
  "payload": { 
    "type": "SHOPPING_MUSE", 
    "data": { 
      "assistant": "I'm here to help you find products. For store locations, please visit our store locator page on the website.", 
      "support": true, 
      "chatId": "gAAAAABnD34yb0Q5RLo8nmcpo5GikahgDh0i-zKjn7VNWdI-HlObaZTdvxENLnFPCNzjp", 
      "widgets": null 
    } 
  } 
}

Rate limits and response time

The Shopping Muse endpoint enforces the following default rate limits:

• Response time: 95% of the requests will return in less than 6 seconds.
• Global limit: 22,000 requests per minute.
• Section limit: 1000 requests per minute.
• User limit: 10 requests per minute.

If a request exceeds the configured limit, the API will return a 429 Too Many Requests response. For adjustments to rate-limit configurations based on specific use cases, contact your Technical Account Manager.

🚧

Important:

Because of the inherent latency of LLMs, Shopping Muse should not be triggered automatically on page load. Instead, any experience powered by Shopping Muse should be reactive—initiated by user actions such as clicking an element, submitting a query, opening the cart, or answering a product finder. Triggering Shopping Muse outside of user-driven events risks unnecessary API calls and may cause you to hit the API rate limits.

Visual search integration

Note: In the previous Shopping Muse application, Visual Search was a native part of the experience. In the API model, it's a separate service and must be explicitly integrated.

In some Shopping Muse templates, the interface enables you to create interactions by uploading an image instead of entering a text query. In these cases, the search by image component is powered by Visual Search, part of the Experience Search app, and requires setting up a Visual Search experience in Experience OS.

If you want to create a custom assistant experience that also includes Visual Search functionality, follow the Visual Search API implementation guidelines. For details, see the Search API documentation.

Use case examples

The Shopping Muse API is designed to support a variety of commerce experiences where natural language understanding and real-time personalization are critical. The following are some common use cases:

Conversational shopping assistants

Integrate Shopping Muse into conversational shopping experiences to deliver dynamic, real-time product discovery. Users can engage in natural, free-flowing conversations (for example, "I'm looking for a lightweight running shoe") and receive intelligent, personalized product recommendations. This enhances the customer experience through interactive, responsive dialogue.

In this use case, the query represents the user's input, while the assistant provides the tailored response.

 "query": {
    "text": "Can you also help me find shoes to go with that dress?",
    "chatId": "gAAAAABn85XBEaWKxRxEABWj2P2E8VecQcjXv8qvaZEOs-PlP1Lbt8b4VjHvo1xWOmHTNF-QlD"
  }

Product finders

Use Shopping Muse to build interactive product finders that guide users through large catalogs using natural language prompts. You can support progressive journeys, where users answer one question at a time to refine options step-by-step, or batch journeys, where multiple preferences are collected upfront and recommendations are provided once all inputs are gathered.

This approach streamlines product discovery and makes it easier for users to find the right products.

 "query": {
    "text": "Suggest products based on these preferences: Skin type: Dry, Age: 44, Concern: Fine lines, Product type: Moisturizer, Texture preference: Lightweight cream, Additional preference: Fragrance-free."
  }

Product search scenarios

Enhance search experiences by integrating Shopping Muse to enable conversational, intent-driven search. Shopping Muse interprets the meaning behind user queries, supporting complex, descriptive, and contextual inputs. It can also proactively ask follow-up questions to refine results (for example, "summer dresses under $100" or "eco-friendly travel backpacks for hiking"), creating a more natural and effective product discovery journey.

 "query": {
    "text": "I'm looking for eco-friendly travel backpacks for hiking, preferably under $150."  }

Generative product grids

Use Shopping Muse to deliver tailored product grids by interpreting user input, browsing behavior, and contextual signals. This enables the creation of dynamic, personalized experiences—such as "Top Picks for You" sections, curated collections based on user questions, or real-time AI-driven suggestion modules that evolve as users engage with your platform.

 "query": {
    "text": "Suggest total look for 'Blue Midi Dress', from the 'dresses' category"
 }