This feature is in beta, and we are actively working to improve it. If you have questions about enablement, account configuration, or campaigns, please contact our Support.

This guide explains how to integrate product recommendations in headless or FastStore web stores using the VTEX Recommendations BFF API.

For mobile apps, see Integrating product recommendations in mobile stores.

Before implementing recommendations in a headless or FastStore web store, make sure you have:

• A headless or FastStore web frontend capable of making authenticated HTTPS requests.
• Requested and received approval for the product recommendations feature for the account.
• Recommendation campaigns created and their respective VRNs.
• Automatic cart and order event capture through Activity Flow configured for your headless or FastStore web store. For custom headless web storefronts, follow Installing Activity Flow in headless stores. FastStore includes Activity Flow natively.

After the feature is approved, the VTEX team prepares the recommendations environment for the account. This setup includes:

• Creating and configuring the recommendations workspace.

• Synchronizing the product catalog with the recommendation service.

• Configuring the access credentials used by the integration.

• Configuring automatic cart and order event capture for your headless or FastStore web store through Activity Flow.

• Cart events, such as add_to_cart and remove_from_cart, are consumed from the Data Layer and sent to the recommendations platform.

• Completed orders are automatically processed and transformed into transactions used to train and improve the models.

• When the order contains the recommendations identifier saved in the orderForm, the purchase can be associated with the user who browsed the store anonymously.

Once these configurations are complete, you can proceed with the implementation steps below.

Your headless or FastStore web store must call the POST Start session endpoint.

This endpoint starts or updates the user's recommendations session. It associates the userId used during browsing with the current orderFormId, saves this identifier in the orderForm custom data, and returns the recommendationsUserId that must be used in subsequent requests.

Sending orderFormId in the JSON body is optional for web storefronts when the request forwards the checkout.vtex.com cookie: the API can resolve the order form from that cookie when it isn't in the body. If the client can't send cookies (for example, some server-only calls), include orderFormId in the body manually. For FastStore, the recommended approach is to forward cookies on the start-session request.

Call POST Start session:

• On the first session load where an order form is available (via the request body or the checkout.vtex.com cookie).
• Every time the vtex-rec-user-start-session cookie expires.

The endpoint also sets the vtex-rec-user-id cookie with the returned recommendationsUserId, and the vtex-rec-user-start-session cookie, which controls when a new start-session call must be made. The recommendationsUserId must be sent as userId in recommendation and event endpoints.

start-session is important because it allows navigation and interaction events collected during the session to be linked later to the completed purchase. When the order is processed, the service uses the recommendationsUserId saved in the orderForm to associate the anonymous browsing behavior with the VTEX user who completed the purchase.

Request example with checkout.vtex.com cookie:

When the request includes the shopper's checkout.vtex.com cookie, you can omit the JSON body. That applies to FastStore and to headless storefronts that forward the browser's checkout cookies.

In tools like curl, pass that cookie explicitly like in the example below. In the browser it is forwarded automatically. The cookie value includes the cart identifier (for example, _ofid and the orderFormId), as described in Get cart information by ID.

In tools like curl, pass that cookie explicitly like below. In the browser it is forwarded automatically. The cookie value includes the cart identifier, for example _ofid={orderFormId}, as described in Get cart information by ID.

Request example with orderFormId:

When the request cannot send checkout cookies (for example, some server-side calls), include orderFormId in the body.

Response example:

The returned recommendationsUserId is the same value persisted in the vtex-rec-user-id cookie. The endpoint also sets the vtex-rec-user-start-session cookie.

To display recommendations in your headless or FastStore web store:

1. Start the session by calling POST Start session.
2. Use the returned recommendationsUserId, which is the same value stored in the vtex-rec-user-id cookie, while the vtex-rec-user-start-session cookie is valid.
3. Fetch recommendations for each shelf using the campaign VRN.
4. Render the returned products.

Use the GET Fetch recommendations endpoint whenever a page contains a recommendation shelf.

The campaignVrn is the VRN (Virtual Resource Name) that identifies the recommendation strategy. It follows the vrn:recommendations:{store-name}:{campaignType}:{campaignId} format.

The full VRN can be obtained through our Support or from the store Admin in Storefront > Recommendations. In the shelf list, click the three dots on the right side of the shelf and then click Copy ID.

Available campaign types:

• rec-top-items-v2: Best Sellers
• rec-persona-v2: For You
• rec-similar-v2: Similar Products
• rec-cross-v2: Who Viewed Also Bought
• rec-cross-v2: Buy Together
• rec-last-v2: Recently Viewed
• rec-visual-v2: Visually Similar Products
• rec-search-v2: Manual collection or search
• rec-next-v2: Next Interaction

Main parameters:

• an: VTEX account name.
• campaignVrn: Campaign VRN.
• userId: recommendationsUserId returned by start-session.
• products: Comma-separated product IDs. Required for contextual campaigns, such as similar products, who viewed also bought, visually similar products, next interaction, and cart recommendations.
• salesChannel: Store sales channel.
• locale: User locale, for example en-US.

Request example:

For campaigns that require product context, include products:

Response example:

When the shelf returns a sponsored product, the product will be marked with the advertisement tag. In this case, render the card with a sponsored label.

Render the returned products as product cards on the shelf.

To measure performance and improve recommendations, your headless or FastStore web store must send product-view events when the user opens a product detail page.

For accurate tracking, ensure that you always use the same session recommendationsUserId in the userId field.

Use the POST Product view endpoint when the user views a product detail page.

Request example:

The response returns 202 Accepted.

The source field accepts values such as WEB_DESKTOP and WEB_MOBILE. When source is not sent, the BFF tries to infer the value from the user-agent.

Recommendation shelf view events and recommended product click events are automatically captured through Activity Flow.

To capture view events, render the following attributes on the recommendation shelf parent container:

To capture click events, render the following attributes on each product in the recommendation shelf:

Use the correlationId returned in the recommendation response, the campaignId returned in campaign.id, and the list of rendered product IDs in productIds.

Implementation example: