Be it through category menus, keyword searches, or product pages, shoppers accessing your headless store will need to browse through your products' information.

Below you can learn more about API endpoints you can use to help shoppers find what they need in your store. See the catalog documentation to learn how to manage products, SKUs and categories, among other things.

You can filter the results of the endpoints below by trade policy with the query parameter sc={tradePolicy}.

One of the ways shoppers will interact with your product information is by browsing through a categories menu.

Use the following endpoint to fetch category information:

• Get category tree

Instead of browsing categories, shoppers may prefer to type a keyword into your store’s search bar to find what they want. VTEX provides two different search solutions for your store. We recommend that you use Intelligent Search, but you have the option to use the Legacy CMS Portal search if you wish.

Learn more about VTEX Intelligent Search.

Before implementing Intelligent Search in your headless storefront, make sure to check this Intelligent Search guide and make the necessary configurations.

To retrieve products with the Intelligent Search API, use this endpoint:

• Get list of products for a query

For any given Intelligent Search query, you can get search facets and display them so that your shoppers can narrow their search.

• Get list of the possible facets for a given query

Shoppers may have trouble coming up with the optimal search term for their needs. Use these endpoints to help fill in the gaps:

• Get attempt of correction of a misspelled term
• Get list of suggested terms similar to the search term

Banners

You can use the Intelligent Search banners feature with this endpoint:

• Get list of banners registered for query

Intelligent Search autocomplete

You can also improve shopping experience by implementing an autocomplete feature. Use this endpoint to get suggested search terms based on a provided term:

• Get list of suggested terms and attributes similar to the search term

You can also get the most searched terms on your site:

• Get list of the 10 most searched terms

To retrieve products with the Legacy Search, use this endpoint:

• Search for Products with Filter, Order and Pagination

Note that this endpoint provides multiple filtering and ordering options that can be made available for the shopper to narrow their search, improving the user’s experience. Handy examples include:

• Searching within specific category levels (department, category and subcategory): https://{accountName}.vtexcommerce{environment}.com.br/api/catalog_system/pub/products/search/{department}/{category}/{subcategory}
• Filtering products by collection: query string fq=productClusterIds:{collectionId}
• Sorting by best discount: query string O=OrderByBestDiscountDESC

See the Search endpoint documentation to learn about all filtering and sorting options.

Legacy Search autocomplete

You can also implement an autocomplete feature to your store’s search bar using Legacu Search. To do this, use this endpoint:

• Product Search Autocomplete

On product pages and in other sections of your headless store, you will need to retrieve information about specific products.

We recommend using the Intelligent Search API for Product Detail Pages (PDP), as it provides:

• Better search performance: Optimized for faster response times.
• Consistent user experience: When using Delivery Promise, using Intelligent Search ensures delivery estimates and availability match between Product Listing Pages (PLP) and Product Detail Pages (PDP).
• Location-based availability: Supports filtering by ZIP code for accurate product availability.

Use the Get list of products for a query endpoint with the query (or q) parameter to retrieve a specific product by ID. The Intelligent Search API supports the following ID types:

Search by Product ID:

Search by SKU ID:

Search by product slug:

Other supported ID types:

• query=product.id:{id} - Product ID (alternative syntax)
• query=sku.id:{id} - SKU ID (alternative syntax)
• query=sku.ean:{ean} - SKU EAN
• query=sku.reference:{refId} - SKU Reference ID

Examples:

For stores using Delivery Promise: You must include the zip-code parameter in all Intelligent Search API requests to ensure accurate delivery estimates and product availability. See the Delivery Promise for headless stores guide for implementation details.

Example with ZIP code (required for Delivery Promise):

The query parameter accepts specific filters like product:{id}, sku:{id}, product.link:{slug}, and other ID types to retrieve individual products. For more details, see the Intelligent Search API reference.

Alternatively, you can use the Legacy Search API endpoints to retrieve product information:

• Search Product by Product URL
• Search for Products with Filter, Order and Pagination
  • Filter by product ID: fq=productId:{productId}
  • Filter by SKU ID: fq=skuId:{skuId}

Legacy Search endpoints do not support Delivery Promise features. If your store uses Delivery Promise, you must use the Intelligent Search API as described above.

When a shopper is interested in a product, it may be a good idea to display related products that they may be interested in purchasing as well.

See this guide to learn how to set up cross selling capabilities and use the endpoints below to retrieve this information on your storefront:

• Get Product Search of Show Together
• Get Product Search of Accessories
• Get Product Search of Similars
• Get Product Search of Suggestions

See these other guides to learn more about building a headless shopping experience using VTEX:

• Headless commerce overview
• Headless cart and checkout
• Headless profile management and order history