Skip to content

Search products

GET
/public/stores/{storeRef}/search/catalog
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/public/stores/example/search/catalog?q=T-shirt&collection=products&page=1&page_size=10&sort_by=min_price%3Aasc&min_price=10&max_price=100&variant_mode=single&has_promotion=true&collection_slug=summer-sale&ids=1&ids=2&ids=3' \
--header 'x-storefront-api-key: <x-storefront-api-key>'

Searches the store’s products with typo tolerance and meaning-based matching. collection must be products. Only active products published to the online store are searched. Page with page and page_size (at most 100), sort with sort_by (up to three field:asc|desc pairs), and narrow with min_price, max_price, variant_mode, has_promotion, collection_slug or ids. Use q=* to list products without a search term.

storeRef
required
string

The store’s ref, as returned by GET /stores.

q
required
string

Example

T-shirt

The search query string

collection
required
string

Example

products

The collection to search within

page
number
default: 1 >= 1

Example

1

Page number for pagination (1-based)

page_size
number
default: 10 >= 1 <= 100

Example

10

Number of items per page

sort_by
string
/^(?:(?:_text_match|store_id|name|min_price|max_price|max_discount_percentage|updated_at|created_at|promotion_start_date|promotion_end_date|total_sales|sales_last_30_days|trending_score|view_count|view_count_last_7_days|rating_average|review_count|variant_count|published_at):(?:asc|desc))(?:,(?:_text_match|store_id|name|min_price|max_price|max_discount_percentage|updated_at|created_at|promotion_start_date|promotion_end_date|total_sales|sales_last_30_days|trending_score|view_count|view_count_last_7_days|rating_average|review_count|variant_count|published_at):(?:asc|desc)){0,2}$/

Example

min_price:asc

Sort order for results: field:asc|desc, up to 3 comma-separated. Products sort by: _text_match, store_id, name, min_price, max_price, max_discount_percentage, updated_at, created_at, promotion_start_date, promotion_end_date, total_sales, sales_last_30_days, trending_score, view_count, view_count_last_7_days, rating_average, review_count, variant_count, published_at

min_price
string

Example

10

Minimum price for filtering

max_price
string

Example

100

Maximum price for filtering

variant_mode
string

Example

single

Variant mode for filtering

has_promotion
string

Example

true

Filter products with active promotions

collection_slug
string

Example

summer-sale

Filter products by collection slug

ids
Array<number>

Example

[
1,
2,
3
]

Array of product IDs to filter by

Media typeapplication/json
object
facet_counts
required

For each faceted field, how many matches carry each value. Empty when the response is read from the database.

Array<object>
object
key
additional properties
any
data

The matches on this page. Present on results from the search index.

Array<object>
object
document
required

The indexed record. For products it holds fields such as id, name, slug, description, main_image_url, min_price, max_price, has_promotion, variant_mode and rating_average; for blog posts, id, title, slug, excerpt and published_at.

object
key
additional properties
any
highlight

Highlighted fragments of the matched fields, keyed by field name. Absent on results read from the database.

object
key
additional properties
any
highlights

The same fragments as a list, one entry per matched field. Absent on results read from the database.

Array<object>
object
key
additional properties
any
hits

The matches on this page. Present instead of data when the response is read directly from the database, which happens for a manual collection that keeps its hand-picked order.

Array<object>
object
document
required

The indexed record. For products it holds fields such as id, name, slug, description, main_image_url, min_price, max_price, has_promotion, variant_mode and rating_average; for blog posts, id, title, slug, excerpt and published_at.

object
key
additional properties
any
highlight

Highlighted fragments of the matched fields, keyed by field name. Absent on results read from the database.

object
key
additional properties
any
highlights

The same fragments as a list, one entry per matched field. Absent on results read from the database.

Array<object>
object
key
additional properties
any
request_params

The request parameters as the search ran them. Absent on results read from the database.

object
per_page
required

Number of matches per page.

number
q
required

The search query.

string
found
required

Total number of records that match, across all pages.

number
page
required

The page these results belong to, starting at 1.

number

Example generated

{
"facet_counts": [
{}
],
"data": [
{
"document": {},
"highlight": {},
"highlights": [
{}
]
}
],
"hits": [
{
"document": {},
"highlight": {},
"highlights": [
{}
]
}
],
"request_params": {
"per_page": 1,
"q": "example"
},
"found": 1,
"page": 1
}

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}