# Filtering Products Filtering is a crucial feature in eCommerce platforms, enabling users to narrow down their search results and find products that meet specific criteria. Effective filtering can significantly enhance user experience, leading to higher conversion rates and customer satisfaction. ### Key Components of Filtering 1. **Category Filters**: * **Product Categories**: Users can filter products based on categories such as electronics, fashion, home appliances, etc. * **Sub-Categories**: Further refinement within a category, like smartphones under electronics, or dresses under fashion. 2. **Attribute Filters**: * **Price Range**: Allows users to set a minimum and maximum price to find products within their budget. * **Brand**: Users can filter products from specific brands they trust or prefer. * **Ratings and Reviews**: Filtering by customer ratings and reviews helps users find highly-rated products. 3. **Availability Filters**: * **Stock Status**: Users can choose to see only products that are in stock. * **Delivery Options**: Filters for same-day delivery, free shipping, or other delivery preferences. 4. **Custom Filters:** * **Color and Size**: Especially important in fashion and apparel categories, allowing users to filter by color, size, and other physical attributes. * **Features and Specifications**: For electronics and appliances, users can filter by specific features like battery life, screen size, or capacity. ### Faceted Search Faceted search is a powerful search and filtering method that enables users to refine their search results across multiple dimensions or attributes simultaneously. This approach provides a more granular and precise filtering experience compared to traditional single-attribute filters. * **Multiple Dimensions**: Users can filter products based on various attributes such as category, brand, price range, color, size, and more. For example, a user looking for a laptop can apply filters for brand (e.g., Apple, Dell), price range ($500-$1000), screen size (15 inches), and processor type (Intel i5). * **Hierarchical Filtering**: Faceted search supports hierarchical filters, where users can drill down through categories and sub-categories. For example, within the "Electronics" category, users can further refine their search by selecting "Laptops," and then "Gaming Laptops." #### Dynamic Updating of Filters One of the key features of faceted search is the dynamic updating of available filters based on the user's current selections. This ensures a seamless and intuitive filtering experience, preventing the user from encountering zero results. * **Real-Time Updates**: As users apply or remove filters, the remaining available filter options update in real time to reflect the current set of applicable products. For example, if a user selects the "Nike" brand under the "Shoes" category, the available size, color, and price range filters will automatically update to show only options that are relevant to Nike shoes. * **Preventing Zero Results**: By dynamically updating filters, faceted search helps prevent scenarios where users might end up with no search results due to incompatible filter combinations. If a certain combination of filters would result in zero results, those filter options might be disabled or hidden. For example, if selecting both "Red" and "Large" would lead to no available products, one or both of those options may be grayed out or removed. #### User Experience Enhancements * **Intuitive UI**: Faceted search interfaces are designed to be user-friendly and intuitive. Filters are often presented as checkboxes, sliders, or dropdown menus, making it easy for users to apply and modify filters. * **Bread Crumbs and Clear Filters**: Users can easily see which filters they have applied through breadcrumb trails or a summary section. They can also quickly clear individual filters or all filters at once to reset their search. ### Key Terms of Product List Filter Settings #### 1. Attribute Key The `attribute_key` (known as attribute code in Omnitron) refers to one of the predefined static attributes, such as price, stock, and other similar properties. To add a filter based on a specific attribute key for the product, include the key value using `attribute_key`. #### 2. Attribute Type The attribute type indicates how the attribute to be filtered should be categorized, and it can take values of `EAV` or `global`. * **EAV (entity-attribute-value)**: If the entered attribute\_key matches a value in the product attributes, the attribute\_type should be set to EAV. For example, use EAV for keys like `integration_color` that are listed in the *Omnitron > Products and Catalogs > Product Attributes* list. * **Global**: If the entered attribute\_key matches any static attribute of the product, such as `price` or `stock`, the attribute\_type should be set to global. #### 3. Widget Type Widgets determine how users interact with filters on the frontend. Various types include * multi\_select * category * attribute\_value * visual\_swatch * nested Below are detailed instructions on setting up each widget type. **3.1. Multi Select** To allow users to select multiple values from a list, such as price ranges. In the **Multi Select** filter, `widget_kwargs` and `facet_kwargs` enable users to select multiple predefined ranges, such as price intervals. This configuration allows for flexible filtering where users can pick from multiple options rather than being limited to a single range or continuous input. These parameters are configured within the Facet Configuration. **Example**: Adding a price filter. * **attribute\_key**: "price" * **attribute\_type**: "global" * **widget**: "multi\_select" * **facet**: "range" **widget\_kwargs**: ```json { "labels": { "0-250": "0 TL - 250 TL", "251-500": "250 TL - 500 TL", "501-750": "500 TL - 750 TL", "750": "Above 750 TL" }, "name": "PRICE", "order": 0 } ``` **facet\_kwargs:** ```json { "ranges": [ ["0-250", [0, 25000]], ["251-500", [25100, 50000]], ["501-750", [50100, 75000]], ["750", [75000, null]] ] } ``` **3.2. Category** To allow users to filter products by category. In the **Category** filter, `widget_kwargs` and `facet_kwargs` are used to configure how users can filter products by categories in the Facet Configuration. This setup provides users with a structured list of categories, sorted according to specified criteria and limited by a defined result size. **Example**: Adding a category filter. * **attribute\_key**: "category\_ids" * **attribute\_type**: "global" * **widget**: "category" * **facet**: "terms" **widget\_kwargs**: ```json { "name": "Kategori", "sorting_mode": "attr_value_order", "order": 1 } ``` The sorting mode parameter determines the display order of the filtered categories. It can take the values `attr_value_order` or `label`: * `attr_value_order` sorts categories based on the value that matches the entered `attribute_key`. * `label` sorts categories based on the name of the filter. **facet\_kwargs:** ```json { "size": 500 } ``` The size parameter specifies the maximum number of data entries that will be returned from this filter. **3.3. Attribute Value** To allow users to filter products by redirecting to a specific URL. In the **Attribute Value** filter, `widget_kwargs` and `facet_kwargs` are configured within the Facet Configuration to allow users to filter products based on a specific attribute, such as "gender", for more targeted filtering options. **Example**: Adding a gender filter. * **attribute\_key**: "gender" * **attribute\_type**: "EAV" * **widget**: "attribute\_value" * **facet**: "terms" **widget\_kwargs**: ```json { "sorting_mode":"attr_value_order", "order":1 } ``` The sorting mode parameter determines the display order of the filtered categories. It can take the values `attr_value_order` or `label`: * `attr_value_order` sorts categories based on the value that matches the entered `attribute_key`. * `label` sorts categories based on the name of the filter. **facet\_kwargs:** ```json { "size": 500 } ``` The size parameter specifies the maximum number of data entries that will be returned from this filter. **3.4. Visual Swatch** To display visual selections like colors. In the **Visual Swatch** filter, `widget_kwargs` and `facet_kwargs` are configured within the Facet Configuration to let users filter products by visually selecting attributes like colors. **Example**: Adding a color filter. * **attribute\_key**: "color" * **attribute\_type**: "EAV" * **widget**: "visual\_swatch" * **facet**: "terms" **widget\_kwargs**: ```json { "color_objects": { "Blue": { "hex": "#1976D2", "klass": null, "label": "Blue" }, "Pink": { "hex": "#FF4081", "klass": null, "label": "Pink" }, "Purple": { "hex": "#7B1FA2", "klass": null, "label": "Purple" }, "Fuchsia": { "hex": "#FF00FF", "klass": null, "label": "Fuchsia" } }, "name": "Color", "order": 5 } ``` **facet\_kwargs:** ```json { "size": 500 } ``` The size parameter specifies the maximum number of data entries that will be returned from this filter. **3.5. Nested** To filter products by multiple attributes simultaneously. In the **Nested** filter, `facet_kwargs` and `settings` are configured within the Facet Configuration to enable multi-attribute filtering. This allows users to filter products based on combinations of attributes, like color and size, to find items that meet specific requirements across multiple characteristics. **Example**: Adding a filter for products with both specific color and size. * **attribute\_key**: "attribute\_key\_value" * **attribute\_type**: "EAV" * **widget**: "nested" * **facet**: "terms" **facet\_kwargs**: ```json { "size": 500 } ``` The size parameter specifies the maximum number of data entries that will be returned from this filter. **settings**: ```json { "nested_facets": [ [ "products.attributes_color", "products.attributes_size", "products.attributes_combined_color_size" ] ], "nested_facet_map": [ [ "color", "size", "combined_color_size" ] ] } ``` **Example Scenario**: To filter products that are both blue and XL: * **First value**: "products.attributes\_color" * **Second value**: "products.attributes\_size" * **Possible values**: * **Color**: "Blue", "Green", "Red" * **Size**: "XL" * **Combined values**: "blueXL", "greenXL", "redXL" **3.6. Range** The range filter allows for dynamic filtering of products by attribute values within specified numerical ranges. This functionality is particularly useful for attributes like price, storage, or any other numeric fields that may vary across products. With this filter, brands can create a filtering option that lets users adjust a range, allowing for more precise control over the search. After creating **FacetConfiguration** with the range filter, users are able to filter products with a parameter like `?price=X-Y` to specify a range. For instance, `?price=0-2000` will filter products whose price is between 0 and 2000. This option extends to other product attributes, such as storage, where users can specify a range (e.g., between 16 GB and 256 GB for mobile phones) to discover products with storage capacities that meet their requirements. Depending on the front-end capabilities, the **range** widget can be implemented in various ways, such as a slider (for continuous selection) or text fields (for manually entering range values). These are just examples, and other methods may be used based on specific needs or requirements. In the **Range** filter, `widget_kwargs` is a configuration setting used to define specific display and behavioral properties for the widget associated with the range filter in a Facet Configuration. It allows for a detailed customization of how the widget will appear and interact with the user, specifically for attributes such as the widget's name, order, and step increments. `facet_kwargs`, like `widget_kwargs`, is part of the Facet Configuration and defines additional settings that control how the range filter behaves on a backend level. **Example 1: Filtering by Storage Capacity** To filter products based on storage capacity, the following configuration can be used: * **attribute\_key**: "storage" * **attribute\_type**: "global" * **widget**: "range" * **facet**: "range" **widget\_kwargs**: ```json { "name": "Storage Range", "order": 0, "step": 16 } ``` * **name**: Specifies the name of the widget, which is `"Storage Range"` in this case. * **order**: Defines the display order of the widget (0 here). * **step**: Sets the increment step for the slider, with steps of 16. **facet\_kwargs**: ```json { "continuous": true, "ranges": [["0", [0, null]]], } ``` * **continuous:** Must be set to `true` to enable continuous adjustments of the range slider. If not set to `true`, the range filter will not function correctly. * **ranges:** Defines the range selection. In this example, `[["0", [0, null]]]` allows users to select storage capacity within an automatically defined range based on available storage options in the list. With this range filter, users can filter products by storage capacity, for example, selecting between 16 GB and 256 GB for mobile phones by adding `?storage=16-256` to the query string. **Example 2: Filtering by Price** To filter products based on price within a specified range, such as $0 to $2000, the following configuration can be used: * **attribute\_key**: "price" * **attribute\_type**: "global" * **widget**: "range" * **facet**: "range" **facet\_kwargs:** ```json { "continuous": true, "ranges": [["0", [0, null]]], } ``` * **continuous:** Must be set to `true` to enable continuous adjustments of the range slider. If not set to `true`, the range filter will not function correctly. * **ranges:** Defines the range selection. In this example, `[["0", [0, null]]]` allows users to filter products by price within the available range, based on the price list. **widget\_kwargs**: ```json { "name": "Price Range", "order": 0, "step": 10 } ``` * **name**: Specifies the name of the widget, which is `"Price Range"` in this case. * **order**: Defines the display order of the widget (0 here). * **step**: Sets the increment step for the slider, with steps of 10. With this range filter, users can filter products by price, for example, selecting between $0 and $2000 for products by adding `?price=0-2000` to the query string. ### Facet Configuration Facet configurations are features that allow users to customize various filtering settings for listed products. They enable the customization of filter values such as a product's price, category, or specific attributes like color or size. These settings are maintained on the Commerce product and can be added through the Omnitron panel by making a request to Commerce. #### How Facets Work Facets operate by indexing values in Elasticsearch along with the products. Filtering is then performed based on these indexed values. To display a filter on the product listing page, the product must first be indexed in Elasticsearch with the relevant filterable values. Attributes such as stock status, price, and categories are automatically indexed. Other facets are derived from the `attributes` field in the product. For example, if a product has an attribute like {"integration\_olcu": "31.5x20.5x20.5 cm"}, it will be indexed in Elasticsearch as `attributes_integration_olcu`. To make these values visible on the listing page and customize filters, FacetConfigurations are used. It's crucial to enter the correct `attribute_key` in the FacetConfiguration. For the example above, the `attribute_key` would be `integration_olcu`. #### Attribute Types The `attribute_type` field determines the type of facet. There are two types: `global` and `eav`. The `eav` option is suitable for facets derived from the product's `attributes` field, such as `integration_olcu`, `integration_cap`, `integration_materyal`. These are indexed in the format `attributes_integration_olcu`. For such fields, the appropriate attribute type is `eav`. For facets unrelated to attribute values, such as `price`, the attribute type should be `global`. #### Ordering and Sorting Facets To set the order of facets, include the `order` parameter in the `widget_kwarg`s: ```json {"name": "Renk", "order": 2} ``` This configuration will display the facet in the second position. You can also specify how the content is sorted using the `sorting_mode` parameter in `widget_kwargs`: ```json {"name": "Renk", "sorting_mode": "attr_value_order"} ``` #### Limiting the Size of Facet Results You can limit the number of facets displayed using the `size` parameter in `facet_kwargs`: ```json {"size": 3} ``` This configuration will only display three filters for the color facet. If this is not specified, the default size is 500. Problems may arise if there are more than 500 indexed values, so it's advisable to set a high value like: ```json {"size": 999999} ``` For these fields, the `terms` facet type is commonly used. Another type, `range`, is used for values like prices. #### Example FacetConfiguration for Price Ranges To configure a facet for price ranges, use the `range` facet type: **Example Request** ```json { "name": "Fiyat", "attribute_key": "price", "attribute_type": "global", "widget": "multi_select", "widget_kwargs": { "labels": { "0-50": "0 - 50 TL", "50-100": "50 - 100 TL", "100-150": "100 - 150 TL", "150-200": "150 - 200 TL", "200-500": "200 - 500 TL", "500-1000": "500 - 1000 TL", "1000": "1000 ve üzeri" }, "name": "Fiyat aralıkları" }, "facet": "range", "facet_kwargs": { "ranges": [ ["0-50", [0, 5000]], ["50-100", [5000, 10000]], ["100-150", [10000, 15000]], ["150-200", [15000, 20000]], ["200-500", [20000, 50000]], ["500-1000", [50000, 100000]], ["1000", [100000, null]] ] }, "settings": {} } ``` **Example Response** ```json { "pk": 1, "name": "Fiyat", "attribute_key": "price", "attribute_type": "global", "widget": "multi_select", "widget_kwargs": { "labels": { "0-50": "0 - 50 TL", "50-100": "50 - 100 TL", "100-150": "100 - 150 TL", "150-200": "150 - 200 TL", "200-500": "200 - 500 TL", "500-1000": "500 - 1000 TL", "1000": "1000 ve üzeri" }, "name": "Fiyat aralıkları" }, "facet": "range", "facet_kwargs": { "ranges": [ ["0-50", [0, 5000]], ["50-100", [5000, 10000]], ["100-150", [10000, 15000]], ["150-200", [15000, 20000]], ["200-500", [20000, 50000]], ["500-1000", [50000, 100000]], ["1000", [100000, null]] ] }, "settings": {} } ``` With this price FacetConfiguration, you can now filter and list products based on their price ranges, displaying the price attribute as "Fiyat aralıkları". #### Customizing Facet Display with Widgets You can select the widget type to determine how the facets are displayed. The `multi_select` widget is often used for attributes that allow multiple selections. When defining a category facet, the `category` widget type is used, which lists categories and subcategories based on indexed `category_ids`: ```json "attribute_key": "category_ids", "facet": "terms", "widget": "category", "facet_kwargs": {"size": 9999} ``` #### Visual Swatches for Color Facets To display color options visually instead of as text, you can use the `visual_swatch` widget type. This requires setting the `facet` to `terms`, `attribute_type` to `eav`, and providing the appropriate `attribute_key` (usually set as `color`). The colors and their hex codes are specified in `widget_kwargs`: ```json { "color_objects": { "SARI": {"hex": "#F8E81C", "klass": null, "label": "SARI"}, "KAHVERENGİ": {"hex": "#8B572A", "klass": null, "label": "KAHVERENGİ"}, "GRİ": {"hex": "#B4B0B0", "klass": null, "label": "GRİ"}, "MULTİ RENK": {"hex": null, "klass": "bg-multi", "label": "MULTİ RENK"}, "MOR": {"hex": "#B390D2", "klass": null, "label": "MOR"}, "ŞEFFAF": {"hex": null, "klass": "bg-transparent", "label": "ŞEFFAF"}, "YEŞİL": {"hex": "#759D45", "klass": null, "label": "YEŞİL"} }, "name": "Renk", "order": 1 } ``` After setting up this FacetConfiguration, you will see color swatches instead of text in the filter display. #### Nested Widgets for Slider Items The `nested` widget type is used to display slider items under a widget. If you do not want a specific attribute to appear in the filter, you can set its widget value to `null` in the FacetConfiguration. #### Key Conversion The attribute key used for indexing in Elasticsearch is formatted as "custom\_" + "indexconfiguration.attribute\_key". For example, if your `attribute_key` is "index\_conf\_test", the corresponding key in Elasticsearch will be "custom\_index\_conf\_test". To ensure proper matching, the `attribute_key` in your FacetConfiguration should also be "custom\_index\_conf\_test". #### Example Facet Request Body Here is an example of a request body for creating a FacetConfiguration object: ```json { "name": "Facet name", "attribute_key": "custom_index_conf_test", "attribute_type": "global", "widget": "multi_select", "widget_kwargs": { "labels": { "1000": "1000 +", "100-1000": "100-1000", "0-50": "0-50", "50-100": "50-100" }, "name": "Cap-Range", "order": 1 }, "facet": "range", "facet_kwargs": { "ranges": [ ["0-50", [0, 49]], ["50-100", [50, 99]], ["100-1000", [100, 999]], ["1000", [1000, 100000]] ] }, "settings": {} } ``` ### Facet API Methods #### `GET` Facet Configurations This method is used to get facet configuration objects. **Path:** `/api/v1/facet/` **Query Parameters** The following query parameters can be used to get the facet configuration objects.
ParameterData TypeInDescription
AuthorizationstringheaderThe API token of the customer account
**Example Request** To retrieve facet configuration objects, send a GET request to the `/api/v1/facet/` endpoint. In the headers, set the Authorization header to include the API token for authentication. Here's an example of how to make the request using Python: ```python import requests url = "https://{commerce_url}/api/v1/facet/" headers = { 'Authorization': 'Token xxxxxx' } response = requests.request("GET", url, headers=headers) print(response.text) ``` **Example Response (200 OK)** In a successful response with a status code of 200 OK, the API returns the requested facet configuration information. The response includes the appropriate content-type specified in the response headers, typically application/json. The parameters are described in the following table.
ParameterData TypeDescription
pkintegerThe primary key of the facet configuration.
namestringThe name of the facet configuration.
attribute_keystringThe name of the field to be filtered on the product.
attribute_typestringThe type information for the attribute to be filtered (values: "EAV", "global").
widgetstringThe type of the widget to be displayed on the frontend (e.g., multi_select, category, attribute_value, visual_swatch, nested).
widget_kwargsdictAdditional properties that can be entered for the widget, if any.
facetstringThe type of the created facet configuration (values: "terms", "range").
facet_kwargsdictAdditional properties that can be entered for the facet, if any.
settingsdictThe status of the reservation.
This example response serves as a reference to understand the structure and data format returned when retrieving facet configuration information successfully. ```json { "count": 1, "next": null, "previous": null, "results": [ { "pk": 1, "name": "Price", "attribute_key": "price", "attribute_type": "global", "widget": "multi_select", "widget_kwargs": { "labels": { "0-250": "0 TL - 250 TL", "251-500": "250 TL - 500 TL", "501-750": "500 TL - 750 TL", "750": "Above 750 TL" }, "name": "PRICE", "order": -1 }, "facet": "range", "facet_kwargs": { "ranges": [ ["0-250", [0, 25000]], ["251-500", [25100, 50000]], ["501-750", [50100, 75000]], ["750", [75000, null]] ] }, "settings": {} } ] } ``` #### `GET` Detailed Facet Configuration This method is used to get the details of the facet configuration object with the specified pk. **Path:** `/api/v1/facet/{pk}` **Query Parameters** The following query parameters can be used to get the details of the facet configuration objects.
ParameterData TypeInDescription
AuthorizationstringheaderThe API token of the customer account.
{pk}intqueryThe ID number of the facet configuration.
**Example Request** To retrieve information about a facet configuration instance, a `GET` request should be sent to the `/api/v1/facet/{pk}` endpoint. Include the facet configuration ID as a path parameter to specify the facet configuration. In the headers, set the Authorization header to include the API token for authentication. Here's an example of how to make the request using Python: ```python import requests url = "https://{commerce_url}/api/v1/facet/{pk}" headers = { 'Authorization': 'Token xxxxxx' } response = requests.request("GET", url, headers=headers) print(response.text) ``` **Example Response (200 OK)** In a successful response with a status code of 200 OK, the API returns the requested facet configuration instance information. The response includes the appropriate content-type specified in the response headers, typically application/json. The parameters are described in the following table.
ParameterData TypeDescription
pkintegerThe primary key of the facet configuration.
namestringThe name of the facet configuration.
attribute_keystringThe name of the field to be filtered on the product.
attribute_typestringThe type information for the attribute to be filtered (values: "EAV", "global").
widgetstringThe type of the widget to be displayed on the frontend (e.g., multi_select, category, attribute_value, visual_swatch, nested).
widget_kwargsdictAdditional properties that can be entered for the widget, if any.
facetstringThe type of the created facet configuration (values: "terms", "range").
facet_kwargsdictAdditional properties that can be entered for the facet, if any.
settingsdictThe status of the reservation.
This example response serves as a reference to understand the structure and data format returned when retrieving facet configuration instance information successfully. ```json { "pk": 1, "name": "Price", "attribute_key": "price", "attribute_type": "global", "widget": "multi_select", "widget_kwargs": { "labels": { "0-250": "0 TL - 250 TL", "251-500": "250 TL - 500 TL", "501-750": "500 TL - 750 TL", "750": "Above 750 TL" }, "name": "PRICE", "order": -1 }, "facet": "range", "facet_kwargs": { "ranges": [ ["0-250", [0, 25000]], ["251-500", [25100, 50000]], ["501-750", [50100, 75000]], ["750", [75000, null]] ] }, "settings": {} } ``` #### `POST` Create Facet Configuration This method is used to create a facet configuration object with the request body. **Path:** `/api/v1/facet/` **Request Body** The following request body parameters can be used to create a facet configuration object.
ParameterData TypeInRequiredDescription
Authorizationstringheader✓The API token of the customer account.
namestringbody✓The name of the facet configuration.
attribute_keystringbody✓The name of the field to be filtered on the product.
attribute_typestringbody✓The type information for the attribute to be filtered (values: "EAV", "global").
widgetstringbody✓The type of the widget to be displayed on the frontend (e.g., multi_select, category, attribute_value, visual_swatch, nested).
widget_kwargsdictbodyAdditional properties that can be entered for the widget, if any.
facetstringbody✓The type of the created facet configuration (values: "terms", "range").
facet_kwargsdictbodyAdditional properties that can be entered for the facet, if any.
settingsdictbodyThe status of the reservation.
**Example Request** To create a facet configuration, a POST request should be sent to the `/api/v1/facet/` endpoint. In the headers, set the Authorization header to include the API token for authentication. Here's an example of how to make the request using Python: ```python import requests import json url = "https://{commerce_url}/api/v1/facet/" payload = json.dumps({ "name": "Price", "attribute_key": "price", "attribute_type": "global", "widget": "multi_select", "widget_kwargs": { "labels": { "750": "Above 750 TL", "0-250": "0 TL - 250 TL", "501-750": "500 TL - 750 TL", "251-500": "250 TL - 500 TL" }, "name": "PRICE", "order": -1 }, "facet": "range", "facet_kwargs": { "ranges": [ ["0-250", [0, 25000]], ["251-500", [25100, 50000]], ["501-750", [50100, 75000]], ["750", [75000, None]] ] }, "settings": {} }) headers = { 'Authorization': 'Token xxxxxx', 'Content-Type': 'application/json' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` **Example Response (201 Created)** In a successful response with a status code of 201 Created, the API indicates that a new facet configuration has been successfully created.
ParameterData TypeDescription
pkintegerThe primary key of the facet configuration.
namestringThe name of the facet configuration.
attribute_keystringThe name of the field to be filtered on the product.
attribute_typestringThe type information for the attribute to be filtered (values: "EAV", "global").
widgetstringThe type of the widget to be displayed on the frontend (e.g., multi_select, category, attribute_value, visual_swatch, nested).
widget_kwargsdictAdditional properties that can be entered for the widget, if any.
facetstringThe type of the created facet configuration (values: "terms", "range").
facet_kwargsdictAdditional properties that can be entered for the facet, if any.
settingsdictThe status of the reservation.
This example response serves as a reference to understand the structure and data format returned when a new facet configuration is created successfully. ```json { "pk": 1, "name": "Price", "attribute_key": "price", "attribute_type": "global", "widget": "multi_select", "widget_kwargs": { "labels": { "0-250": "0 TL - 250 TL", "750": "Above 750 TL", "501-750": "500 TL - 750 TL", "251-500": "250 TL - 500 TL" }, "name": "PRICE", "order": -1 }, "facet": "range", "facet_kwargs": { "ranges": [ ["0-250", [0, 25000]], ["251-500", [25100, 50000]], ["501-750", [50100, 75000]], ["750", [75000, null]] ] }, "settings": {} } ``` **Example Response (400 Bad Request)** In an unsuccessful response with a status code of 400 Bad Request, the API indicates that the request could not be processed due to client error. The response body contains a JSON object that provides additional information about the error, including an error message or validation errors. This example response serves as a reference to understand the structure and data format returned when a request fails due to client error. ```json { "attribute_key": [ "facet configuration with this attribute key already exists." ] } ``` #### `PUT` Update Facet Configuration This method is used to update an existing facet configuration object identified by its ID. **Path:** `/api/v1/facet/{pk}/` **Path Parameters**
ParameterData TypeInDescription
{pk}intqueryThe ID number of the facet configuration
**Request Body** The following request body parameters can be used to update a facet configuration object.
ParameterData TypeInRequiredDescription
Authorizationstringheader✓The API token of the customer account.
namestringbody✓The name of the facet configuration.
attribute_keystringbody✓The name of the field to be filtered on the product.
attribute_typestringbody✓The type information for the attribute to be filtered (values: "EAV", "global").
widgetstringbody✓The type of the widget to be displayed on the frontend (e.g., multi_select, category, attribute_value, visual_swatch, nested).
widget_kwargsdictbodyAdditional properties that can be entered for the widget, if any.
facetstringbody✓The type of the created facet configuration (values: "terms", "range").
facet_kwargsdictbodyAdditional properties that can be entered for the facet, if any.
settingsdictbodyThe status of the reservation.
**Example Request** To update a facet configuration, send a PUT request to the `/api/v1/facet/{id}/` endpoint. Include the Authorization header with the API token for authentication. Here's an example of how to make the request using Python: ```python import requests import json url = "https://{commerce_url}/api/v1/facet/{pk}/" payload = json.dumps({ "name": "Updated Price Filter", "widget_kwargs": { "labels": { "750": "Above 750 TL", "0-250": "0 TL - 250 TL", "501-750": "500 TL - 750 TL", "251-500": "250 TL - 500 TL" }, "name": "UPDATED_PRICE", "order": -1 }, "facet_kwargs": { "ranges": [ ["0-250", [0, 25000]], ["251-500", [25100, 50000]], ["501-750", [50100, 75000]], ["750", [75000, None]] ] } }) headers = { 'Authorization': 'Token xxxxxx', 'Content-Type': 'application/json' } response = requests.request("PUT", url, headers=headers, data=payload) print(response.text) ``` **Example Response (200 OK)** In a successful response with a status code of 200 OK, the API indicates that the facet configuration has been successfully updated.
ParameterData TypeDescription
pkintegerThe primary key of the facet configuration
namestringThe name of the facet configuration
attribute_keystringThe name of the field to be filtered on the product
attribute_typestringThe type information for the attribute to be filtered (values: "EAV", "global").
widgetstringThe type of the widget to be displayed on the frontend (e.g., multi_select, category, attribute_value, visual_swatch, nested).
widget_kwargsdictAdditional properties that can be entered for the widget, if any.
facetstringThe type of the created facet configuration (values: "terms", "range").
facet_kwargsdictAdditional properties that can be entered for the facet, if any.
settingsdictThe status of the reservation.
This example response serves as a reference to understand the structure and data format returned when a new facet configuration is updated successfully. ```json { "pk": 1, "name": "Updated Price Filter", "attribute_key": "price", "attribute_type": "global", "widget": "multi_select", "widget_kwargs": { "labels": { "0-250": "0 TL - 250 TL", "750": "Above 750 TL", "501-750": "500 TL - 750 TL", "251-500": "250 TL - 500 TL" }, "name": "UPDATED_PRICE", "order": -1 }, "facet": "range", "facet_kwargs": { "ranges": [ ["0-250", [0, 25000]], ["251-500", [25100, 50000]], ["501-750", [50100, 75000]], ["750", [75000, null]] ] }, "settings": {} } ``` **Example Response (400 Bad Request)** In an unsuccessful response with a status code of 400 Bad Request, the API indicates that the request could not be processed due to client error. The response body contains a JSON object that provides additional information about the error, including an error message or validation errors. This example response serves as a reference to understand the structure and data format returned when a request fails due to client error. ```json { "attribute_key": [ "facet configuration with this attribute key already exists." ] } ``` #### `PATCH` Partial Update Facet Configuration This method is used to partially update an existing facet configuration object identified by its ID. **Path:** `/api/v1/facet/{id}/` **Path Parameters**
ParameterData TypeInDescription
{pk}intqueryThe ID number of the facet configuration.
**Request Body** The following request body parameters can be used to partially update a facet configuration object.
ParameterData TypeInRequiredDescription
Authorizationstringheader✓The API token of the customer account.
namestringbodyThe name of the facet configuration.
attribute_keystringbodyThe name of the field to be filtered on the product.
attribute_typestringbodyThe type information for the attribute to be filtered (values: "EAV", "global").
widgetstringbodyThe type of the widget to be displayed on the frontend (e.g., multi_select, category, attribute_value, visual_swatch, nested).
widget_kwargsdictbodyAdditional properties that can be entered for the widget, if any.
facetstringbodyThe type of the created facet configuration (values: "terms", "range").
facet_kwargsdictbodyAdditional properties that can be entered for the facet, if any.
settingsdictbodyThe status of the reservation.
**Example Request** To partially update a facet configuration, send a PATCH request to the `/api/v1/facet/{id}/` endpoint. Include the Authorization header with the API token for authentication. Here's an example of how to make the request using Python: ```python import requests import json url = "https://{commerce_url}/api/v1/facet/{id}/" payload = json.dumps({ "name": "Updated Price Filter", "widget_kwargs": { "labels": { "750": "Above 750 TL", "0-250": "0 TL - 250 TL", "501-750": "500 TL - 750 TL", "251-500": "250 TL - 500 TL" } } }) headers = { 'Authorization': 'Token xxxxxx', 'Content-Type': 'application/json' } response = requests.request("PATCH", url, headers=headers, data=payload) print(response.text) ``` **Example Response (200 OK)** In a successful response with a status code of 200 OK, the API indicates that the facet configuration has been successfully updated.
ParameterData TypeDescription
pkintegerThe primary key of the facet configuration
namestringThe name of the facet configuration
attribute_keystringThe name of the field to be filtered on the product
attribute_typestringThe type information for the attribute to be filtered (values: "EAV", "global").
widgetstringThe type of the widget to be displayed on the frontend (e.g., multi_select, category, attribute_value, visual_swatch, nested).
widget_kwargsdictAdditional properties that can be entered for the widget, if any.
facetstringThe type of the created facet configuration (values: "terms", "range").
facet_kwargsdictAdditional properties that can be entered for the facet, if any.
settingsdictThe status of the reservation.
This example response serves as a reference to understand the structure and data format returned when a new facet configuration is updated successfully. ```json { "pk": 1, "name": "Updated Price Filter", "attribute_key": "price", "attribute_type": "global", "widget": "multi_select", "widget_kwargs": { "labels": { "0-250": "0 TL - 250 TL", "750": "Above 750 TL", "501-750": "500 TL - 750 TL", "251-500": "250 TL - 500 TL" }, "name": "UPDATED_PRICE", "order": -1 }, "facet": "range", "facet_kwargs": { "ranges": [ ["0-250", [0, 25000]], ["251-500", [25100, 50000]], ["501-750", [50100, 75000]], ["750", [75000, null]] ] }, "settings": {} } ``` **Example Response (400 Bad Request)** In an unsuccessful response with a status code of 400 Bad Request, the API indicates that the request could not be processed due to client error. The response body contains a JSON object that provides additional information about the error, including an error message or validation errors. This example response serves as a reference to understand the structure and data format returned when a request fails due to client error. ```json { "attribute_key": [ "facet configuration with this attribute key already exists." ] } ``` ### Adding Filters with Attribute Config After linking an attribute to an attribute set, you can make various adjustments to that attribute. One of the key adjustments is setting the `is_filterable` value to `true`, making the attribute filterable. This allows the attribute to be used as a filter on the frontend, even if a facet has not been created for it. **Example Filter Configuration** Here is an example of an attribute configuration that includes filter settings: ```json { "key": "color", "data_type": "dropdown", "default_value": null, "is_required": true, "is_visible": true, "is_searchable": true, "is_filterable": true, ... } ``` ### Index Configuration The IndexConfiguration feature allows users to index numeric attribute values on Elasticsearch (ES). For instance, by default, attribute values are indexed as strings in Elasticsearch. However, if a brand requests the ability to apply a range filter for an attribute, such as size, the attribute must be indexed as a numeric value instead of a string. Example: ```json "size": "35 cm" ``` With *index\_conf*, the value would be indexed as: ```json "size": 35 ``` This numeric representation allows for range-based filtering, such as `30 < x < 35`. By indexing attributes as numbers, the system facilitates more advanced filtering and query capabilities in Elasticsearch. **Prerequisites** Before creating an IndexConfiguration, ensure that your attribute values meet the following criteria: The attribute values should be numeric or convertible to numeric values. Acceptable formats include integers, floating-point numbers, and numeric strings. Here are examples of valid and invalid attribute values: * **Valid Values**: * Integers: 1, 100, 5000 * Floats: 10.5, 99.99 * Numeric Strings: "1", "50", "100" * **Invalid Values**: * Non-numeric Strings: "30 cm", "large", "10x20x50" * Mixed Alphanumeric: "50kg", "room101" Non-numeric values, as shown in the invalid values section, will not be indexed. Ensure that your data is cleaned and formatted correctly before attempting to index it. #### `GET` Index Configurations This method is used to get index configuration objects. **Path:** `/api/v1/index-configurations/` **Query Parameters** The following query parameters can be used to get the index configuration objects.
ParameterData TypeInDescription
AuthorizationstringheaderThe API token of the customer account.
**Example Request** To retrieve index configuration objects, a GET request should be sent to the `/api/v1/index-configurations/` endpoint. In the headers, set the Authorization header to include the API token for authentication. Here's an example of how to make the request using Python: ```python import requests url = "https://{commerce_url}/api/v1/index-configurations/" headers = { 'Authorization': 'Token xxxxxx' } response = requests.request("GET", url, headers=headers) print(response.text) ``` **Example Response (200 OK)** In a successful response with a status code of 200 OK, the API returns the requested index configuration information. The response includes the appropriate content-type specified in the response headers, typically application/json. The parameters are described in the following table.
ParameterData TypeDescription
pkintegerThe primary key of the index configuration.
namestringThe name of the index configuration.
attribute_keystringThe name of the field to be filtered on the product.
attribute_typestring"integer", "float", "long"
This example response serves as a reference to understand the structure and data format returned when retrieving provider instance information successfully. ```json { "count": 1, "next": null, "previous": null, "results": [ { "pk": 1, "name": "index_conf_test conf", "attribute_key": "index_conf_test", "attribute_type": "integer" } ] } ``` #### `GET` Detailed Index Configuration This method is used to get the details of the index configuration object with the specified pk. **Path:** `/api/v1/index-configurations/{pk}` **Query Parameters** The following query parameters can be used to get the details of the index configuration objects.
ParameterData TypeInDescription
AuthorizationstringheaderThe API token of the customer account.
{pk}intqueryThe ID number of the index configuration.
**Example Request** To retrieve information about an index configuration instance, a GET request should be sent to the `/api/v1/index-configurations/{pk}` endpoint. Include the index configuration ID as a path parameter to specify the index configuration. In the headers, set the Authorization header to include the API token for authentication. Here's an example of how to make the request using Python: ```python import requests url = "https://{commerce_url}/api/v1/index-configurations/{pk}" headers = { 'Authorization': 'Token xxxxxx' } response = requests.request("GET", url, headers=headers) print(response.text) ``` **Example Response (200 OK)** In a successful response with a status code of 200 OK, the API returns the requested index configuration instance information. The response includes the appropriate content-type specified in the response headers, typically application/json. The parameters are described in the following table.
ParameterData TypeDescription
pkintegerThe primary key of the index configuration.
namestringThe name of the index configuration.
attribute_keystringThe name of the field to be filtered on the product.
attribute_typestring"integer", "float", "long"
This example response serves as a reference to understand the structure and data format returned when retrieving index configuration instance information successfully. ```json { "pk": 1, "name": "index_conf_test conf", "attribute_key": "index_conf_test", "attribute_type": "integer" } ``` #### `POST` Create Index Configuration This method is used to create an index configuration object with the request body. **Path:** `/api/v1/index-configurations/` **Request Body** The following request body parameters can be used to create an index configuration object.
ParameterData TypeInRequiredDescription
Authorizationstringheader✓The API token of the customer account.
namestringbody✓The name of the index configuration.
attribute_keystringbody✓The name of the field to be filtered on the product.
attribute_typestringbody✓"integer", "float", "long"
**Example Request** To create an index configuration, a POST request should be sent to the `/api/v1/index-configurations/` endpoint. In the headers, set the Authorization header to include the api token for authentication. Here's an example of how to make the request using Python: ```python import requests import json url = "https://{commerce_url}/api/v1/index-configurations/" payload = json.dumps({ "name": "index_conf_test conf", "attribute_key": "index_conf_test", "attribute_type": "integer" }) headers = { 'Authorization': 'Token xxxxxx', 'Content-Type': 'application/json' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` **Example Response (201 Created)** In a successful response with a status code of 201 Created, the API indicates that a new index configuration has been successfully created.
ParameterData TypeDescription
pkintegerThe primary key of the index configuration.
namestringThe name of the index configuration.
attribute_keystringThe name of the field to be filtered on the product.
attribute_typestring"integer", "float" or "long"
This example response serves as a reference to understand the structure and data format returned when a new index configuration is created successfully. ```json { "pk": 1, "name": "index_conf_test conf", "attribute_key": "index_conf_test", "attribute_type": "integer" } ``` **Example Response (400 Bad Request)** In an unsuccessful response with a status code of 400 Bad Request, the API indicates that the request could not be processed due to client error. The response body contains a JSON object that provides additional information about the error, including an error message or validation errors. This example response serves as a reference to understand the structure and data format returned when a request fails due to client error. ```json { "attribute_key": [ "index configuration with this attribute key already exists." ] } ``` #### `PUT` Update Index Configuration This method is used to update an existing index configuration object identified by its ID. **Path:** `/api/v1/index-configurations/{pk}/` **Path Parameters**
ParameterData TypeInDescription
{pk}intqueryThe ID number of the index configuration.
**Request Body** The following request body parameters can be used to update an index configuration object.
ParameterData TypeInRequiredDescription
Authorizationstringheader✓The API token of the customer account.
namestringbody✓The name of the index configuration.
attribute_keystringbody✓The name of the field to be filtered on the product.
attribute_typestringbody✓"integer", "float", "long"
**Example Request** To update an index configuration, send a PUT request to the `/api/v1/index-configurations/{id}/` endpoint. Include the Authorization header with the API token for authentication. Here's an example of how to make the request using Python: ```python import requests import json url = "https://{commerce_url}/api/v1/index-configurations/{pk}/" payload = json.dumps({ "name": "updated_index_conf_test conf", "attribute_key": "updated_index_conf_test", "attribute_type": "long" }) headers = { 'Authorization': 'Token xxxxxx', 'Content-Type': 'application/json' } response = requests.request("PUT", url, headers=headers, data=payload) print(response.text) ``` **Example Response (200 OK)** In a successful response with a status code of 200 OK, the API indicates that the index configuration has been successfully updated.
ParameterData TypeDescription
pkintegerThe primary key of the index configuration.
namestringThe name of the index configuration.
attribute_keystringThe name of the field to be filtered on the product.
attribute_typestring"integer", "float", "long"
This example response serves as a reference to understand the structure and data format returned when a new index configuration is updated successfully. ```json { "pk": 1, "name": "updated_index_conf_test conf", "attribute_key": "updated_index_conf_test", "attribute_type": "long" } ``` **Example Response (400 Bad Request)** In an unsuccessful response with a status code of 400 Bad Request, the API indicates that the request could not be processed due to client error. The response body contains a JSON object that provides additional information about the error, including an error message or validation errors. This example response serves as a reference to understand the structure and data format returned when a request fails due to client error. ```json { "attribute_key": [ "index configuration with this attribute key already exists." ] } ``` #### `PATCH` Partial Update Index Configuration This method is used to partially update an existing index configuration object identified by its ID. **Path:** `/api/v1/index-configurations/{id}/` **Path Parameters**
ParameterData TypeInDescription
{pk}intqueryThe ID number of the index configuration.
**Request Body** The following request body parameters can be used to partially update an index configuration object.
ParameterData TypeInRequiredDescription
Authorizationstringheader✓The API token of the customer account.
namestringbody✓The name of the index configuration.
attribute_keystringbody✓The name of the field to be filtered on the product.
attribute_typestringbody✓"integer", "float", "long"
**Example Request** To partially update an index configuration, send a PATCH request to the `/api/v1/index-configurations/{id}/` endpoint. Include the Authorization header with the API token for authentication. Here's an example of how to make the request using Python: ```python import requests import json url = "https://{commerce_url}/api/v1/index-configurations/{id}/" payload = json.dumps({ "name": "updated index_conf_test conf" }) headers = { 'Authorization': 'Token xxxxxx', 'Content-Type': 'application/json' } response = requests.request("PATCH", url, headers=headers, data=payload) print(response.text) ``` **Example Response (200 OK)** In a successful response with a status code of 200 OK, the API indicates that the index configuration has been successfully updated.
ParameterData TypeDescription
pkintegerThe primary key of the index configuration.
namestringThe name of the index configuration.
attribute_keystringThe name of the field to be filtered on the product.
attribute_typestring"integer", "float", "long"
This example response serves as a reference to understand the structure and data format returned when an index configuration is updated successfully. ```json { "name": "updated index_conf_test conf", "attribute_key": "index_conf_test", "attribute_type": "integer" } ``` **Example Response (400 Bad Request)** In an unsuccessful response with a status code of 400 Bad Request, the API indicates that the request could not be processed due to client error. The response body contains a JSON object that provides additional information about the error, including an error message or validation errors. This example response serves as a reference to understand the structure and data format returned when a request fails due to client error. ```json { "attribute_key": [ "index configuration with this attribute key already exists." ] } ``` #### `DELETE` Delete Index Configuration This method is used to delete an existing index configuration object identified by its ID. **Path:** `/api/v1/index-configurations/{id}/` **Path Parameters**
ParameterData TypeInDescription
{pk}intqueryThe ID number of the index configuration.
**Example Request** To delete an index configuration, send a DELETE request to the `/api/v1/index-configurations/{id}/` endpoint. Include the Authorization header with the API token for authentication. Here's an example of how to make the request using Python: ```python import requests import json url = "https://{commerce_url}/api/v1/index-configurations/{id}/" headers = { 'Authorization': 'Token xxxxxx', 'Content-Type': 'application/json' } response = requests.request("DELETE", url, headers=headers) print(response.text) ``` **Example Response (204 No Content)** In a successful response with a status code of 204 No Content, the API indicates that the index configuration has been successfully deleted, but there is no content to return. **Example Response (400 Bad Request)** In an unsuccessful response with a status code of 400 Bad Request, the API indicates that the request could not be processed due to client error. The response body contains a JSON object that provides additional information about the error, including an error message or validation errors. This example response serves as a reference to understand the structure and data format returned when a request fails due to client error. ```json { "detail": "Not found." } ``` ### Dynamic Filter The Dynamic Filter feature is useful for retrieving information specifically about the most recently viewed items by a user, allowing for filters within this subset of items. For example, if a user has viewed 10 products, you can store these product details and perform filters on this specific set of 10 products. To enable the feature that allows fetching details of the last N viewed products in a single request, follow the steps below. #### Enabling the Feature Ensure that the `SEARCH_DYNAMIC_FILTER_ACTIVE` environment variable in the ACC Commerce project is set to True. This enables the functionality described in this section. #### Example Use Case Suppose you want to filter products with SKUs `2672881040611` and `2672881031947`. **1. Create the JSON Object** First, create a JSON object as follows: ```json { "products.sku.raw": ["2672881040611", "2672881031947"] } ``` **2. Encode the JSON** Next, encode this JSON object using base64: ```json eyJwcm9kdWN0cy5za3UiOiBbIjI2NzI4ODEwNDA2MTEiLCIyNjcyODgxMDMxOTQ3Il19IA== ``` **3. Add Header to Request** When sending a request to the `/list/` endpoint, include the following header to filter only the products with the specified SKUs: ```json X-SEARCH-DYNAMIC-FILTER: eyJwcm9kdWN0cy5za3UiOiBbIjI2NzI4ODEwNDA2MTEiLCIyNjcyODgxMDMxOTQ3Il19IA== ``` **4. Example Request** Here is an example curl request: ```json curl --location 'http://{commerce_url}/list/?format=json' \ --header 'X-SEARCH-DYNAMIC-FILTER: eyJwcm9kdWN0cy5za3UiOiBbIjI2NzI4ODEwNDA2MTEiLCIyNjcyODgxMDMxOTQ3Il19IA==' ``` ### Dynamic Exclude The Dynamic Exclude feature is used to exclude specific products from the filter results. For example, if all products belonging to category ID `152` need to be excluded, this feature can be implemented. To enable the feature follow the steps below. #### Enabling the Feature Ensure that the `SEARCH_DYNAMIC_FILTER_ACTIVE` environment variable in the ACC Commerce project is set to True. This enables the functionality described in this section. #### Example Use Case Suppose you want to exclude products in category ID `152`. **1. Create the JSON Object** First, create a JSON object as follows: ```json { "products.category_ids": [152] } ``` **2. Encode the JSON** Next, encode this JSON object using base64: ```json eyJwcm9kdWN0cy5jYXRlZ29yeV9pZHMiOiBbMTUyXX0g ``` **3. Add Header to Request** When sending a request to the `/list/` endpoint, include the following header to exclude products belonging to the specified category: ```json X-SEARCH-DYNAMIC-EXCLUDE: eyJwcm9kdWN0cy5jYXRlZ29yeV9pZHMiOiBbMTUyXX0g ``` **4. Example Request** Here is an example curl request: ``` curl --location 'http://localhost:8000/list/?format=json' \ --header 'X-SEARCH-DYNAMIC-EXCLUDE: eyJwcm9kdWN0cy5jYXRlZ29yeV9pZHMiOiBbMTUyXX0g' ```