Reference · Data models

This page lists the public Neuroon DTOs: the contract the widget signs against the API. The widget's canonical types live at and the backend's at api/src/main/java/.../dto/.

Product

The product as the widget receives it from SearchResponse.results[].

Field	Type	Required	Notes
id	string	yes	Neuroon UUID.
shopId	string	yes	Shop UUID.
shopName	string	yes	Shop name.
name	string	yes	Product name.
description	string	no
price	number	yes	Regular price.
salePrice	number	no	If present, computes discount.
currency	string	yes	ISO 4217.
url	string	yes	Final URL (host).
imageUrl	string	no
categories	string[]	yes
tags	string[]	yes
brands	string[]	yes
inStock	boolean	yes
score	number	no	Internal relevance score (debug).
rating	number	no	0-5.
reviewCount	number	no
stockCount	number	no	If ≤ 5, the widget shows a "Low stock" badge.
externalId	string	no	Host id (WC post_id, etc.) used for conversion tracking.
badge	enum	no	BESTSELLER | TRENDING | TOP_RATED.
aiReason	string	no	Conversational reason ("ideal for asphalt").
aiScore	number	no	AI re-ranker score.

Product (catalog) vs PluginProductDTO (sync)

Product is what the widget consumes when reading from the catalog. When you write products via POST /api/plugin/shops/{shopId}/products/sync, the shape is PluginProductDTO — broader (includes isActive, parentProductId, attributes, variants, etc.) and serialized by the backend at api/.../dto/PluginProductDTO.java. See API → Plugin Sync for the full shape.

SearchResponse

Canonical response of GET /api/widget/search and POST /api/widget/search. Type at.

Field	Type	Required	Notes
query	string	yes	Normalized query after post-process.
results	Product[]	yes
total	number	yes	Total products matching filters.
searchLogId	string	yes	Turn identifier (attribution).
queryTimeMs	number	yes	Backend latency.
intentId	string	no	Intent detection.
conversationId	string	no	Continuation across turns.
isNewConversation	boolean	no	true when a conversation started.
turnNumber	number	no	1, 2, 3…
filtersApplied	FiltersApplied	no	Filters applied to ranking.
availableFilters	AvailableFilters	no	Filter drawer.
guidedFilters	GuidedFilter[]	no	Dynamic questions.
querySuggestions	QuerySuggestion[]	no	Suggested refinements.
topProducts	TopProduct[]	no	Highlighted carousel.
aiResponse	string	no	Conversational text.
comparison	ComparisonResponse	no
clarification	ClarificationResult	no
buyersGuide	BuyersGuide	no
kit	ProductKit	no
followUp	FollowUpResponse	no
recommendations	RecommendationsResponse	no
cartAction	CartAction	no	Action requested from the widget.
quickReplies	QuickReply[]	no	Quick reply chips.
responseLanguage	string	no	ISO of the agent's language (es, en…).

CartState

interface CartState {
  items: CartItem[]
  totalItems: number
  subtotal: string   // host-formatted: "232,48 €"
  total: string      // host-formatted
  currency: string   // ISO 4217
  shipping?: CartShippingInfo
}

CartItem field	Type	Required	Notes
key	string	yes	Unique item identifier in the cart.
id	string	yes	Neuroon productId.
externalId	string	no	Host id (WC post_id).
name	string	yes
price	string	yes	Host-formatted.
quantity	number	yes
image	string	no
url	string	no
variant	string	no	"Size: 42, Color: Black".
maxQuantity	number	no

CartShippingInfo adds freeShippingThreshold, currentAmount, delta, thresholdMet, destinationCountry, availableCountries[], formattedThreshold and formattedDelta. See cart-integration for the flow.

Event (analytics)

Field	Type	Required	Notes
type	string	yes	snake_case (category_click, kit_view…).
searchLogId	string	recommended	Ties to a search turn.
metadata	object	no	Free-form pairs (no PII).
timestamp	ISO-8601 string	no	If omitted, the backend stamps it.

CartAction

type CartActionType = 'REMOVE' | 'UPDATE_QUANTITY' | 'ADD_SUGGESTION' | 'CLEAR' | 'SET_DESTINATION_COUNTRY'

interface CartAction {
  type: CartActionType
  productId?: string
  externalProductId?: string
  externalId?: string             // legacy alias
  itemKey?: string
  newQuantity?: number
  countryCode?: string             // ISO-3166-1 alpha-2 uppercase
  confirmationPrompt?: string
  product?: CartActionProduct      // only on ADD_SUGGESTION
}

Suggestion

interface Suggestion {
  type: 'query' | 'category' | 'brand' | 'product'
  text: string
  count?: number
  icon?: string
  product?: Product
}

GuidedFilter

interface GuidedFilter {
  id: string
  question: string
  type: 'SINGLE_CHOICE' | 'MULTI_CHOICE' | 'RANGE'
  priority: number
  options: FilterOptionDTO[]
}

interface FilterOptionDTO {
  label: string
  filter: Record<string, unknown>
  count?: number
  isSelected?: boolean
  isRecommended?: boolean
  detectionSource?: 'QUERY_ANALYSIS' | 'TRENDING' | 'INTENT_BASED'
  detectionReason?: string
}

Further reading

• Reference → Errors
• Reference → CSS variables
• Reference → Event bus
• Widget → Events