products
Search published products with filters, facets, sorting and pagination.
products searches the store's published catalog. Use it for listings, search results, and collection or seller pages.
products(input: StorefrontProductsInput): SearchResult!Without input, it returns the first page of 24 products in the default order.
Input
Every field is optional, and they combine.
| Field | Type | Default | Rules |
|---|---|---|---|
includeFilters | Boolean | true | With false, filters comes back empty. Use it for product shelves without a filter panel. |
productIds | [String!] | — | Up to 100 IDs. |
slugs | [String!] | — | Up to 100 slugs of up to 255 characters. Returns the products in list order. |
search | String | — | Free text. |
categories | [String!] | — | Category names. |
brands | [String!] | — | Brand names. |
sellerSlugs | [String!] | — | Seller slugs. |
collections | [String!] | — | Collection slugs. |
collectionId | String | — | A collection ID. |
productTypes | [ProductType!] | — | PRODUCT, SERVICE or BUNDLE. |
tags | [String!] | — | Tags. |
filters | [String!] | — | Up to 100 facets of up to 250 characters. |
inStock | Boolean | — | With true, only available products. |
minPrice | Decimal | — | Minimum price. |
maxPrice | Decimal | — | Maximum price. |
page | Int | 1 | 1 to 100. |
pageSize | Int | 24 | 1 to 100. |
sort | ProductSearchSort | DEFAULT | Result order. |
Each filters value takes one of these forms, with the name and value from filters in the response:
option:name:value
attribute:name:valuePick one value per product option (a size, for example). Attributes accept several values.
ProductSearchSort
| Value | Order |
|---|---|
DEFAULT | Default catalog order. |
PRICE_ASC | Lowest price first. |
PRICE_DESC | Highest price first. |
NEWEST | Newest first. |
NAME_ASC | Name, A to Z. |
NAME_DESC | Name, Z to A. |
OLDEST | Oldest first. |
BEST_SELLING | Best sellers first; ties go to the newest. |
SearchResult
| Field | Type | Description |
|---|---|---|
pageIndex | Int! | Returned page. |
pageSize | Int! | Applied page size. |
totalCount | Long! | Total matches. |
totalPages | Int! | Total pages. |
products | [ProductSummary!]! | Products on the page. |
filters | [SearchFilter!]! | Facets to refine the search. |
ProductSummary
| Field | Type | Field | Type |
|---|---|---|---|
id | String! | name | String! |
slug | String! | url | String! |
productType | String! | imageUrl | String! |
price | Decimal! | compareAtPrice | Decimal |
variantCount | Int! | isAvailable | Boolean! |
totalInventory | Int! | bundleItemsCount | Int! |
brand | String! | category | String! |
status | String! | collections | [String!]! |
tags | [String!]! | seller | ProductSellerInfo |
options | [ProductOptionGroup!]! | images | [ImageItem!]! |
availableVariantId | String | reviews | [StorefrontReviewDto!]! |
urlis the product's public path in the store.sellerhasid,nameandslug, allString!.optionsgroups variant values (key,name,typeandvalues) so a card can show sizes and colors without fetching the details.availableVariantIdis the first available variant, ornullwhen there is none.reviewsreturns the first approved reviews of each product. See Reviews for each product.
SearchFilter
| Field | Type | Description |
|---|---|---|
id | String! | Filter ID. |
label | String! | Display label. |
type | String! | Filter type. |
values | [FacetItem!]! | Values and their counts. |
min | Decimal | Lowest available value, in range filters. |
max | Decimal | Highest available value, in range filters. |
selectedMin | Decimal | Selected minimum. |
selectedMax | Decimal | Selected maximum. |
FacetItem has value: String!, count: Int!, label: String and selected: Boolean!.
Example
query Products($input: StorefrontProductsInput) {
products(input: $input) {
pageIndex
pageSize
totalCount
totalPages
products {
id
name
slug
imageUrl
price
compareAtPrice
isAvailable
brand
seller { id name slug }
}
filters {
id
label
type
min
max
values { value count label selected }
}
}
}{
"input": {
"search": "mug",
"categories": ["Home"],
"inStock": true,
"pageSize": 24,
"sort": "PRICE_ASC"
}
}curl --request POST "https://storefront.ecomiq.pe/graphql" \
--header "Content-Type: application/json" \
--header "x-Store-Domain: my-store" \
--data-binary '{
"query": "query Products($input: StorefrontProductsInput) { products(input: $input) { pageIndex pageSize totalCount totalPages products { id name slug imageUrl price compareAtPrice isAvailable brand seller { id name slug } } filters { id label type min max values { value count label selected } } } }",
"variables": {
"input": { "search": "mug", "categories": ["Home"], "inStock": true, "pageSize": 24, "sort": "PRICE_ASC" }
}
}'{
"data": {
"products": {
"pageIndex": 1,
"pageSize": 24,
"totalCount": 1,
"totalPages": 1,
"products": [
{
"id": "789",
"name": "Ceramic mug",
"slug": "ceramic-mug",
"imageUrl": "/mug.jpg",
"price": 12,
"compareAtPrice": null,
"isAvailable": true,
"brand": "Acme",
"seller": null
}
],
"filters": []
}
}
}Reviews for each product
For each product in the result, reviews returns the same first page as productReviews with the same limit, sortBy and sortDirection.
reviews(limit: Int, sortBy: String, sortDirection: SortDirection): [StorefrontReviewDto!]!| Argument | Default | Rule |
|---|---|---|
limit | 3 | 1 to 10. Out-of-range values are clamped to the nearest bound. |
sortBy | createdOn | createdOn or rating, case-insensitive. Any other value returns BAD_USER_INPUT. |
sortDirection | Depends on sortBy | ASC or DESC. Without a value, createdOn uses DESC and rating uses ASC. |
A product with no approved reviews returns []. For a cursor, search or rating filter, use productReviews.
query ProductsWithReviews($input: StorefrontProductsInput) {
products(input: $input) {
products {
id
name
slug
reviews(limit: 3, sortBy: "rating", sortDirection: DESC) {
id
rating
title
content
reviewerName
createdOn
}
}
}
}{
"data": {
"products": {
"products": [
{
"id": "456",
"name": "Mug",
"slug": "mug",
"reviews": [
{
"id": "7204558912004325999",
"rating": 5,
"title": "Excellent",
"content": "Arrived fast and well packed.",
"reviewerName": "Ana",
"createdOn": "2026-08-25T15:30:00Z"
}
]
}
]
}
}
}Errors
| Code | Cause |
|---|---|
BAD_USER_INPUT | page or pageSize outside 1–100, an invalid ID, more than 100 IDs, slugs or filters, a malformed filter, two values for the same option, or a reviews sortBy other than createdOn and rating. |
NOT_FOUND | The collection in collectionId doesn't exist. |
STORE_CONTEXT_REQUIRED | x-Store-Domain is missing or doesn't match a store. |
REST equivalent
Products in REST takes the same filters as query parameters.
Last updated: