The new SCAYLE search
Functionality of the V2 search endpoints
- Search
- Business

Pia Nadolny
Junior Business Consultant
This guide focuses on the SCAYLE Search configuration in the SCAYLE Panel. To gain a better understanding of the search logic and technical implementation, refer to the Developer Guide.
The search consists of two main endpoints, the /v2/suggestions
and the /v2/resolve
endpoint.
While they have many similarities, there are also some differences between the two:
/v2/suggestions | /v2/resolve | |
---|---|---|
Use case | Giving the user suggestions as he types in the search bar | Bringing the user to the top result once he presses enter |
Results | Many results user can choose from | Only one result |
As a response to a search term, they may return categories, products, or navigation items.
Both endpoints rely on a good configuration to yield satisfying results.
On this page, you will find out how to define your SCAYLE Search in order to get optimal results.
SCAYLE offers a search module that allows you to adjust the output of frontend search results.
You can access the search configuration options in the Shops area through Shops > [Shop Name] > Storefront > Search Configuration
.
You can configure the following settings:
Any changes to the initial configuration will be visible with a time delay of up to two hours.
Search configuration in the SCAYLE Panel
As our search is category-based, you'll need to manually set the visibility of pages that you want to be searchable, such as Shipping, FAQs, Article pages or SEO pages to include them in the search results.
Shops > Shop > Storefront > Navigation
.Customers can now retrieve this page by entering relevant keywords or synonyms in the search bar. Synonyms have to be added first. Find out how to add them in the section Navigation Synonyms.
Include pages in search
SCAYLE uses attribute groups to define search result logic. Searchable Attributes only affect the Text Search of the Storefront API.
Understanding which attribute groups make for an excellent searchable attribute and which don't is essential. When an attribute group is set as searchable, the search will try to match against any of the words in the assigned attribute.
A good candidate for a searchable attribute is an attribute group with short values that users often search for. Here are some common examples:
A wrong candidate for a searchable attribute is an attribute group with long descriptions, full of words that will result in unexpected search outcomes. Here are some common examples:
The reason these are bad is that if any word in the user's search matches any word in the attribute value, the product will be returned in the search results.
As an example, if a user searches for "tongue brush", the search will also return products with the 3rd attribute value in the above example, as it includes the word "tongue". Even though the product has nothing to do with the user's search term.
Another common issue is when a searchable attribute includes unnecessary terms or search-unfriendly terms. Here are some examples:
These examples have a high chance of showing up in completely irrelevant searches.
As an example, if someone searches for "broom", products with the material "broom plant" will show up, regardless of whether they're brooms or not. Or if someone searches for "off season", then products with the color "off white" will show up.
It is strongly recommended that the searchable attribute groups have very straightforward, simple and commonly searched terms as values.
Use drag and drop to assign priorities to these groups to influence their order in the search results. Attribute groups with a higher priority affect the search results order significantly more than those with a lower priority.
Search Logic. In this example, two attribute groups are searchable in the shop. Here, the attribute group "Product Name" is assigned a higher priority than the attribute group "Product Reference Key".
The Synonyms area bundles various options for managing synonyms. Synonyms play an essential role in the output of search results, as the system can recognize which terms are considered equivalent. Use the tabs to define synonyms for single search words or combinations of words, categories, and attributes.
We support defining synonyms for your existing categories. The category synonyms work like alternative names for the specified category, as they are stored alongside the normal name of the category.
As a general guideline, we recommend adding category synonyms to applicable categories instead of word synonyms. Adding category synonyms will work seamlessly with other endpoint functionalities, such as autocomplete and typo tolerance.
As an example, if a category is called "Shirts", but users search for "T-Shirt" then this would be a good candidate to add "T-Shirt" as a synonym.
On our search endpoints, the category "Shirts" would then be returned when the user types in "Shirts" or "T-Shirt".
Shops > [Shop Name] > Storefront > Search Configuration > Synonyms
.CATEGORIES tab
.Adding synonyms
To find out how to add category synonyms in bulk, please see the documentation on imports & jobs in the User Guide.
We support defining synonyms for your existing attributes. Similar to the category synonyms, these are alternative names for your specified attribute and are stored alongside the normal name of the attribute.
As an example, if an attribute group "color" has an attribute "purple", but users search "lila" then this would be a good candidate to add "lila" as a synonym.
For attributes to be used for matching search terms to products, you must add these attributes to the Search Result Logic first.
Shops > [Shop Name] > Storefront > Search Configuration > Synonyms
.ATTRIBUTES
tab.Adding synonyms for attributes
To find out how to add attribute group synonyms in bulk, please see the documentation on imports & jobs in the User Guide.
Word Synonyms allow you to dynamically replace certain words and combinations of words from the user's search term.
Since word synonyms work on the search term itself, this means Typo Tolerance and Autocomplete are not supported.
Word synonyms are synonyms that apply across our search endpoints suggestions
and resolve
, but also work for product search through the products endpoint, which can be used as a fallback, when no matching category or navigation item is found.
The general guideline is to put existing categories, product names and attributes on the left and terms that users might search for (but don't have a matching category/product name/attribute) on the right.
Word synonyms work best for cases where a user searches for a single word, which is a combined term of an existing attribute and an existing category. This is quite common in some languages, like German.
As an example, if a user searches "leinenhose", but "leinen" is an attribute and "hose" is a category, then this is a good candidate for adding a word synonym, where "leinenhose" (the right term) would get mapped into "leinen hose" (the left term).
Word synonyms are also good candidates for improving search on product names.
As an example, the product is called "air max", but the users search for "airmax". This is then a good candidate for a word synonym, where "airmax" (right term) would get mapped into "air max" (left term).
Shops > [Shop Name] > Storefront > Search Configuration > Synonyms
.WORDS
tab.When searching, the searched terms on the right side (in the screenshot below) will be linked with the term on the left.
As an example, if there is a synonym set up for "denim => jeans" and the user searches for "denim", in the background we will search for "jeans".
Adding synonyms for words
Add a synonym of a navigation item at a local shop level.
Navigation item must be configured as Included in Search.
In the case of navigation items, there may be a lot of use cases for different wording. While a product usually has a given name, a page can be named in very different ways from website to website. Navigation item synonyms allow for you to cover those different wordings.
When you want your users to be able to search for navigation items, make sure to include some synonyms as well. Imagine you have a page called "Shipping", that informs user about expected delivery timelines, delivery cost, etc.
Once you define that navigation item as searchable, consider what synonyms users could also be searching for. An example for a good synonym in this use case would be "Delivery".
If you have an FAQ page, consider adding "Frequently Asked Questions" as a synonym.
Shops > Country > Storefront > Search > Synonyms
.Add a synonym of a navigation item at a local shop level
For our previous endpoints /v1/typeahead
and /v1/resolve
it was allowed to configure the typo tolerance we apply; however, we recommend leaving this with AUTO
.
In the new V2 endpoints, /v2/suggestions
and /v2/resolve
, the setting is not considered anymore. The typo tolerance settings are explained more in detail in the Developer Guide.
In the Words area, you define "stop words". Stop words are those words that occur particularly frequently but do not have much meaning or are used as filler words (for example, "the", "that", "everything", "at", "on" or "in"). By excluding stop words from search queries, the quality of generated search results is increased.
Assigning stop words
When you exclude a specific category from the search results, they will not be returned through any of our search endpoints. You may use this functionality if, for example, you have a category for VIP products that should not be visible to every user of your shop.
Invisible or inactive shop categories are never included in the search so this option is hidden for them.
Excluding a product from search results will only affect our search endpoints /v2/resolve
and /v2/suggestions
.
Shops > [Shop Name] > Products > Categories
.GENERAL INFO > Category Configuration
, select the Exclude from Search checkbox.Result: Once indexers have run, this shop category will not be considered for the search in the Shop Storefront anymore.
Exclude shop categories from search on the local shop level
When you exclude a specific product from the search results, it will not be returned through any of our search endpoints. You may use this functionality if, for example, you have some specific VIP products that should not be visible to every user of your shop.
Excluding a product from search results will only affect our search endpoints /v2/resolve
and /v2/suggestions
. If you want to have these products excluded from /v1/products
, too, you will have to adapt your request as described in the Developer Guide.
Shops > [Shop Name] > Products
and select the product you want to exclude from the search.Product > Product Attributes
, set the isExcludedFromSearch dropdown to true
.Result: Once indexers have run, this product will not be considered for the search in the Shop Storefront anymore.
Exclude a product from search on the local shop level
The Exact Attribute Search enables precise product searches based on specific attributes, such as product IDs. Only products with an exact match on a configured attribute (within a relevant Attribute Group) will be returned by the Storefront API. This functionality is particularly useful for scenarios like ID-based product searches.
Users with the permission shop__additional_settings__exact-attribute-search__edit
can view and edit the Attribute Groups considered for Exact Attribute Search.
Only basic advanced Attribute Groups can be selected for this feature. These Attribute Groups must meet the following criteria:
A maximum of 25 Attribute Groups can be configured as relevant for the Exact Attribute Search.
Shop > Storefront > Search Configuration
in the SCAYLE Panel.By using this feature, you can enhance the precision of search results in the shop frontend, ensuring users find the exact products they are searching for based on the configured attributes.
Our search follows a category-first approach, meaning categories are always prioritized in the results. Next, products are displayed if there is an exact match with one of their searchable IDs. Finally, searchable navigation items are returned.
As an example: the search term "501" may match both, a product with the ID "501", or a category for the well-known jeans model. In that case, we make sure the user is redirected to the category.
Yes, this is possible, but it requires proper frontend implementation. Storefront API tries to resolve the Product ID based on the Product ID, Reference Key or EAN if the perfect match is provided. You can add further advanced Attribute Groups to this logic by adding them to the Exact Attribute Search.
If the articles in your offline catalog have Catalog IDs, we recommend adding these to the Specific Attribute Search. Customers can then search for the Catalog ID on your web-store to find the product online. Find out how to add IDs to the Exact Attribute Search here.
Technically, it is possible to set up a word synonym for a Product ID. However, with the Search V2 endpoints, a perfect match is required for the product search, as no fuzziness is applied.
If your e-commerce shop already uses Navigation Items and you tag them with the “Include in search” checkmark, they will be available to the new Search V2 endpoints. However, to display them in the front-end search, you must implement additional front-end changes.
The changes won't be applied immediately. However, depending on the client and the size of the shop, it takes between 1 to 3 hours for the changes to become visible to your users.
For clients using our NPM packages, the only requirement is to use the @scayle/storefront-api
NPM package.
You can refer to the SCAYLE Configuration guidelines or visit our SCAYLE Academy platform, where you can take search courses to enhance your search skills.
Yes, the best approach is to exclude the categories you don’t want users to find, leaving only the ones you want them to be directed to. You can exclude categories through the configuration settings outlined here.
The highest priority is to resolve search terms to specific category pages. In case you identify that certain search terms are not resolved to a category page but rather redirected to a search result page, you can take the following actions:
Try to discover the users' intentions when searching for the term. In most cases, the term can be translated to a shop category. For instance, customers searching for “denim” could also refer to “jeans.”
Check whether you maintain a shop category that matches the meaning of the search term. If yes, you can create a category synonym to map further searches with the term to the corresponding category page.
If there is no matching category, you can create one. This is especially recommended when the search term is frequently used.
If the search term is only used a few times, it is also feasible to accept that users are redirected to a search result page. In such cases, we recommend configuring a proper setup of Searchable Attributes.
A search results page should only be shown in exceptional cases, as the goal is to always redirect the user to a matched category page.
Still, the results on the search results page should be of good quality. For that, a good configuration of the Searchable Attributes is key.
Check our configuration guide on how to configure your Searchable Attributes.
Furthermore, you can create word synonyms for products that users may search for with different spellings (for example, Air Max and Airmax). Find out how to create word synonyms here.
Compound words are individual words made from two or more words working together. These can be very typical in the German language, for example: "Leinenhose", "Strickjacke", "Kaschmirpullover", or "Rippenhose".
In this case, we recommend creating a word synonym that splits the two words into separate words.Leinen Hose
<= Leinenhose
This will allow our system to correctly identify the category and other attributes in the search term.
In that case, the products are ordered by ID (highest to lowest).
productId
?In that case, the product with the matching productId
would be returned, as the productId
is given more priority.
While the Search V2 endpoints do support boolean filters like “Sale” or “New,” proper functionality in the e-commerce shop requires a frontend implementation to handle this use case and redirect the user to the correct URL. In the response body of the Storefront API search endpoints, you will find data on the category and applied filters, which you can use to build frontend logic that forwards the user to the PLP page with the filters applied. Also, note that boolean filters will only be applied if there are products matching both the category and the filters.
Yes, you can configure this in the Word Synonyms section of the SCAYLE Panel. This configuration works with the new Search V2 endpoints, provided they are implemented according to our guidelines.
Yes, you can set this up in the Word Synonyms section of the SCAYLE Panel. This means that if a user searches for “discount shirts,” the search will behave as if “sale shirts” had been entered.
If your shop uses distinct brand categories for different genders, you must set the synonyms for each category individually. For example, setting a synonym for Brands/SCAYLE
will not automatically apply to Men/Brands/SCAYLE
and Women/Brands/SCAYLE
.
Yes, all filters assigned to a category are considered by the search algorithm. You can add or remove filters as needed, which will determine whether they appear on the category page and in the search results.
Translations are not supported by default. However, you can implement synonyms for specific categories, attribute groups, or even individual words to handle translations. For instance, setting up "hose" as a category synonym for "pants" will enable the redirection. You can configure various types of synonyms: Category synonyms, attribute group synonyms, word synonyms, and navigation synonyms.
When searching for a productId, no typo tolerance is applied. The product is only returned if there is an exact match.
The new SCAYLE search
Pia Nadolny
Junior Business Consultant