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 mobile stores using the VTEX Recommendations BFF API.

For web storefronts, see Integrating product recommendations in headless or FastStore web stores.

Before implementing recommendations in a mobile store, make sure you have:

• A mobile app 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 configured for the mobile store. To set this up, see Installing Activity Flow in mobile apps and VTEX Activity Flow.

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.
• 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.

The mobile 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.

In mobile integrations, userId and orderFormId are required in the start-session request body.

Call POST Start session:

• On the first session load where an orderFormId exists.
• Every time the orderFormId changes.

The endpoint also sets the vtex-rec-user-id cookie with the returned recommendationsUserId. The recommendationsUserId must be sent as userId in recommendation and event endpoints.

In mobile integrations, make sure the HTTP client preserves the cookies returned by the endpoint or stores the required values so they can be reused in subsequent calls.

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:

Response example:

The returned recommendationsUserId is the same value persisted in the vtex-rec-user-id cookie.

To display recommendations in the mobile 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 screen 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 in mobile, the store must send three event types through the API:

• recommendation-view: when the recommendation shelf enters the viewport.
• recommendation-click: when the user clicks a recommended product.
• product-view: when the user opens a product detail page.

For accurate tracking, ensure that:

• All events include the same session recommendationsUserId in the userId field.
• You send recommendation-view only when the shelf becomes visible, for example, when at least 50% of the shelf is visible for 1 second.
• Events are properly debounced to prevent duplicates.
• View and click events include the correlationId returned by the recommendation request.
• You send campaignId when available; it is returned in campaign.id.

Use the POST Recommendation view endpoint when a shelf enters the viewport.

Request example:

The response returns 202 Accepted.

Use the POST Recommendation click endpoint when the user clicks a recommended product.

Request example:

The response returns 202 Accepted.

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. For mobile integrations, send WEB_MOBILE.