Shopping Muse

For the request structure, see the API reference.

The Shopping Muse API 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. Shopping Muse API, which uses the Assistant endpoint , is similar to the Choose API, sharing 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.

Query object (request)

chatId field (request & response)

To maintain conversational continuity, the Shopping Muse API uses a chatId. The chatId is an opaque identifier that references the conversation on the server side. It doesn't contain the conversation contents.

The first request must omit the chatId field entirely. Don't send an empty chatId.

The first response includes a chatId. From the second request onward, include that same chatId in every request for the rest of the conversation. The same chatId is also returned in each subsequent response.

For example:

• First request: No chatId
• First response: Contains chatId_123
• Second request: Include chatId_123
• Second response: Contains chatId_123
• Third request: Include chatId_123

And so on.

This ensures that Shopping Muse can maintain context across the entire conversation.

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

• Section limit: 1000 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"
 }