{ "openapi": "3.0.0", "info": { "title": "Recommendations BFF API", "version": "1.0.0", "description": "The Recommendations BFF API allows VTEX stores, integrators, and partners to fetch product recommendations, record user/product events, and manage recommendation sessions for headless, FastStore, and mobile storefronts.\n\nThis API powers personalized and contextual product recommendations, tracks user interactions, and enables advanced analytics. It supports multiple recommendation strategies including best sellers, personalized recommendations, similar products, cross-sell, and visually similar items.\n\n> ℹ️ This feature is in beta. For questions about enablement, account configuration, or campaigns, contact [VTEX Support](https://help.vtex.com/en/support).\n\n## Integration guides\n\n- [Integrating product recommendations in headless or FastStore web stores](https://developers.vtex.com/docs/guides/integrating-product-recommendations-in-headless-or-faststore-web-stores)\n- [Integrating product recommendations in mobile stores](https://developers.vtex.com/docs/guides/integrating-product-recommendations-in-mobile-stores)\n\n## Event tracking\n\n**Web storefronts (headless or FastStore)**: Recommendation shelf view and click events are automatically captured through [Activity Flow](https://developers.vtex.com/docs/guides/activity-flow) when proper data attributes are rendered on shelf elements. Cart and order events are also automatically captured. Product view events must be sent via this API.\n\n**Mobile apps**: All events (recommendation view, recommendation click, and product view) must be sent via this API. Cart and order events require [Activity Flow integration for mobile apps](https://developers.vtex.com/docs/guides/installing-activity-flow-in-mobile-apps)." }, "servers": [ { "url": "https://api.{environment}.com.br", "description": "VTEX server URL.", "variables": { "environment": { "description": "Environment to use. Used as part of the URL.", "enum": [ "vtexcommercestable", "vtexcommercebeta" ], "default": "vtexcommercestable" } } } ], "paths": { "/api/recommend-bff/v2/events/recommendation-view": { "post": { "tags": [ "Events" ], "summary": "Recommendation view", "description": "Records when a recommendation shelf enters the viewport.\n\n## When to send\n\n**Web storefronts**: Automatically captured through Activity Flow when proper data attributes are rendered on the shelf container. See the integration guides for details.\n\n**Mobile apps**: Send this event when the recommendation shelf becomes visible (e.g., when at least 50% of the shelf is visible for 1 second). Ensure events are properly debounced to prevent duplicates.\n\n## Important notes\n\n- Always use the same session `recommendationsUserId` in the `userId` field for accurate tracking.\n- Include the `correlationId` returned in the [Fetch recommendations](https://developers.vtex.com/docs/api-reference/recommendations-bff-api#get-/api/recommend-bff/v2/recommendations) response.\n- Include the `campaignId` from `campaign.id` in the [Fetch recommendations](https://developers.vtex.com/docs/api-reference/recommendations-bff-api#get-/api/recommend-bff/v2/recommendations) response.\n- The `products` array should contain all product IDs rendered in the shelf.\n\n## Permissions\n\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "parameters": [ { "name": "x-vtex-rec-origin", "in": "header", "description": "Required format: `{accountName}/{sourceType}/{appOrIntegrationId}`. Must match the `an` query parameter for account name.", "required": true, "schema": { "type": "string", "example": "apiexamples/storefront/vtex.recommendation-shelf@2.x" } }, { "name": "an", "in": "query", "description": "VTEX account name. Must match the account name in the `x-vtex-rec-origin` header.", "required": true, "schema": { "type": "string", "example": "apiexamples" } } ], "responses": { "202": { "description": "Accepted\n\nEvent queued for processing." }, "400": { "description": "Bad Request\n\nInvalid payload or missing fields." }, "401": { "description": "Unauthorized\n\nMissing or invalid credentials." }, "403": { "description": "Forbidden\n\nRequest origin not allowed." }, "404": { "description": "Not Found\n\nReferenced resources were not found." }, "422": { "description": "Unprocessable Entity\n\nValidation failed." }, "429": { "description": "Too Many Requests\n\nRate limit exceeded." }, "500": { "description": "Internal Server Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendationViewEventV2Request" }, "example": { "userId": "198e0f50-acf8-42f7-998a-5cd125464749", "correlationId": "d2e8c706-e67c-45d7-8de9-b80976960f89", "products": [ "14", "12" ], "campaignId": "ca2acae8-41a4-4bcd-9ffd-0ac40b7c0a57" } } } } } }, "/api/recommend-bff/v2/events/recommendation-click": { "post": { "tags": [ "Events" ], "summary": "Recommendation click", "description": "Records when a user clicks on a recommended product.\n\n## When to send\n\n**Web storefronts**: Automatically captured through Activity Flow when proper data attributes are rendered on each product card. See the integration guides for details.\n\n**Mobile apps**: Send this event when the user taps on a recommended product.\n\n## Important notes\n\n- Always use the same session `recommendationsUserId` in the `userId` field for accurate tracking.\n- Include the `correlationId` returned in the [Fetch recommendations](https://developers.vtex.com/docs/api-reference/recommendations-bff-api#get-/api/recommend-bff/v2/recommendations) response.\n- Include the `campaignId` from `campaign.id` in the [Fetch recommendations](https://developers.vtex.com/docs/api-reference/recommendations-bff-api#get-/api/recommend-bff/v2/recommendations) response.\n- The `product` field should contain the clicked product ID.\n\n## Permissions\n\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "parameters": [ { "name": "x-vtex-rec-origin", "in": "header", "description": "Required format: `{accountName}/{sourceType}/{appOrIntegrationId}`. Must match the `an` query parameter for account name.", "required": true, "schema": { "type": "string", "example": "apiexamples/storefront/vtex.recommendation-shelf@2.x" } }, { "name": "an", "in": "query", "description": "VTEX account name. Must match the account name in the `x-vtex-rec-origin` header.", "required": true, "schema": { "type": "string", "example": "apiexamples" } } ], "responses": { "202": { "description": "Accepted\n\nEvent queued for processing." }, "400": { "description": "Bad Request\n\nInvalid payload or missing fields." }, "401": { "description": "Unauthorized\n\nMissing or invalid credentials." }, "403": { "description": "Forbidden\n\nRequest origin not allowed." }, "404": { "description": "Not Found\n\nReferenced resources were not found." }, "422": { "description": "Unprocessable Entity\n\nValidation failed." }, "429": { "description": "Too Many Requests\n\nRate limit exceeded." }, "500": { "description": "Internal Server Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendationClickEventV2Request" }, "example": { "userId": "198e0f50-acf8-42f7-998a-5cd125464749", "correlationId": "d2e8c706-e67c-45d7-8de9-b80976960f89", "product": "14", "campaignId": "ca2acae8-41a4-4bcd-9ffd-0ac40b7c0a57" } } } } } }, "/api/recommend-bff/v2/recommendations": { "get": { "tags": [ "Recommendations" ], "summary": "Fetch recommendations", "description": "Retrieves recommended products with full product details based on the provided campaign VRN (Virtual Resource Name).\n\nThe campaign VRN identifies a specific recommendation strategy and follows the format: `vrn:recommendations:{store-name}:{campaignType}:{campaignId}`\n\nYou can obtain the full VRN from:\n- [VTEX Support](https://help.vtex.com/en/support).\n- VTEX Admin at **Storefront > Recommendations** (click the three dots next to a shelf and select **Copy ID**).\n\n## Campaign types and requirements\n\n**Non-contextual campaigns** (no `products` parameter needed):\n- `rec-top-items-v2`: Most popular (products with the highest number of views).\n- `rec-persona-v2`: Recommended for you (custom recommendations based on user profile and behavior).\n- `rec-last-v2`: Recently viewed (products recently viewed by the user).\n- `rec-search-v2`: Manual collection (recommendations from a manually created collection).\n\n**Contextual campaigns** (require `products` parameter):\n- `rec-similar-v2`: Similar products (products similar to a specific one).\n- `rec-cross-v2`: Frequently bought together (complementary products commonly purchased together).\n- `rec-visual-v2`: Visually similar products (products visually similar to a specific one).\n- `rec-next-v2`: Recent interactions (products most likely to engage the user in the future).\n- Cart recommendations (requires all product IDs currently in the cart).\n\n## Response details\n\n- Returns full product objects with brand, name, link, items (SKUs), images, and pricing information.\n- Products marked with the `advertisement` tag are sponsored and should display a sponsored label.\n- The `correlationId` must be used when tracking recommendation view and click events.\n- The `campaign.id` should be included in event tracking calls.\n\n## Permissions\n\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "parameters": [ { "name": "x-vtex-rec-origin", "in": "header", "description": "Required format: `{accountName}/{sourceType}/{appOrIntegrationId}`. Must match the `an` query parameter for account name.", "required": true, "schema": { "type": "string", "example": "apiexamples/storefront/vtex.recommendation-shelf@2.x" } }, { "name": "an", "in": "query", "description": "VTEX account name. Must match the account name in the `x-vtex-rec-origin` header.", "required": true, "schema": { "type": "string", "example": "apiexamples" } }, { "name": "campaignVrn", "in": "query", "description": "VRN identifier for an existing campaign, following the pattern: `vrn:recommendations:{store-name}:{campaignType}:{campaignId}`.\n\nAvailable campaign types:\n- `rec-top-items-v2`: Most popular (products with the highest number of views).\n- `rec-persona-v2`: Recommended for you (custom recommendations based on user profile and behavior).\n- `rec-similar-v2`: Similar products (products similar to a specific one).\n- `rec-cross-v2`: Frequently bought together (complementary products commonly purchased together).\n- `rec-cart-v2`: Cart-based recommendations.\n- `rec-last-v2`: Recently viewed (products recently viewed by the user).\n- `rec-visual-v2`: Visually similar products (products visually similar to a specific one).\n- `rec-search-v2`: Manual collection (recommendations from a manually created collection).\n- `rec-next-v2`: Recent interactions (products most likely to engage the user in the future).", "required": true, "schema": { "type": "string", "example": "vrn:recommendations:apiexamples:rec-top-items-v2:123e4567-e89b-12d3-a456-426614174000" } }, { "name": "userId", "in": "query", "description": "The `recommendationsUserId` returned by the `POST` [Start session](https://developers.vtex.com/docs/api-reference/recommendations-bff-api#post-/api/recommend-bff/v2/users/start-session) endpoint. Required for personalized recommendations based on user behavior. This value is also stored in the `vtex-rec-user-id` cookie.", "required": false, "schema": { "type": "string", "example": "198e0f50-acf8-42f7-998a-5cd125464749" } }, { "name": "products", "in": "query", "description": "Comma-separated list of product IDs for context-based recommendations. **Required** for: similar products (`rec-similar-v2`), buy together (`rec-cross-v2`), visually similar products (`rec-visual-v2`), next interaction (`rec-next-v2`), and cart recommendations. For similar items and cross-sell campaigns, send only **one product ID**. For cart recommendations, send **all product IDs** currently in the user's cart.", "required": false, "schema": { "type": "string", "example": "product-id-1,product-id-2,product-id-3" } }, { "name": "salesChannel", "in": "query", "description": "Trade policy ID. We also try to extract it from the segment cookie. If none is provided in the query, we will use the default trade policy.", "required": false, "schema": { "type": "string", "example": "1" } }, { "name": "locale", "in": "query", "description": "The user's locale information. If not provided, it is extracted from the segment cookie. This is important for multi-language stores.", "required": false, "schema": { "type": "string", "example": "en-US" } }, { "name": "zipCode", "in": "query", "description": "Zip code for location-based recommendations. If not provided, it is extracted from the segment cookie.", "required": false, "schema": { "type": "string", "example": "90210" } }, { "name": "pickupPoint", "in": "query", "description": "Pickup point identifier for location-based recommendations. If not provided, it is extracted from the segment cookie.", "required": false, "schema": { "type": "string", "example": "pickup-1234" } }, { "name": "regionId", "in": "query", "description": "Region identifier for location-based recommendations. If not provided, it is extracted from the segment cookie.", "required": false, "schema": { "type": "string", "example": "southeast-1" } } ], "responses": { "200": { "description": "OK\n\nSuccessfully fetched recommendations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendationsV2Response" }, "example": { "products": [ { "brand": "Mizuno", "productId": "14", "productName": "Standard Sunglasses", "link": "/standard-sunglasses/p", "items": [ { "itemId": "31", "nameComplete": "Standard Sunglasses", "images": [ { "imageUrl": "https://biggy.vtexassets.com/arquivos/ids/155412/images.png?v=637528820142830000" } ], "sellers": [ { "sellerId": "1", "commertialOffer": { "Price": 330, "ListPrice": 330, "AvailableQuantity": 10000 } } ] } ] }, { "brand": "Google", "productId": "12", "productName": "Trail Backpack", "link": "/trail-backpack/p", "tags": ["advertisement"], "items": [ { "itemId": "29", "nameComplete": "Trail Backpack - variant 2", "images": [ { "imageUrl": "https://biggy.vtexassets.com/arquivos/ids/155410/mochila-para-trilha-thule-alltrail-25l-masc-01.jpg?v=637528813555100000" } ], "sellers": [ { "sellerId": "1", "commertialOffer": { "Price": 121, "ListPrice": 121, "AvailableQuantity": 10000 } } ] } ] } ], "correlationId": "d2e8c706-e67c-45d7-8de9-b80976960f89", "campaign": { "id": "ca2acae8-41a4-4bcd-9ffd-0ac40b7c0a57", "title": "Complementary products", "type": "CROSS_SELL" } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/RecommendationsV2Response" }, "example": { "products": [ { "brand": "Mizuno", "productId": "14", "productName": "Standard Sunglasses", "link": "/standard-sunglasses/p", "items": [ { "itemId": "31", "nameComplete": "Standard Sunglasses", "images": [ { "imageUrl": "https://biggy.vtexassets.com/arquivos/ids/155412/images.png?v=637528820142830000" } ], "sellers": [ { "sellerId": "1", "commertialOffer": { "Price": 330, "ListPrice": 330, "AvailableQuantity": 10000 } } ] } ] }, { "brand": "Google", "productId": "12", "productName": "Trail Backpack", "link": "/trail-backpack/p", "tags": ["advertisement"], "items": [ { "itemId": "29", "nameComplete": "Trail Backpack - variant 2", "images": [ { "imageUrl": "https://biggy.vtexassets.com/arquivos/ids/155410/mochila-para-trilha-thule-alltrail-25l-masc-01.jpg?v=637528813555100000" } ], "sellers": [ { "sellerId": "1", "commertialOffer": { "Price": 121, "ListPrice": 121, "AvailableQuantity": 10000 } } ] } ] } ], "correlationId": "d2e8c706-e67c-45d7-8de9-b80976960f89", "campaign": { "id": "ca2acae8-41a4-4bcd-9ffd-0ac40b7c0a57", "title": "Complementary products", "type": "CROSS_SELL" } } } } }, "400": { "description": "Bad Request\n\nInvalid or conflicting parameters." }, "401": { "description": "Unauthorized\n\nMissing or invalid credentials." }, "403": { "description": "Forbidden\n\nRequest origin not allowed." }, "404": { "description": "Not Found\n\nCampaign not found or unavailable." }, "422": { "description": "Unprocessable Entity\n\nValidation failed due to an invalid recommendation type." }, "429": { "description": "Too Many Requests\n\nRate limit exceeded." }, "500": { "description": "Internal Server Error" } } } }, "/api/recommend-bff/v2/users/start-session": { "post": { "tags": [ "Users" ], "summary": "Start session", "description": "Starts or updates a user's recommendation session by associating the `userId` with the current `orderFormId` and returning the `recommendationsUserId` to use in subsequent requests.\n\nThis endpoint:\n- Sets the `vtex-rec-user-id` cookie with the returned `recommendationsUserId`.\n- Sets the `vtex-rec-user-start-session` cookie to control when a new session call is needed.\n- Saves the recommendations identifier in the orderForm custom data for purchase attribution.\n- Links anonymous browsing behavior to completed purchases when the order is processed.\n\n## When to call\n\n**Web storefronts (headless or FastStore)**:\n- On the first session load where an order form is available (via request body or `checkout.vtex.com` cookie).\n- Every time the `vtex-rec-user-start-session` cookie expires.\n- `orderFormId` is **optional** in the request body when the `checkout.vtex.com` cookie is forwarded (the API extracts it from the cookie).\n\n**Mobile apps**:\n- On the first session load where an `orderFormId` exists.\n- Every time the `orderFormId` changes.\n- Both `userId` and `orderFormId` are **required** in the request body.\n- Ensure the HTTP client preserves cookies or stores required values for subsequent calls.\n\n## Permissions\n\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "parameters": [ { "name": "x-vtex-rec-origin", "in": "header", "required": true, "description": "Origin identifier for tracking integration sources. Required format: `{accountName}/{sourceType}/{appOrIntegrationId}`. The account name must match the `an` query parameter. Example: `apiexamples/storefront/vtex.recommendation-shelf@2.x`", "schema": { "type": "string", "example": "apiexamples/storefront/vtex.recommendation-shelf@2.x" } }, { "name": "x-forwarded-host", "in": "header", "description": "Forwarded host header, typically containing the original host requested by the client.", "schema": { "type": "string", "example": "www.apixamples.com" } }, { "name": "host", "in": "header", "description": "Host header containing the domain name of the API server.", "schema": { "type": "string", "example": "apiexamples.vtexcommercestable.com.br" } }, { "name": "an", "in": "query", "description": "VTEX account name. Must match the account name in the `x-vtex-rec-origin` header.", "required": true, "schema": { "type": "string", "example": "apiexamples" } } ], "responses": { "200": { "description": "OK\n\nSession started successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSessionV2Response" }, "example": { "recommendationsUserId": "198e0f50-acf8-42f7-998a-5cd125464749" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/StartSessionV2Response" }, "example": { "recommendationsUserId": "198e0f50-acf8-42f7-998a-5cd125464749" } } } }, "400": { "description": "Bad Request\n\nInvalid payload or missing fields." }, "401": { "description": "Unauthorized\n\nMissing or invalid credentials." }, "403": { "description": "Forbidden\n\nRequest origin not allowed." }, "404": { "description": "Not Found\n\nReferenced resources were not found." }, "422": { "description": "Unprocessable Entity\n\nValidation failed." }, "429": { "description": "Too Many Requests\n\nRate limit exceeded." }, "500": { "description": "Internal Server Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSessionV2Request" }, "example": { "orderFormId": "d761924de4254f6883a8ec2e9a28597d" } } } } } }, "/api/recommend-bff/v2/events/product-view": { "post": { "tags": [ "Events" ], "summary": "Product view", "description": "Records when a user views a product detail page. This event is used to measure performance and improve recommendations.\n\n## When to send\n\nSend this event when the user opens a product detail page (PDP).\n\n## Important notes\n\n- Always use the same session `recommendationsUserId` in the `userId` field for accurate tracking.\n- When `source` is not provided, the API attempts to infer it from the `user-agent` header.\n- For web integrations, use `WEB_DESKTOP` or `WEB_MOBILE`.\n- For mobile app integrations, use `WEB_MOBILE` or `MOBILE_APP`.\n\n## Permissions\n\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "parameters": [ { "name": "x-vtex-rec-origin", "in": "header", "description": "Required format: `{accountName}/{sourceType}/{appOrIntegrationId}`. Must match the `an` query parameter for account name.", "required": true, "schema": { "type": "string", "example": "apiexamples/storefront/vtex.recommendation-shelf@2.x" } }, { "name": "user-agent", "in": "header", "description": "User agent string identifying the client application or browser.", "schema": { "type": "string", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" } }, { "name": "an", "in": "query", "description": "VTEX account name. Must match the account name in the `x-vtex-rec-origin` header.", "required": true, "schema": { "type": "string", "example": "apiexamples" } } ], "responses": { "202": { "description": "Accepted\n\nEvent queued for processing." }, "400": { "description": "Bad Request\n\nInvalid payload or missing fields." }, "401": { "description": "Unauthorized\n\nMissing or invalid credentials." }, "403": { "description": "Forbidden\n\nRequest origin not allowed." }, "404": { "description": "Not Found\n\nReferenced resources were not found." }, "422": { "description": "Unprocessable Entity\n\nValidation failed." }, "429": { "description": "Too Many Requests\n\nRate limit exceeded." }, "500": { "description": "Internal Server Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductViewEventV2Request" }, "example": { "userId": "550e8400-e29b-41d4-a716-446655440000", "product": "2000026", "source": "WEB_DESKTOP", "name": "Coca-Cola Can 350ml", "category": "Beverages/Soft Drinks", "url": "https://mystore.com/coca-cola-can-350ml/p" } } } } } } }, "components": { "schemas": { "StartSessionV2Request": { "type": "object", "description": "Request body for starting a user session. Requirements vary by platform:\n- **Web storefronts**: `orderFormId` is optional when the `checkout.vtex.com` cookie is sent. The API extracts the order form from the cookie.\n- **Mobile apps**: Both `userId` and `orderFormId` are required in the request body.", "properties": { "orderFormId": { "type": "string", "description": "Order form ID associated with the session. Optional for web storefronts when `checkout.vtex.com` cookie is present. Required for mobile apps.", "example": "d761924de4254f6883a8ec2e9a28597d" }, "userId": { "type": "string", "description": "User ID for the session. Required for mobile apps. Optional for web storefronts.", "example": "198e0f50-acf8-42f7-998a-5cd125464749" } } }, "StartSessionV2Response": { "type": "object", "description": "Response body for starting a user session. The returned ID is also stored in the `vtex-rec-user-id` cookie.", "properties": { "recommendationsUserId": { "type": "string", "description": "The recommendations user ID to use in subsequent API calls. This value is also stored in the `vtex-rec-user-id` cookie and saved in the orderForm custom data for purchase attribution." } }, "required": [ "recommendationsUserId" ] }, "RecommendationsV2Response": { "type": "object", "description": "Response containing recommended products with full product details and campaign information.", "properties": { "products": { "type": "array", "description": "List of recommended products with full details including brand, name, images, and pricing.", "items": { "type": "object", "description": "Product object with full details.", "properties": { "brand": { "type": "string", "description": "Product brand name." }, "productId": { "type": "string", "description": "Product ID." }, "productName": { "type": "string", "description": "Product name." }, "link": { "type": "string", "description": "Product page URL path." }, "tags": { "type": "array", "description": "Product tags. When `advertisement` tag is present, the product is sponsored and should display a sponsored label.", "items": { "type": "string", "description": "Tag name." } }, "items": { "type": "array", "description": "List of SKUs for this product.", "items": { "type": "object", "description": "SKU object with variant details.", "properties": { "itemId": { "type": "string", "description": "SKU ID." }, "nameComplete": { "type": "string", "description": "Complete SKU name including variant information." }, "images": { "type": "array", "description": "SKU images.", "items": { "type": "object", "description": "Image object.", "properties": { "imageUrl": { "type": "string", "description": "Image URL." } } } }, "sellers": { "type": "array", "description": "List of sellers offering this SKU.", "items": { "type": "object", "description": "Seller object with pricing information.", "properties": { "sellerId": { "type": "string", "description": "Seller ID." }, "commertialOffer": { "type": "object", "description": "Commercial offer details.", "properties": { "Price": { "type": "number", "description": "Selling price.", "example": 330 }, "ListPrice": { "type": "number", "description": "List price (before discount).", "example": 330 }, "AvailableQuantity": { "type": "number", "description": "Available stock quantity.", "example": 10000 } } } } } } } } } } } }, "correlationId": { "type": "string", "description": "Correlation ID for the recommendation request. Must be included when tracking recommendation view and click events." }, "campaign": { "type": "object", "description": "Campaign information.", "properties": { "id": { "type": "string", "description": "Campaign ID. Should be included when tracking recommendation view and click events." }, "title": { "type": "string", "description": "Campaign title." }, "type": { "type": "string", "description": "Campaign type. Supported types:\n\n- **TOP_ITEMS**: Most popular - products with the highest number of views.\n- **PERSONALIZED**: Recommended for you - custom recommendations based on user profile and behavior.\n- **SIMILAR_ITEMS**: Similar products - products similar to a specific one.\n- **CROSS_SELL**: Frequently bought together - complementary products commonly purchased together.\n- **CART_RECOMMENDATIONS**: Cart recommendations based on cart contents.\n- **LAST_SEEN**: Recently viewed - products recently viewed by the user.\n- **RECENT_INTERACTIONS**: Products the user recently interacted with.\n- **VISUAL_SIMILARITY**: Visually similar products - products visually similar to a specific one.\n- **SEARCH_BASED**: Manual collection - recommendations from a manually created collection.\n- **NEXT_INTERACTION**: Recent interactions - products most likely to engage the user in the future.", "enum": [ "TOP_ITEMS", "PERSONALIZED", "SIMILAR_ITEMS", "CROSS_SELL", "CART_RECOMMENDATIONS", "LAST_SEEN", "RECENT_INTERACTIONS", "VISUAL_SIMILARITY", "SEARCH_BASED", "NEXT_INTERACTION" ] } }, "required": [ "id", "type" ] } }, "required": [ "products", "correlationId", "campaign" ] }, "RecommendationViewEventV2Request": { "type": "object", "description": "Request body for recording a recommendation view event when a shelf enters the viewport.", "properties": { "userId": { "type": "string", "description": "The `recommendationsUserId` returned by the `POST` [Start session](https://developers.vtex.com/docs/api-reference/recommendations-bff-api#post-/api/recommend-bff/v2/users/start-session) endpoint. Must be the same session ID used throughout the user's session.", "example": "198e0f50-acf8-42f7-998a-5cd125464749" }, "correlationId": { "type": "string", "description": "Correlation ID returned in the [Fetch recommendations](https://developers.vtex.com/docs/api-reference/recommendations-bff-api#get-/api/recommend-bff/v2/recommendations) response. Used to track which recommendation request generated this view.", "example": "d2e8c706-e67c-45d7-8de9-b80976960f89" }, "products": { "type": "array", "description": "List of product IDs that were rendered in the recommendation shelf.", "items": { "type": "string", "description": "Product ID.", "example": "14" }, "example": [ "14", "12" ] }, "campaignId": { "type": "string", "description": "Campaign ID from the `campaign.id` field in the [Fetch recommendations](https://developers.vtex.com/docs/api-reference/recommendations-bff-api#get-/api/recommend-bff/v2/recommendations) response. Include when available.", "example": "ca2acae8-41a4-4bcd-9ffd-0ac40b7c0a57" } }, "required": [ "userId", "correlationId", "products" ] }, "RecommendationClickEventV2Request": { "type": "object", "description": "Request body for recording a recommendation click event when a user clicks on a recommended product.", "properties": { "userId": { "type": "string", "description": "The `recommendationsUserId` returned by the `POST` [Start session](https://developers.vtex.com/docs/api-reference/recommendations-bff-api#post-/api/recommend-bff/v2/users/start-session) endpoint. Must be the same session ID used throughout the user's session.", "example": "198e0f50-acf8-42f7-998a-5cd125464749" }, "product": { "type": "string", "description": "Product ID that was clicked.", "example": "14" }, "correlationId": { "type": "string", "description": "Correlation ID returned in the [Fetch recommendations](https://developers.vtex.com/docs/api-reference/recommendations-bff-api#get-/api/recommend-bff/v2/recommendations) response. Used to track which recommendation request generated this click.", "example": "d2e8c706-e67c-45d7-8de9-b80976960f89" }, "campaignId": { "type": "string", "description": "Campaign ID from the `campaign.id` field in the [Fetch recommendations](https://developers.vtex.com/docs/api-reference/recommendations-bff-api#get-/api/recommend-bff/v2/recommendations) response. Include when available.", "example": "ca2acae8-41a4-4bcd-9ffd-0ac40b7c0a57" } }, "required": [ "userId", "product", "correlationId" ] }, "ProductViewEventV2Request": { "type": "object", "description": "Request body for recording a product view event when a user views a product detail page.", "properties": { "userId": { "type": "string", "description": "The `recommendationsUserId` returned by the `POST` [Start session](https://developers.vtex.com/docs/api-reference/recommendations-bff-api#post-/api/recommend-bff/v2/users/start-session) endpoint. Must be the same session ID used throughout the user's session.", "example": "198e0f50-acf8-42f7-998a-5cd125464749" }, "product": { "type": "string", "description": "Product ID that was viewed.", "example": "14" }, "source": { "type": "string", "description": "Source of the view event. When not provided, the API attempts to infer from the `user-agent` header. Use `WEB_DESKTOP` or `WEB_MOBILE` for web storefronts, and `WEB_MOBILE` or `MOBILE_APP` for mobile apps.", "enum": [ "WEB_DESKTOP", "WEB_MOBILE", "MOBILE_APP" ], "example": "WEB_DESKTOP" }, "name": { "type": "string", "description": "Display name of the product. Optional. When provided, enriches the product view event with additional product information. We recommend sending it whenever available.", "example": "Coca-Cola Can 350ml" }, "category": { "type": "string", "description": "Category of the product. Optional. When provided, enriches the product view event with additional product information. We recommend sending it whenever available.", "example": "Beverages/Soft Drinks" }, "url": { "type": "string", "description": "URL of the product page. Optional. When provided, enriches the product view event with additional product information. We recommend sending it whenever available.", "example": "https://mystore.com/coca-cola-can-350ml/p" } }, "required": [ "userId", "product" ] } } }, "tags": [ { "name": "Events" }, { "name": "Recommendations" }, { "name": "Users" } ] }