/api/v1/search,
/api/v1/merchants/{merchantId}/search, /api/catalog, and the
omni_search_catalog MCP tool. Chat is scoped to the deployment’s organization
and excludes drafts and private seller data. A category or query is optional.
The query also searches current public ACO FAQ questions and answers. Results
include
faqs, grouped by language with question, answer, and rank. Rejected
FAQs and historical profiles are excluded. Variants use their own ACO profile
when present and otherwise inherit the parent’s current profile, matching the
public product page. For example, {"query":"dual monitor"} can find a product
whose FAQ covers dual monitor compatibility even if its title does not.
With sort=relevance (the default), title and SKU matches score 3; description,
brand, and category matches score 2; and FAQ matches score 1. Scores add across
matching fields, so a FAQ-only match ranks below any of these catalog fields.
Matching multiple FAQs or marketplace categories does not multiply their score.
Explicit newest, price, and rating sorts use their selected metric instead.
Brand and category filters can combine with these arguments. Search supports
every platform in OmniCommerce’s canonical marketplace list. Variant option
filters are exact, case-insensitive matches; all requested options must match
the same variant. Pagination uses limit and offset.
newest sorts by catalogAddedAt, the date the catalog record was created,
independently of later edits. It does not establish a release date or physical
stock arrival. addedAfter is an inclusive timestamp with a time zone.
Price ranges and price sorting use catalogPrice, the listed catalog price,
and require a three-letter currency. Bounds are inclusive and may be zero.
Products without a catalog price cannot match a budget. Prices with unknown or
different currencies are excluded when a currency is selected. Marketplace
offers remain separately labeled by currency and may have different prices.
There is no implicit currency conversion or global cheapest ranking across
currencies.
Ratings average the imported, visible, valid 1–5-star product reviews for the
product family. A marketplace filter also scopes the rating to that platform.
The result includes rating.average, rating.reviewCount, rating.scale, and
rating.source. Missing ratings return null and do not match minRating.
Review requests, hidden reviews, invalid ratings, and private buyer details are
excluded. These are imported review aggregates, not guaranteed lifetime
marketplace totals. most_reviewed ranks review count, not sales or best sellers.
Storefront results include review coverage limitations from the shared
marketplace capability service. Shopee and Lazada currently have review read
integrations. TikTok requires enablement, Shopify Shop reviews have no supported
integration, and Zalora and eBay lack a confirmed product-review API in this
integration. Amazon supports review requests rather than importing individual
product reviews. WhatsApp has no product reviews. Catalog discovery and purchase
links remain available for all these platforms.
Unknown inventory remains inStock: null; it matches neither an in-stock nor an
out-of-stock filter.
For HTTP search, use min_price, max_price, min_rating, min_review_count,
added_after, variant_options, and in_stock. variant_options is a
URL-encoded JSON array. Invalid ranges, ratings, options, or price requests
without a currency return HTTP 400.