Product Filters API

Last updated

Faceted search (faceted navigation / filtered search) allows filtering and showing products in Ecwid storefront by the following parameters:

- prices
- categories
- attributes’ values
- keywords

You can use this new feature to:

- add a "smart" search (e.g. "find all products with keyword "chair" from the "Furniture" category") 
- build new dynamic store pages, i.e. new custom store navigation (e.g. "show all t-shirts which have Gender attribute = Male and where price is between $10 and $50").

How it works

To use the faceted search, you should form a special URL containing necessary parameters in the part of URL that goes after "search".

Here is an example illustrating how such a query looks like:

All parameters are surely optional and only one parameter would be mandatory. If you specify more than one parameter, you should link them with AND (displayed as &) – it will indicate that all the conditions in the URL are to be met. See more examples of the queries below.

List of search parameters:

  • priceFrom: the minimum products’ price (base price). The decimal separator is dot. No currency symbol.
  • priceTo: the maximum products’ price (base price). The decimal separator is dot. No currency symbol. 
  • category: the category ID, to which products belong. This partially duplicates functions of the Categories widget and provides you with the more flexible results. For example, you can mix several parameters: to select all the products which cost less than $30 and belong to the ‘t-shirt’ category. Instructions: How to get category ID
  • withSubcategory: whether to show products from subcategories, if the "category" parameter is indicated. Possible values: true, any other value is treated as false. 
  • field{Name}=param[,param]: search by product attributes. "Name" is the attribute name (spaces will work). "Param" is the attribute value. You can place several values separated by comma. In that case values will be connected through "OR", and if the product has at least one of them it will be shown. 
    Important note: if you need to search for an exact attribute value you should enclose it in the quotation marks. 
    For information about product attributes please refer to this article.
  • field{id}=param[,param]: it is the same parameter as field[Name] but attribute ID is used instead attribute name. In this case you need to get the attribute ID number through the API. It is more complex but resistant to attributes renaming.
  • keywords: it is a search string. The search result will be products with title, description, or some other fields containing these keywords.
  • inStock=true: returns the list of "In stock" products. Otherwise the search shows both "In stock" and "Out of stock" products. 


A very good example of how Faceted search may work can be viewed on Ecwid demo store:

All products under $50:

All products from the "Womens Apparel" category:
NOTE: the "withSubcategory" parameter is used with value "true" to show products from subcategories as a search result.

All products from the "Mens Apparel" category which price is from $50 to $60:

All products which contain the word "Boardshorts" from the "Mens Apparel" category (Match the "Boardshorts" word AND category = Mens Apparel incl. subcategories):

How can I use it on my site?

There are several ways to use this feature:

1. You can create links with a specific search query manually and place them on your site, or share them with your customers. For example, you can create a page listing all brands available in your store and link each brand's logo to a store page containing products that belong to this very brand only.

2. You can use our Product and JavaScript APIs to build such links automatically to expand the functionality of Ecwid's widgets. For example, create several drop-down menus and place them next to your Product browser and make each value in the drop down box open a page with products filtered by this value.

3. Check out ready applications in Ecwid App Market: Clickable Brand and Product Search Enhancer. They use Ecwid REST API and Product Filters functionality of storefront to provide enhanced experience for your customers.

Back to top
Has the article answered your question?

Awesome! Thanks for your feedback!

Please send us that question. We will be happy to help by email.

Send a message