Skip to main content

Search

The Storefront API provides product search with full-text matching across product names, descriptions, SKUs, and attribute values.

Search Products​

GET /api/storefront/products/search?q=t-shirt&page=1&pageSize=20
X-Store-Code: us-store
X-Language-Code: en
X-Currency-Code: USD

Response: Same paginated format as the category product listing:

{
  "products": [...],
  "page": 1,
  "pageSize": 20,
  "totalCount": 5,
  "totalPages": 1
}

POST /api/storefront/products/search takes the filters as a JSON body and is what listing screens, content blocks and apps use:

POST /api/storefront/products/search
X-Store-Code: us-store
X-Language-Code: en
Content-Type: application/json

{
  "page": 1,
  "pageSize": 20,
  "categoryId": "guid",
  "productIds": ["guid", "guid"],
  "brandIds": ["guid"],
  "priceMin": 1000,
  "priceMax": 50000,
  "appliedFacets": [],
  "sortBy": "price",
  "sortOrder": "asc"
}

All filters are optional and combine. categoryId accepts a master or a sales category. productIds restricts the result to a curated selection — a content block's hand-picked products, a favourites list; results come back in the default sort, so a client that needs the hand-picked order re-orders by its own list.

Each product card carries imageUrl (the primary still image — safe for a plain <img>) and images, the default variant's full gallery, primary first, for clients that show a swipeable gallery per card. Entries have url, altText, isPrimary, displayOrder, mediaType (image or video) and mimeType. Request a rendition by appending ?width=400 (or another configured width) to an image url.

Facets​

The response's dynamicFacets are computed over the current result set, each with a key, a localized label and its values (id, value, count, isSelected). Two kinds exist:

  • Variant attributes (colour, size …) — key is the attribute name, e.g. renk.
  • Specifications marked Use as a search filter in the Backoffice — key is spec: plus the specification's name, e.g. spec:tas. Only option-based specifications (dropdown, radio, checkbox) qualify; free-text values are never grouped.

Apply a selection by sending the facet's key and the chosen value ids back:

"appliedFacets": [
  { "facetKey": "spec:tas", "valueIds": ["guid-of-Pırlanta"] },
  { "facetKey": "renk", "valueIds": ["guid-of-Beyaz-Altın"] }
]

Values within one facet are OR-ed, different facets are AND-ed. Counts are disjunctive: a facet's own selection does not reduce its sibling values, so the customer can still see — and add — the alternatives.

Rate Limiting​

Where the installation has rate limiting switched on, search is limited per client — 60 requests per minute by default, counted per signed-in user or otherwise per address. One visitor's searching never uses up another's allowance.

If rate limited, you'll receive:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Search Tips​

  • Search is case-insensitive
  • Results are filtered by the current store context (store mappings apply)
  • Only active products are returned
  • Prices are pre-resolved for the requested currency
  • Results are cached for 2 minutes per unique query + store/language/currency combination

If Qdrant is configured, the API can provide semantic/vector-based search for more intelligent results (e.g., searching "summer outfit" returns relevant products even if those exact words aren't in the product title). This is an optional enhancement — standard text search works without Qdrant.