Call the SearchCatalogItems Endpoint

Applies to: Catalog API

Learn how to search for items or item variations using one or more supported query filters.

The SearchCatalogItems endpoint can take one or more of the following query filters:

• The category_ids filter returns catalog items or item variations of specified category IDs.
• The custom_attribute_filters query expressions return items or item variations of the specified custom attributes.
• The enabled_Location_ids filter returns items or item variations with the specified enabled locations.
• The product_types filter returns items or item variations of the specified product types.
• The stock_levels filter returns items or item variations of the specified stock levels.
• The text_filter query returns items or item variations containing the specified text terms in searchable attributes.
• The custom_attribute_filters returns items or item variations matching specified custom attributes.

When you use more than one filter, the returned result contains items and item variations that satisfy all the query conditions.

Search with category IDs means to query catalog items of given categories as identified by the specified category IDs.

You can search for items or their variations by using a text filter. This involves matching specific words or phrases, known as tokens, with the searchable attributes of items, such as their name and description. A match can be found on a full or partial token match.

Text-based searching is a type of free-text search where your search input is broken down into tokens. The search process involves comparing these tokens with the tokens from the item's attributes. The order of the tokens doesn't matter; the search checks for matches between the tokens in your query and those in the item's information.

You can search for specific product types along with a text search when using the SearchCatalogItems endpoint. This gives you results that match all parts of your search.

For example, you can look for items and their variations that are a certain product type and also have "Coffee" in their searchable details.

When items or their variations have custom attribute values, you can use the SearchCatalogItems endpoint to find them based on these attributes. To do this, you provide a list of search expressions for custom attributes, written as JSON objects. For example, if you want to search for a custom attribute whose key is "cocoa_brand", you write it as {"key": "cocoa_brand"}.

  {
    "custom_attribute_filters": [
      {
        "custom_attribute_definition_token": "NPQJUZVDBE6EKZ25EU3GPLC5"
      }
    ]
  }

   "custom_attribute_filters": [
      {
        "string_filter": "Cocoa Magic"
      }
    ]

If items or their variations in your catalog have different custom attributes with the same key, you can make your search more specific by adding extra conditions. For example, you can add a string filter to the key when using SearchCatalogItems. This allows you to find items with a custom attribute key of "cocoa_brand" and a value that includes "Cocoa Magic".

   "custom_attribute_filters": [
      {
        "key": "cocoa_brand",
        "string_filter": "Cocoa Magic"
      }
    ]

When you use a selection_tokens_filter, the search results include items or variations that match any of the specified selection tokens with the selection_uid_values of their custom attribute values. You can add multiple conditions in one filter to make your search more focused or selective. Additionally, you can apply several filters to the custom_attribute_filters input, like the following:

   "custom_attribute_filters": [
      {
        "custom_attribute_definition_token": "NPQJUZVDBE6EKZ25EU3GPLC5"
      },
      {
        "key": "cocoa_brand"
      }
    ]

The search results include items that have custom attribute values matching all the conditions in your filters. Because an item can have many custom attribute values, using multiple filters helps make the search more specific and focused.