Skip to content
Queries

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.

FieldTypeDefaultRules
includeFiltersBooleantrueWith 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.
searchString—Free text.
categories[String!]—Category names.
brands[String!]—Brand names.
sellerSlugs[String!]—Seller slugs.
collections[String!]—Collection slugs.
collectionIdString—A collection ID.
productTypes[ProductType!]—PRODUCT, SERVICE or BUNDLE.
tags[String!]—Tags.
filters[String!]—Up to 100 facets of up to 250 characters.
inStockBoolean—With true, only available products.
minPriceDecimal—Minimum price.
maxPriceDecimal—Maximum price.
pageInt11 to 100.
pageSizeInt241 to 100.
sortProductSearchSortDEFAULTResult order.

Each filters value takes one of these forms, with the name and value from filters in the response:

option:name:value
attribute:name:value

Pick one value per product option (a size, for example). Attributes accept several values.

ProductSearchSort

ValueOrder
DEFAULTDefault catalog order.
PRICE_ASCLowest price first.
PRICE_DESCHighest price first.
NEWESTNewest first.
NAME_ASCName, A to Z.
NAME_DESCName, Z to A.
OLDESTOldest first.
BEST_SELLINGBest sellers first; ties go to the newest.

SearchResult

FieldTypeDescription
pageIndexInt!Returned page.
pageSizeInt!Applied page size.
totalCountLong!Total matches.
totalPagesInt!Total pages.
products[ProductSummary!]!Products on the page.
filters[SearchFilter!]!Facets to refine the search.

ProductSummary

FieldTypeFieldType
idString!nameString!
slugString!urlString!
productTypeString!imageUrlString!
priceDecimal!compareAtPriceDecimal
variantCountInt!isAvailableBoolean!
totalInventoryInt!bundleItemsCountInt!
brandString!categoryString!
statusString!collections[String!]!
tags[String!]!sellerProductSellerInfo
options[ProductOptionGroup!]!images[ImageItem!]!
availableVariantIdStringreviews[StorefrontReviewDto!]!
  • url is the product's public path in the store.
  • seller has id, name and slug, all String!.
  • options groups variant values (key, name, type and values) so a card can show sizes and colors without fetching the details.
  • availableVariantId is the first available variant, or null when there is none.
  • reviews returns the first approved reviews of each product. See Reviews for each product.

SearchFilter

FieldTypeDescription
idString!Filter ID.
labelString!Display label.
typeString!Filter type.
values[FacetItem!]!Values and their counts.
minDecimalLowest available value, in range filters.
maxDecimalHighest available value, in range filters.
selectedMinDecimalSelected minimum.
selectedMaxDecimalSelected maximum.

FacetItem has value: String!, count: Int!, label: String and selected: Boolean!.

Example

Products.graphql
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"
  }
}
Terminal
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" }
    }
  }'
Response
{
  "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!]!
ArgumentDefaultRule
limit31 to 10. Out-of-range values are clamped to the nearest bound.
sortBycreatedOncreatedOn or rating, case-insensitive. Any other value returns BAD_USER_INPUT.
sortDirectionDepends on sortByASC 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.

ProductsWithReviews.graphql
query ProductsWithReviews($input: StorefrontProductsInput) {
  products(input: $input) {
    products {
      id
      name
      slug
      reviews(limit: 3, sortBy: "rating", sortDirection: DESC) {
        id
        rating
        title
        content
        reviewerName
        createdOn
      }
    }
  }
}
Response
{
  "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

CodeCause
BAD_USER_INPUTpage 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_FOUNDThe collection in collectionId doesn't exist.
STORE_CONTEXT_REQUIREDx-Store-Domain is missing or doesn't match a store.

REST equivalent

Products in REST takes the same filters as query parameters.

Last updated:

On this page