Built-in filtering and sorting in the same /v1/search/component call
Typo-tolerant fuzzy matching
Synonym handling to recover poor or uncommon queries (see Synonyms)
Search redirects, which send a search straight to a specific page, aren't managed in the Malachyte Portal.
Search behavior is configured in the Portal, so it can be changed without frontend code changes or redeploys. Queries can be tested in the Search Playground.
Use these query parameters in Pagination Mode (Option A):
Parameter
Type
Behavior
page
Integer
Which page of results to return. Pages start at 1.
size
Integer
How many results to return per page.
For example, with size=40, page=1 returns results 1–40 and page=2 returns results 41–80 (for example, when the shopper clicks "Page 2" or "Load more").
Estimated before filters: The count is calculated before any filters (price, size, color, etc.) are applied, so a filtered search may show a higher total than the number of results that can actually be paged through.
Capped at 10,000: Very broad searches will report a maximum of 10,000 results.
Important
Treat the total count as an estimate when filters are active. Use it for display text, not to calculate the exact number of pages.
The UUID of the search component configured in Malachyte that defines the search logic, strategy, and ranking rules. It's available via the Portal.
visitor_id
string
Yes
A unique ID for the shopper's browser. On Shopify stores, it's generated automatically. On headless stores, the client sets it up on their side: generate one (for example, a UUID), store it in localStorage so it stays the same across visits, and send the same ID in pixel events. See Headless.
k
integer
Conditionally
Number of items to return. Required for Large-k mode or the first request in Pagination Option B.
search_filters
Filter[]
Optional
List of Filter objects to apply to the results. Uses the same Filter object as the PLP API.
catalog
integer
Optional
The catalog identifier. Only needed if the store has more than one catalog (for example, two storefronts or brands under one Malachyte account). Defaults to -1 when left out. The client's Malachyte contact provides the value.
sort_order
string (SortOrder)
Optional
Sort order to apply to the results. Default is "RECOMMENDED". See Supported Sort Orders below.
return_filters
boolean
Optional
Whether to return assigned filter values, search filter definitions, and facet options in the response. Defaults to true.
allow_empty_query
boolean
Optional
Whether to return results when query is an empty string.
user_id
string
Optional
The unique identifier of the logged-in shopper. It stays the same across sessions. Leave blank if the shopper isn't logged in.
Filtering and sorting are handled within the POST /v1/search/component call described above.
Filtering: pass search_filters in the request body. Search uses the same Filter object as PLP. See Filtering in the Listing Request for the full structure and supported operators.
Sorting: pass sort_order in the request body. If it's left out, results use RECOMMENDED.
results: the matching products, in ranked order. Each has a score and its product data in facts.
facts: the product fields set up for the search component. Some setups return only product_id, and the storefront looks up the rest of the product details itself. Field names depend on the client's setup, so the examples here are only examples.
assigned_filter_values: the values available for each filter in these results, with a count of how many results have each value. It's keyed by the filter id from search_filters, for example:
Errors return the matching HTTP status code and a JSON body with a detail message:
{"detail": "Search component request must include a search_component_id"}
Status Code
Description
Reason
400 Bad Request
Malformed request
search_component_id is missing ("Search component request must include a search_component_id"), query is missing ("Malformed request: query missing"), or both user_id and visitor_id are missing ("Malformed request: user_id and visitor_id missing").
400 Bad Request
Unknown search component
The search_component_id doesn't match a search component in the Portal ("Unknown Search Component: <id>").
401 Unauthorized
Invalid API key
The x-api-key header is missing or wrong.
404 Not Found
No results found
No matching products were found, or all results were filtered out ("No search results found: All candidates filtered, try loosening filter criteria.").
422 Unprocessable Entity
Validation error
Invalid request payload or parameter types (for example, a string sent for k).
500 Internal Server Error
Unexpected error
An unexpected server error occurred ("internal_server_error").
503 Service Unavailable
Service unavailable
Malachyte couldn't process the request right now. Retry the request; if the error persists, contact Malachyte.
Note
A 404 means the search ran but returned no results. Treat it as an empty result set (for example, show a "No results" message) rather than a failure.
Data Integrity & Tracking
These fields are essential for measuring search performance and ROI.
visitor_id: a unique ID for the shopper's browser. On Shopify stores, it's generated automatically. On headless stores, the client sets it up on their side. Use the same ID that's sent in pixel events.
user_id: Identifies a logged-in shopper and stays the same across sessions.