Get product filter facets from the Ecwid API – find available values for specific product options, price, keywords, attributes and more.
There is a native product filters widget available for the Ecwid storefronts. Learn more about it in our Help Center.
Headers
Name
Type
Description
Authorization
string
oAuth token with mandatory Bearer before it. Example: Bearer e***s0, where e***s0 should be replaced with your oAuth token.
Request
All request parameters should be passed in the request body inside the 'params' object using the structure "Key": "Value"
Field
Type
Description
filterFields
string
Comma-separated list of filters for Ecwid to return. Supported filters: "price","inventory","onsale","categories", "option_{optionName}", "attribute_{attributeName}". Example: "price,inventory,option_Size,attribute_Brand,categories". If option or attrubute has a comma or a backslash in its name, escape it with a backslash: "\". I.e. option name "Color, size" will transform to "option_Color\, size" in your request.
Filter limits
Name
Type
Description
filterFacetLimit
string
Set the number of filter values in response. Individual limit example: "onsale:all,attribute_Brand:50,option_Color:10". General limit example: "10". Use "all" to return all facets. Default limit is 50
filterParentCategoryId
string
Set parent category ID limit for categories filter field in response. "0" or "home" or empty value means there is no parent category. If you want to limit product results by categories, use categories product limit field below
Product limits
Name
Type
Description
keyword
string
Search term. Use quotes to search for exact match. Ecwid searches products over multiple fields:
title
description
SKU
product options
category name
gallery image descriptions
attribute values (except for hidden attributes). If your keywords contain special characters, it may make sense to URL encode them before making a request
priceFrom
string
Minimum product price
priceTo
string
Maximum product price
categories
string
Limit results by category IDs separated by a comma. Use "home" to get Store Home Page products. Example: "18265,12324,home"
includeProductsFromSubcategories
string
Use "true" if you need to include products from subcategories. Use "false" otherwise. "false" is the default value
Product last create date/time (upper bound). Supported formats:
UNIX timestamp
updatedFrom
string
Product last update date/time (lower bound). Supported formats:
UNIX timestamp
updatedTo
string
Product last update date/time (upper bound). Supported formats:
UNIX timestamp
enabled
string
Use "true" if you need only enabled products. Use "false" if you need both enabled and disabled products
option_{optionName}
string
Filter by product option values. Format: option_{optionName}=param[,param], where optionName is the attribute name and param is the attribute value. You can place several values separated by comma. In that case, values will be connected through logical "OR", and if the product has at least one of them it will get to the search results. Example: option_Size=S,M,L&option_Color=Red,Black
attribute_{attributeName}
string
Filter by product attribute values. Format: attribute_{attributeName}param[,param], where attributeName is the attribute name and param is the attribute value. You can place several values separated by comma. In that case, values will be connected through logical "OR", and if the product has at least one of them it will get to the search results. Example: attribute_Brand=Apple&attribute_Capacity=32GB,64GB
inventory
string
Use "instock" to get in stock items only or "outofstock" for out of stock items.
onsale
string
Use "onsale" to get on sale items only or "notonsale" for items not currently on sale
lang
string
Preferred language for the translated filter fields in search results. If a certain field does not have the translation available for the set language, the default language text will be used for that field
Response
A JSON object of type 'SearchResult' with the following fields:
SearchResult
Field
Type
Description
productCount
number
The total number of found products
filters
<ProductFilters>
Store filters returned for this request
ProductFilters
Field
Type
Description
price
<PriceFilter>
Range of available prices
inventory
Array <FilterValue>
Available values for inventory filter
onsale
Array <FilterValue>
Available values for on sale filter
categories
Array <FilterValue>
List of categories result products are assigned to
option_{optionName}
Array <FilterValue>
List of available values for a specific product option
attribute_{attributeName}
Array <AttributesFilterValue>
List of available values for a specific product attribute
PriceFilter
Field
Type
Description
minValue
number
The minimum price found for these products
maxValue
number
The maximum price found for these products
FilterValue
Field
Type
Description
id
number/string
Filter value ID: category ID, "onsale", "outofstock"
title
string
Filter value name: option value, attribute value, "On sale", "Out of Stock", etc.
titleTranslated
string
Translated title for the current entity for the lang value provided in your request. If translation is not available, default langage translation is used
productCount
number
Number of products found for this specific filter
AttributesFilterValue
Field
Type
Description
name
string
Attribute name: "Brand", "Model number", etc.
nameTranslated
string
Translated name for the attribure for the lang value provided in your request. If translation is not available, default langage translation is used
value
string
Values of the specified attribute
valueTranslated
string
Translated values for the attribure for the lang value provided in your request.
productCount
number
Number of products found for this specific filter
Errors
In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description
HTTP codes
HTTP Status
Meaning
Code (optional)
400
Request parameters are malformed
400
Parameter filterFields is required
FILTER_FIELDS_REQUIRED
403
Access token doesn't have read_catalog scope
415
Unsupported content-type: expected application/json or text/json
500
Cannot complete request because of an error on the server
