Search with category tokens means to query catalog items of given categories as identified by the specified category IDs.
Link to section
Request
The following cURL example searches for items by matching the items' category_id attribute against the specified category_token filter expressed as a list of category IDs:
You can search for items or item variations using text_filter to match specified string tokens against searchable attribute values of items or item variations. Searchable attributes include name, description, and others.
Search by text is a form of free-text search in which the query expression is tokenized into a list of tokens. Matching is conducted by comparing tokenized searchable attribute values of items or item variations token by token, irrespective of the token orders, against the tokenized query expression.
Link to section
Request
The following example fetches items or item variation containing the Coffee and Drink tokens:
Because matching is independent of the token orders, you get the same result if you use the following text_filter:
Furthermore, a token in the query can match part of a token in an attribute of an item or item variation. Hence, the following variation of the previous text_filter returns the same results as previously shown:
Link to section
Search with text and product types filters
You can combine a text search with specific product types when calling the SearchCatalogItems endpoint. You get the result that matches all the query expressions.
The following example searches for items and item variations by a specified product type that also contains Coffee in their searchable attribute values.
If your catalog doesn't contain any items satisfying the both query expressions, you receive an empty payload in a 200 OK response.
Link to section
Search with custom attribute filters
When items or item variations have custom attribute values assigned to them, you can call the SearchCatalogItems endpoint to search for them by their custom attribute values. To do so, you supply a list of custom_attribute_filter query expressions, expressed as JSON objects. If a custom attribute value contains the key value of cocoa_brand, the custom_attribute_filter can be expressed as {"key": "cocoa_brand"}.
Link to section
Request
The following cURL example shows how to call the SearchCatalogItems endpoint to search for items with a custom attribute filter:
On the other hand, if you know the custom attribute definition ID ("NPQJUZVDBE6EKZ25EU3GPLC5") of the custom attribute value, you can express the custom_attribute_query filters as follows:
If the custom attribute value has the string_value property assigned the "Cocoa Magic" value, you can call the SearchCatalogItems endpoint with the following custom_attribute_filters:
Link to section
Response
If such items are present in the catalog and the request succeeds, you get the result in a response similar to the following:
If the items or item variations in your catalog have different custom attribute values of the same key, you can narrow the scope of the search result by adding other query conditions. For example, you can append a string_filter expression to the key expression in a custom_attribute_filter when calling the SearchCatalogItems, as shown the following example. This lets you search for items or items variations with custom attribute values having the key of cocoa_brand and the string_value containing Cocoa Magic.
However, when you use a selection_tokens_filter, the returned search results are items or item variations matching any of the specified selection tokens against the selection_uid_values of their custom_attribute_values.
You can specify multiple query conditions in a single query filter to narrow the scope of the search target or to make the search more selective.
You can also assign multiple query filters to the custom_attribute_filters input property, as shown:
The result contains items each of which has a custom_attribute_value property matching all the query conditions in all the query filters. Because an item or item variation can have multiple custom attribute values, using multiple custom attribute filters helps make the search more selective to narrow the scope of the search result.