Discovery
Search Products
Search for products across merchant catalogs using keyword-based queries with optional filters
POST
Search for products across merchant catalogs using keyword-based queries. Use filters to narrow results by domain, price, availability, and variant attributes.
Authentication
This endpoint supports two authentication methods:- Browser Session
- Server-to-Server
For client-side applications (browser, mobile). See Browser Session Authentication.
Request Body
Search keyword(s). Required for all search requests.
Optional filters to narrow search results.
Number of results per page. Maximum:
100Response
Array of product objects matching the search criteria. Returns empty array
[] when no results found (HTTP 200).Number of results returned in this page
Time taken to execute the search query in milliseconds
Full URL to fetch the next page of results. Use this URL directly with your authorization header.
null when there are no more results.Error Responses
| Status Code | Error | Description |
|---|---|---|
400 | InvalidRequest | Missing required query parameter or invalid parameter values |
401 | Unauthorized | Missing or invalid x-firmly-authorization header |
401 | TokenExpired | Authentication token has expired. Refresh and retry. |
403 | Forbidden | Token does not have permission for this operation |
429 | RateLimitExceeded | Too many requests. Check Retry-After header. |
500 | ErrorStoreUnavailable | Search service is temporarily unavailable |
503 | ServiceUnavailable | System maintenance in progress |
No results is not an error: When no products match your search criteria, the API returns HTTP
200 with an empty products array. This is standard REST behavior—404 is reserved for “resource not found” (e.g., invalid endpoints), not “no results found”.Usage Notes
Domain authorization: Search results are limited to merchant domains associated with your account. Requests for unauthorized domains will return empty results. Contact your account manager to request access to additional merchants.
Domain filtering: Use the
filters.domains array to search specific merchants:- Single merchant:
"domains": ["benchmademodern.com"] - Multiple merchants:
"domains": ["merchant1.com", "merchant2.com", "merchant3.com"] - All merchants: omit the
domainsfield entirely
Variant filtering: Use the
filters.variants array to filter by product attributes like color, size, or material. Each variant filter specifies an option name and an array of allowed values. Use the Options endpoint to discover available options and values.Filter matching: Variant filters use exact string matching. The values must match exactly as stored in the product data (e.g.,
"Blue" will not match "blue" or "Navy").Pricing: All prices are integers in USD cents (not dollars).
"min_price": 100000 filters for 2,499.99 USD. To display: (price / 100).toFixed(2).Data Types:
price_range.min, price_range.max are always integers in cents (e.g., 249999 for $2,499.99). has_available_variants is always a boolean (true or false). These are never returned as strings.Why cents? Integer cents avoid floating-point precision issues (e.g.,
0.1 + 0.2 !== 0.3 in JavaScript). This is the industry standard used by Stripe, PayPal, and other payment APIs.