NAV

Get store filters

Each store has general set of filter facets enabled by default: filter by price, availability, availability in stock, whether it belongs to a specific category and whether it’s on sale.

Store owners can also choose their own set of product filters, for example: specific product options, like Size and Color, or attributes, like Brand.

The product options and attribute names are available in the product details. So first you should learn what kind of options and attributes a merchant’s store has by inspecting the catalog.

Afterwards, can get store filter facets from the Ecwid API – find available values for specific product options, price, keywords, attributes and more.

Request example

GET /api/v3/4870020/products/filters?filterParentCategoryId=123532&inventory=instock&lang=ru&token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache
Accept-Encoding: gzip

GET https://app.ecwid.com/api/v3/{storeId}/products/filters?filterFields={filterFields}&filterFacetLimit={filterFacetLimit}&filterParentCategoryId={filterParentCategoryId}&keyword={keyword}&priceFrom={priceFrom}&priceTo={priceTo}&categories={categories}&includeProductsFromSubcategories={includeProductsFromSubcategories}&createdFrom={createdFrom}&createdTo={createdTo}&updatedFrom={updatedFrom}&updatedTo={updatedTo}&enabled={enabled}&inventory={inventory}&onsale={onsale}&field{attributeName}={attributeValues}&field{attributeId}={attributeValues}&option_{optionName}={optionValues}&attribute_{attributeName}={attributeValues}&lang={lang}&token={token}

Filter limits

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
filterFieldsstringComma-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"
filterFacetLimitstringSet 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
filterParentCategoryIdstringSet 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

NameTypeDescription
keywordstringSearch 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
priceFromnumberMinimum product price
priceTonumberMaximum product price
categoriesstringLimit results by category IDs separated by a comma. Use "home" to get Store Home Page products. Example: "18265,12324,home"
includeProductsFromSubcategoriesbooleanUse true if you need to include products from subcategories. Use false otherwise. false is the default value
createdFromstringProduct create date/time (lower bound). Supported formats:
  • UNIX timestamp
Example:
  • 1447804800
createdTostringProduct last create date/time (upper bound). Supported formats:
  • UNIX timestamp
updatedFromstringProduct last update date/time (lower bound). Supported formats:
  • UNIX timestamp
updatedTostringProduct last update date/time (upper bound). Supported formats:
  • UNIX timestamp
enabledbooleanUse true if you need only enabled products. Use false if you need both enabled and disabled products
option_{optionName}stringFilter 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}stringFilter 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
inventorystringUse "instock" to get in stock items only or "outofstock" for out of stock items.
onsalestringUse "onsale" to get on sale items only or "notonsale" for items not currently on sale
langstringPreferred 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

Response example (JSON)

{
    "productCount": 45,
    "filters": {
        "price": {
            "minValue": 0,
            "maxValue": 14776.3
        },
        "inventory": {
            "values": [
                {
                    "id": "instock",
                    "title": "In stock",
                    "productCount": 35
                },
                {
                    "id": "outofstock",
                    "title": "Out of stock",
                    "productCount": 10
                }
            ]
        },
        "onsale": {
            "values": [
                {
                    "id": "notonsale",
                    "title": "Regular price",
                    "productCount": 43
                },
                {
                    "id": "onsale",
                    "title": "On sale",
                    "productCount": 2
                }
            ]
        },
        "categories": {
            "values": [
                {
                    "id": 19563207,
                    "title": "Shorts",
                    "titleTranslated": "Шорты",
                    "productCount": 5
                },
                {
                    "id": 21579001,
                    "title": "Hats",
                    "titleTranslated": "Шляпы",
                    "productCount": 4
                },
                {
                    "id": 21898001,
                    "title": "Sale",
                    "titleTranslated": "Распродажа",
                    "productCount": 2
                },
                {
                    "id": 22515002,
                    "title": "Accessories",
                    "titleTranslated": "Аксессуары",
                    "productCount": 2
                }
                {
                    "id": 19976009,
                    "title": "Apparel",
                    "titleTranslated": "Apparel",
                    "productCount": 2
                }
            ]
        },
        "attribute_Brand": {
            "values": [
                {
                    "title": "Sunshine",
                    "productCount": 2
                },
                {
                    "title": "Envelope",
                    "productCount": 1
                }
            ]
        },
        "option_Size": {
            "title": "Size",
            "titleTranslated": "Размер",
            "values": [
                {
                    "title": "S",
                    "titleTranslated": "S",
                    "productCount": 7
                },
                {
                    "title": "L",
                    "titleTranslated": "L",
                    "productCount": 6
                },
                {
                    "title": "M",
                    "titleTranslated": "M",
                    "productCount": 6
                },
                {
                    "title": "Large",
                    "titleTranslated": "Large",
                    "productCount": 4
                },
                {
                    "title": "Medium",
                    "titleTranslated": "Medium",
                    "productCount": 4
                },
                {
                    "title": "Small",
                    "titleTranslated": "Small",
                    "productCount": 4
                },
                {
                    "title": "XL",
                    "titleTranslated": "XL",
                    "productCount": 4
                },
                {
                    "title": "2XL",
                    "titleTranslated": "2XL",
                    "productCount": 3
                }
            ]
        }
    }
}

A JSON object of type ‘SearchResult’ with the following fields:

SearchResult

FieldTypeDescription
productCountnumberThe total number of found products
filters<ProductFilters>Store filters returned for this request

ProductFilters

FieldTypeDescription
price<PriceFilter>Range of available prices
inventoryArray <FilterValue>Available values for inventory filter
onsaleArray <FilterValue>Available values for on sale filter
categoriesArray <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 <FilterValue>List of available values for a specific product attribute

PriceFilter

FieldTypeDescription
minValuenumberThe minimum price found for these products
maxValuenumberThe maximum price found for these products

FilterValue

FieldTypeDescription
idnumber/stringFilter value ID: category ID, "onsale", "outofstock"
titlestringFilter value name: option value, attribute value, “On sale”, “Out of Stock”, etc.
titleTranslatedstringTranslated title for the current entity for the lang value provided in your request. If translation is not available, default langage translation is used
productCountnumberNumber of products found for this specific filter

Errors

Error response example

HTTP/1.1 400 Bad request
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaningCode (optional)
400Request parameters are malformed
403Access token doesn’t have read_catalog scope
415Unsupported content-type: expected application/json or text/json
500Cannot complete request because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message