Skip to main content
GET
Search Products (Query-String Form)
Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See Authentication & Base URLs. Structured fields such as facets and filters must be JSON-encoded into the query string; a malformed value is silently ignored rather than rejected, so an encoding mistake looks like the parameter having no effect. To send them as real JSON, use Search Products (POST).

Headers

x-tenant-id
string
required

Identifies your organization. Ensures data isolation per tenant.

x-workspace-id
string
required

Identifies the workspace within your organization. Scopes resources to a specific workspace.

x-environment-id
string
required

Identifies the environment you are targeting. Scopes the call to a specific deployment environment.

Query Parameters

catalog_id
string<uuid>
required

The catalog to search. Every request is scoped to a single catalog.

q
string

The shopper's search term. Leave it out to browse instead of search — combine that with category_id or collection_id to list everything in a category or collection.

locale
string

Locale to run the search in, such as en-us. Determines which localized product content is matched and returned.

category_id
string

Restrict results to a single category, identified by its id in your commerce platform.

collection_id
string<uuid>

Restrict results to a single Experro collection, identified by its Experro collection id.

category_name
string

Restrict results to a single category by name rather than id. Use this when you have the category name but not its id.

fields
string

Fields to return for each product. Complex/nested field: pass as a JSON-encoded string. Parsed server-side by SearchProductsGetQuery::into_payload_parts.

skip
integer
limit
integer
sort_by
string

Free-text name of the field to sort by, for example price.

Example:

"price"

sort_order
enum<string>
default:desc

Sort direction, paired with sort_by.

  • asc — lowest to highest.
  • desc — highest to lowest. This is the default.

Case-insensitive; any other value falls back to descending.

Available options:
asc,
desc
include_count
boolean
is_auto_spell_correction
boolean
is_auto_spell_correction_zero_results
boolean
did_you_mean_limit
integer
session_id
string
user_id
string

Body-level user id passed to search_params (distinct from the x-user-id header).

facets
string

Facet selections used to narrow the search. One entry per faceted field, each shaped { "field": ..., "value": { "value": ..., "min": ..., "max": ... } } — set value.value for a categorical facet, or value.min and value.max for a numeric range facet. Pass as a JSON-encoded string; it is parsed server-side. A malformed value is silently ignored rather than rejected.

filters
string

Filter criteria applied to the search. Each entry is either a condition { "action": ..., "field": ..., "value": ... } or a nested group { "group": { "operator": "and" | "or", "rules": [ ... ] } }. action is one of equals, not_equals, greater_than, less_than, greater_than_or_equal, less_than_or_equal, contains, or not_contains. A condition value may be a single value, a two-element [min, max] array for a range, or an array of values for membership. Pass as a JSON-encoded string; it is parsed server-side. A malformed value is silently ignored rather than rejected.

currency
string
out_of_stock
enum<string>

Controls how out-of-stock products are treated in results.

  • Include — included and ranked normally.
  • Exclude — removed from results entirely.
  • Burry — included but ranked lower.
Available options:
Include,
Exclude,
Burry
auto_redirect
boolean
variation_map_group_by
string

Groups variant results by a product attribute for variant and swatch mapping. Each entry is { "name": ..., "field": ... }. Complex/nested field: pass as a JSON-encoded string. Parsed server-side by SearchProductsGetQuery::into_payload_parts.

variation_map_group_values
string

Computed aggregate values returned per variation group. Each entry is { "name": ..., "aggregation": ..., "field": ..., "value": null }, where aggregation is one of First, Last, Min, Max, Count, Avg, Sum, FieldCount, or ValueCount. Complex/nested field: pass as a JSON-encoded string. Parsed server-side by SearchProductsGetQuery::into_payload_parts.

hero_variant_option_override
string

Forces which variant option is shown as the hero, meaning the default image, for a product. Shaped { "field": ..., "value": ... }. Complex/nested field: pass as a JSON-encoded string. Parsed server-side by SearchProductsGetQuery::into_payload_parts.

location
string
price_group
string
currency_conversion_rate
number
selected_variant_fields
string

Complex/nested field: pass as a JSON-encoded string. Parsed server-side by SearchProductsGetQuery::into_payload_parts.

skip_facet_generation
boolean

Response

Success.

The product-search payload. Returned at the top level, with no envelope.

records
object[]

Ranked product records for the current page.

facets
object[] | null

Facets generated for the result set. Null when skip_facet_generation is true.

banners
object[] | null

Banners to render alongside the results. Null when none apply.

meta
object

Result metadata for the query.