Get product filters

POST https://app.ecwid.com/api/v3/{storeId}/products/filters

Request and response example

Request:

POST /api/v3/1003/products/filters HTTP/1.1
Authorization: Bearer secret_token
Host: app.ecwid.com
Content-Type: application/json

{
   "params": {
      "enabled": "true",
      "filterFacetLimit": "200",
      "filterFields": "price,inventory,onsale,categories,attribute_Brand,option_Size",
      "includeProductsFromSubcategories": "true",
      "lang": "en"
   }
}

Response:

{
  "productCount": 2,
  "filters": {
    "price": {
      "minValue": 27.5,
      "maxValue": 77,
      "status": "SUCCESS"
    },
    "inventory": {
      "values": [
        {
          "id": "instock",
          "title": "In stock",
          "productCount": 2
        }
      ],
      "status": "SUCCESS"
    },
    "onsale": {
      "values": [
        {
          "id": "notonsale",
          "title": "Regular price",
          "productCount": 2
        }
      ],
      "status": "SUCCESS"
    },
    "categories": {
      "values": [
        {
          "id": 172966754,
          "title": "Not toys",
          "productCount": 1
        },
        {
          "id": 172786255,
          "title": "Toys",
          "productCount": 1
        }
      ],
      "status": "SUCCESS",
      "sortingOrder": "PRODUCTS_COUNT_DESC"
    },
    "attribute_Brand": {
      "title": "Brand",
      "values": [
        {
          "title": "LIGHTSPEED",
          "productCount": 1
        },
        {
          "title": "Test_Brand",
          "productCount": 1
        }
      ],
      "status": "SUCCESS",
      "sortingOrder": "FILTER_VALUE_ASC"
    },
    "option_Size": {
      "title": "Size",
      "values": [
        {
          "title": "24",
          "productCount": 1
        },
        {
          "title": "28",
          "productCount": 1
        },
        {
          "title": "32",
          "productCount": 1
        }
      ],
      "status": "SUCCESS",
      "sortingOrder": "FILTER_VALUE_ASC"
    }
  }
}

Required access scopes

Your app must have the following access scopes to make this request: read_catalog

Path params

All path params are required.

Param	Type	Description
storeId	number	Ecwid store ID.

Query params

Request requires one query param.

Name	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 an option or attribute has a comma or backslash in its name, escape it with a backslash: "\". I.e. option name "Color, size" will transform to "option_Color\, size" when used in query param.

Headers

The Authorization header is required.

Header	Format	Description
Authorization	Bearer secret_ab***cd	Access token of the application.

Request JSON

A JSON object with the following fields:

Field	Type	Description
params	object params	Filtering params for the request.

params

Field	Type	Description
filterFields	string	String that defines all applied filtering params, for example: "price,inventory,option_Size,attribute_Brand,categories". Full list of supported filters: "price" "inventory" "onsale" "categories" "option_{optionName}" "attribute_{attributeName}" If an option/attribute has a comma or a backslash in its name, escape it with a backslash \. For example, an option named "Color, size" transforms to "option_Color\, size" in the request.

Response JSON

A JSON object with the following fields:

Field	Type	Description
productCount	number	Total number of products matching any specified filters
filters	object filters	List of found product filters.

filters

Field	Type	Description
price	object price	Price filters.
inventory	object inventory	Inventory filters – number of in stock and out-of-stock products.
onsale	object onsale	Filter for currently discounted products.
categories	object categories	Filter for product categories.
attribute_{attrName}	object attribute_{attrName}	Filter for product attributes. Response can contain multiple attribute filters. Field name for each attribute filter includes the attribute name.
option_{optionName}	object option_{optionName}	Filter for product options. Response can contain multiple option filters. Field name for each option filter includes the attribute name.

price

Field	Type	Description
minValue	number	Minimal product price in the store for applying filters.
minValue	number	Maximum product price in the store for applying filters.
status	string	If SUCCESS, the price filter can be applied on the storefront.

inventory

Field	Type	Description
values	array of objects values	Found invontory filters.
success	string	If SUCCESS, found filters can be applied on the storefront.

Objects inside the values array list found inventory filters in the following format:

{
  "id": "instock",
  "title": "In stock",
  "productCount": 2
}

onsale

Field	Type	Description
values	array of objects values	Found sale filters.
success	string	If SUCCESS, found filters can be applied on the storefront.

Objects inside the values array list found sale filters in the following format:

{
  "id": "notonsale",
  "title": "Regular price",
  "productCount": 2
}

categories

Field	Type	Description
values	array of objects values	Found category filters.
success	string	If SUCCESS, found filters can be applied on the storefront.

Objects inside the values array list found category filters in the following format:

{
  "id": 172786255,
  "title": "Toys",
  "productCount": 1
}

attribute_{attrName}

Field	Type	Description
title	string	Title of the found attribute filter.
values	array of objects values	Found attribute filters.
success	string	If SUCCESS, found filters can be applied on the storefront.
sortingOrder	string	Default sorting order for the filter, for example, "FILTER_VALUE_ASC"

Objects inside the values array list found attribute filters in the following format:

"values": [
  {
    "title": "LIGHTSPEED",
    "productCount": 1
  },
  {
    "title": "Test_Brand",
    "productCount": 1
  }
]

option_{optionName}

Field	Type	Description
title	string	Title of the found option filter.
values	array of objects values	Found option filters.
success	string	If SUCCESS, found filters can be applied on the storefront.
sortingOrder	string	Default sorting order for the filter, for example, "FILTER_VALUE_ASC"

Objects inside the values array list found option filters in the following format:

"values": [
  {
    "title": "24",
    "productCount": 1
  },
  {
    "title": "28",
    "productCount": 1
  },
  {
    "title": "32",
    "productCount": 1
  }
]