Displaying product recommendations with the Recommendation Shelf

This feature is in beta. If you have questions about enablement, account configuration, or campaigns, contact our Support team.

This guide covers the native Recommendation Shelf section, which is the recommended way to display recommendations in a FastStore store. Follow Integrating product recommendations in headless or FastStore web stores only if you're building a custom headless storefront or a fully custom recommendation experience that calls the Recommendations API directly instead of using this section.

• A FastStore store connected to the CMS.
• Approval to use the product recommendations feature for your account. To request it, open a ticket with VTEX Support.
• Activity Flow available in your store, if you want to track recommendation impressions, views, and clicks. Activity Flow is optional but recommended, and FastStore includes it natively. If tracking events don't appear, confirm that Activity Flow is active and that the shelf's tracking attributes are rendered.
• At least one active recommendation campaign.

1. In the VTEX Admin, go to Storefront > Recommendations.
2. In the shelf list, select the campaign you want to display.
3. Click the three dots on the right side of the shelf and then click Copy ID.

For the list of supported campaign types, see Campaign types and product context.

1. In the VTEX Admin, go to Storefront > Content > All Content and open the page where you want to display the shelf, such as the Homepage, a Product Details Page (PDP), or a Product Listing Page (PLP).
2. Click Add Section and select Recommendation Shelf.
3. Turn on the Enable recommendations? toggle switch. This field is disabled by default, and the shelf doesn't fetch or render anything while the field is disabled.
4. Paste the campaign VRN from Step 1 in the Campaign VRN field. This field is required.
5. Configure the remaining fields as needed. See Section fields.
6. Save and publish the page.

You can add more than one Recommendation Shelf to the same page. Repeat the steps above for each shelf and give each one its own campaign VRN, for example, to display cross-sell and similar-item shelves on the same product page.

• ProductCard: A custom card component. Defaults to the core ProductCard.
• mapProductToProductCard: Maps each recommended product, a normalized StoreProduct, into card props. When you provide this function, it fully owns the card props and the default productCardConfiguration merge no longer applies.

The exact integration depends on your override setup.

• PDP (default): uses the product on the current product detail page. Outside a PDP, there's no product context.
• CART: uses the products currently in the cart, deduplicated. This is intended for cross-sell shelves on the cart page.

• It inherits the Cart Sidebar’s tax configuration.
• Doesn't render when the cart is empty, even for context-agnostic campaigns.
• Allows shoppers to add recommended products without closing the drawer.
• It's bundled in its own chunk so that stores with the feature disabled do not download its code or styles.

The mini cart shelf reuses the same Recommendations infrastructure as the Recommendation Shelf. Follow Before you begin and Step 1: Get the campaign VRN before enabling it.

1. In the VTEX Admin, go to Storefront > Content > All Content.
2. Open the Global Sections content type and select the Cart Sidebar component.
3. Under Recommendations, turn on the Should display Recommendation Shelf? toggle switch. This field is off by default, and the drawer doesn't fetch or render anything while it's off.
4. Paste the campaign VRN from Step 1 in the Campaign VRN field.
5. Configure the remaining fields as needed. See Mini cart shelf fields.
6. Save and publish.

Fields prefixed with › are nested inside the Carousel Configuration and Product Card Configuration groups.