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 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. While similar to the Choose API, it features some differences in object structure—particularly in the query object.

Query object (request)

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"
 }