The VTEX Intelligent Search Events API captures behavioral signals from shoppers to improve search relevance. It collects events such as search queries, product clicks, and purchase completions to feed the machine learning models powering VTEX Intelligent Search.
openapi: 3.0.0
info:
title: VTEX Intelligent Search Events API - Headless
description: "Intelligent Search Events API is responsible for collecting the search events to improve your search results, such as page interactions and conversion, in a headless implementation. Some of the features improved by this collection are the possibility to sort the products by clicks or record the top search in the autocomplete.\r\n\r\n>⚠️ **This API applies only to Headless scenarios**. It doesn't apply to stores using Store Framework, since they are already integrated with all Intelligent Search features.\r\n\r\n## Building the request body\r\n\r\nIn the following sections, we detail the required structure for the request body of the `POST`[Save events](https://developers.vtex.com/docs/api-reference/intelligent-search-events-api-headless#post-/event) endpoint.\r\n\r\n### User identification\r\n\r\nTo identify the user, there are two required identifiers according to the [nanoid](https://github.com/ai/nanoid) pattern: `session` and `anonymous`. Read the API reference for more information on each field.\r\n\r\n> ⚠️ The `session` and `anonymous` identifiers need to be sent in every request.\r\n\r\n### Event type\r\n\r\nTo identify the events that occur in our search, the `type` field is required in the request. The most common event types are the following:\r\n\r\n| Event type | Value | Description |\r\n| - | - | - |\r\n| Session Ping | `session.ping` | Sends an ACK to the API to renew the session server-side. It should be sent every 1 minute. |\r\n| Page Cart | `page.cart` | Sends an event every time the shopper enters the cart page. Each interaction should include all products inside the shopping cart at that time. In case a product is removed, sent the updated card. |\r\n| Empty Cart | `page.empty_cart` | Sends an event if there are no products in the shopping cart at that time. | \r\n| Page Confirmation |`page.confirmation` | Sends a confirmation informing the products that were bought. |\r\n| Search Click | `search.click` | Sends an event every time a shopper clicks on a product from a search page. |\r\n| Search Query | `search.query` | Sends a query event every time the shopper makes a full-text search. |\r\n\r\n### Finding search query information\r\n\r\nSearch query information is possible to find in the Intelligent Search GraphQL response. To retrieve the information above, add operator, fuzzy, and correction attributes in the GraphQL query. Example:\r\n\r\n```graphql\r\nquery {\r\n productSearch(fullText: \"id:43534\") {\r\n products {\r\n productId\r\n productName\r\n ...\r\n }\r\n operator\r\n fuzzy\r\n correction{ \r\n misspelled\r\n }\r\n }\r\n}\r\n```\r\n\r\n### Optional fields\r\n\r\nInformation to identify where the context of that request came from: `agent` and `URL`. Read the API reference for more information on each field.\r\n\r\n### Request body examples\r\n\r\nThe body is built by combining the user information, the event type, and add the optional fields. Below there is an example for each type of event.\r\n\r\n#### Session Ping\r\n\r\n```json\r\n{\r\n\t\"session\":\"zZlNhqz1vFJP6iPG5Oqdf\",\r\n\t\"anonymous\":\"Om1TNluGvgmSgU5OOTvdfg\",\r\n\t\"url\":\"https://example.com/search/?query=zapatilha\",\r\n\t\"agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\r\n\t\"type\":\"session.ping\"\r\n}\r\n``` \r\n\r\n#### Page Cart \r\n\r\n```json\r\n{\r\n \"session\":\"zZlNhqz1vFJP6iPG5Oqtt\",\r\n \"anonymous\":\"Om1TNluGvgmSgU5OOTvkkd\",\r\n \"products\": [\r\n {\r\n \"productId\": \"ABC123\",\r\n \"quantity\": 2\r\n },\r\n {\r\n \"productId\": \"XYZ789\",\r\n \"quantity\": 1\r\n }\r\n ],\r\n \"type\": \"page.cart\"\r\n}\r\n```\r\n\r\n#### Empty Cart \r\n\r\n```json\r\n{\r\n \"session\":\"zZlNhqz1vFJP6iPG5Oqtt\",\r\n \"anonymous\":\"Om1TNluGvgmSgU5OOTvkkd\",\r\n \"products\": [],\r\n \"type\": \"page.empty_cart\"\r\n}\r\n```\r\n\r\n#### Page Confirmation\r\n\r\n```json\r\n{\r\n \"session\":\"zZlNhqz1vFJP6iPG5Oqtt\",\r\n \"anonymous\":\"Om1TNluGvgmSgU5OOTvkkd\",\r\n \"products\"\
: [\r\n {\r\n \"productId\": \"ABC123\",\r\n \"price\": 9.99,\r\n \"quantity\": 3\r\n },\r\n {\r\n \"productId\": \"XYZ789\",\r\n \"price\": 5.99,\r\n \"quantity\": 2\r\n }\r\n ],\r\n \"order\": \"123ABC\",\r\n \"type\": \"page.confirmation\"\r\n}\r\n```\r\n\r\n#### Search Click\r\n\r\n```json\r\n{\r\n\t\"type\": \"search.click\",\r\n\t\"productId\": \"12345\",\r\n\t\"position\": 1,\r\n\t\"url\": \"https://example.com/s?q=pneu&sort=score_desc&page=0\",\r\n\t\"text\": \"pneu\",\r\n\t\"agent\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36\",\r\n\t\"anonymous\": \"1ce47e50-3f10-4556-95d3-57d4881c03a4\",\r\n\t\"session\": \"51a53ce3-096d-4740-a6d0-3cf86085ba13\"\r\n}\r\n```\r\n\r\n#### Search Query\r\n\r\n```json\r\n{\r\n\t\"session\":\"zZlNhqz1vFJP6iPG5Oqtt\",\r\n\t\"anonymous\":\"Om1TNluGvgmSgU5OOTvkkd\",\r\n\t\"url\":\"https://example.com/search/?query=zapatilha\",\r\n\t\"agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\r\n\t\"type\":\"search.query\",\r\n\t\"text\":\"zapatilha\",\r\n\t\"misspelled\":true,\r\n\t\"match\":392,\r\n\t\"operator\":\"and\"\r\n}\r\n```\r\n"
contact: {}
version: '1.0'
servers:
- url: https://sp.vtex.com/event-api/v1/{accountName}
description: Server URL.
variables:
accountName:
default: apiexamples
description: Name of the VTEX account. Used as part of the URL.
paths:
/event:
post:
summary: VTex Save events
description: "Creates search events to integrate with VTEX Intelligent Search using a headless implementation. \r\n\r\n >⚠️ **This API applies only to Headless scenarios**. It doesn't apply to stores using VTEX's storefront solution, natively integrated with Intelligent Search."
parameters:
- name: accountName
in: path
description: Name of the VTEX account. Used as part of the URL.
required: true
schema:
type: string
example: apiexamples
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/SessionPing'
- $ref: '#/components/schemas/PageCart'
- $ref: '#/components/schemas/PageEmptyCart'
- $ref: '#/components/schemas/PageConfirmation'
- $ref: '#/components/schemas/Click'
- $ref: '#/components/schemas/Query'
examples:
Session Ping:
value:
session: zZlNhqz1vFJP6iPG5Oqtt
anonymous: Om1TNluGvgmSgU5OOTvkkd
url: https://example.com/search/?query=zapatilha
agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0
type: search.query
text: zapatilha
misspelled: true
match: 392
operator: and
Page Cart:
value:
session: zZlNhqz1vFJP6iPG5Oqtt
anonymous: Om1TNluGvgmSgU5OOTvkkd
products:
- productId: ABC123
quantity: 2
- productId: XYZ789
quantity: 1
type: page.cart
Empty Cart:
value:
session: zZlNhqz1vFJP6iPG5Oqtt
anonymous: Om1TNluGvgmSgU5OOTvkkd
products: []
type: page.empty_cart
Page Confirmation:
value:
session: zZlNhqz1vFJP6iPG5Oqtt
anonymous: Om1TNluGvgmSgU5OOTvkkd
products:
- productId: ABC123
price: 9.99
quantity: 3
- productId: XYZ789
price: 5.99
quantity: 2
order: 123ABC
type: page.confirmation
Search Click:
value:
type: search.click
productId: '12345'
position: 1
url: https://example.com/s?q=pneu&sort=score_desc&page=0
text: pneu
agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36
anonymous: 1ce47e50-3f10-4556-95d3-57d4881c03a4
session: 51a53ce3-096d-4740-a6d0-3cf86085ba13
Search Query:
value:
session: zZlNhqz1vFJP6iPG5Oqtt
anonymous: Om1TNluGvgmSgU5OOTvkkd
url: https://example.com/search/?query=zapatilha
agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0
type: search.query
text: zapatilha
misspelled: true
match: 392
operator: and
tags:
- Events
responses:
'204':
description: No content
components:
schemas:
UserIdentification:
required:
- anonymous
- session
properties:
anonymous:
type: string
title: anonymous
description: Identifier related to related to the user, according to the [nanoid](https://github.com/ai/nanoid) pattern. This information is kept in storage for one year.
example: Om1TNluGvgmSgU5OOTvkkd
session:
type: string
title: session
description: Identifier related to the current navigation, according to the [nanoid](https://github.com/ai/nanoid) pattern. It is a cookie that lasts for 30 minutes, changing if the user opens another tab in private navigation mode.
example: zZlNhqz1vFJP6iPG5Oqtt
SessionPing:
title: SessionPing
description: Sends an ACK to the API to renew the session server-side. It should be sent every 1 minute.
type: object
required:
- session
- anonymous
- type
- agent
properties:
session:
$ref: '#/components/schemas/UserIdentification/properties/session'
anonymous:
$ref: '#/components/schemas/UserIdentification/properties/anonymous'
type:
type: string
title: type
description: 'Type of event, which can be one of the following: `page.cart`, `page.empty_cart`, `search.query`, `page.confirmation`, `session.ping`, `search.click`.'
example: session.ping
agent:
type: string
title: agent
description: Identifies whether the request came from a mobile or desktop application. It's used as a filter in the search report.
default: desktop
example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0
PageCart:
title: PageCart
description: Sends an event every time the shopper enters the cart page. Each interaction should include all products inside the shopping cart at that time. In case a product is removed, sent the updated card.
type: object
required:
- session
- anonymous
- type
- products
properties:
session:
$ref: '#/components/schemas/UserIdentification/properties/session'
anonymous:
$ref: '#/components/schemas/UserIdentification/properties/anonymous'
products:
type: array
title: products
description: Array of objects containing products. If the event type is `page.cart`, the array contains all the products in the cart, with their ID and quantity. Each interaction should include all products inside the shopping cart at that time. In case a product is removed, sent the updated card. If there are no products in the cart (page.`empty_cart`), the array is empty. If the event type is `page.confirmation`, the array contains all the products that were purchased, with their ID, price and quantity.
items:
$ref: '#/components/schemas/CartProduct'
type:
type: string
title: type
description: 'Type of event, which can be one of the following: `page.cart`, `page.empty_cart`, `search.query`, `page.confirmation`, `session.ping`, `search.click`.'
example: page.cart
PageEmptyCart:
title: Empty Cart
description: Sends an event if there are no products in the shopping cart at that time.
type: object
required:
- session
- anonymous
- type
- products
properties:
session:
$ref: '#/components/schemas/UserIdentification/properties/session'
anonymous:
$ref: '#/components/schemas/UserIdentification/properties/anonymous'
products:
type: array
title: products
description: Array of objects containing products. If the event type is `page.cart`, the array contains all the products in the cart, with their ID and quantity. Each interaction should include all products inside the shopping cart at that time. In case a product is removed, sent the updated card. If there are no products in the cart (page.`empty_cart`), the array is empty. If the event type is `page.confirmation`, the array contains all the products that were purchased, with their ID, price and quantity.
items:
$ref: '#/components/schemas/CartProduct'
type:
type: string
title: type
description: 'Type of event, which can be one of the following: `page.cart`, `page.empty_cart`, `search.query`, `page.confirmation`, `session.ping`, `search.click`.'
example: page.empty_cart
PageConfirmation:
title: Page Confirmation
description: Sends a confirmation informing the products that were bought.
type: object
required:
- session
- anonymous
- type
- order
- products
properties:
session:
$ref: '#/components/schemas/UserIdentification/properties/session'
anonymous:
$ref: '#/components/schemas/UserIdentification/properties/anonymous'
products:
type: array
title: products
description: Array of objects containing products. If the event type is `page.cart`, the array contains all the products in the cart, with their ID and quantity. Each interaction should include all products inside the shopping cart at that time. In case a product is removed, sent the updated card. If there are no products in the cart (page.`empty_cart`), the array is empty. If the event type is `page.confirmation`, the array contains all the products that were purchased, with their ID, price and quantity.
items:
$ref: '#/components/schemas/OrderProduct'
order:
type: string
title: order
description: Order ID.
example: 123ABC
type:
type: string
title: type
description: 'Type of event, which can be one of the following: `page.cart`, `page.empty_cart`, `search.query`, `page.confirmation`, `session.ping`, `search.click`.'
example: page.confirmation
Click:
title: Search Click
description: Sends an event every time a shopper clicks on a product from a search page.
type: object
required:
- type
- productId
- position
- text
- anonymous
- session
properties:
type:
type: string
title: type
description: 'Type of event, which can be one of the following: `page.cart`, `page.empty_cart`, `search.query`, `page.confirmation`, `session.ping`, `search.click`.'
example: search.click
productId:
type: string
description: Unique identifier of the clicked product.
example: '12345'
position:
type: integer
description: Position of the clicked product on the search results page.
example: 1
url:
type: string
title: url
description: URL that identifies from which page the event occurred.
example: https://example.com/s?q=pneu&sort=score_desc&page=0
text:
type: string
title: text
description: Query used in the search.
example: tv
agent:
type: string
title: agent
description: Identifies whether the request came from a mobile or desktop application. It's used as a filter in the search report.
default: desktop
example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0
anonymous:
$ref: '#/components/schemas/UserIdentification/properties/anonymous'
session:
$ref: '#/components/schemas/UserIdentification/properties/session'
Query:
title: Search Query
description: Sends a query event every time the shopper makes a full-text search.
type: object
required:
- session
- anonymous
- type
- misspelled
- text
- match
- operator
properties:
session:
$ref: '#/components/schemas/UserIdentification/properties/session'
anonymous:
$ref: '#/components/schemas/UserIdentification/properties/anonymous'
url:
type: string
title: url
description: URL that identifies from which page the event occurred.
example: https://example.com/search/?query=zapatilha
agent:
type: string
title: agent
description: Identifies whether the request came from a mobile or desktop application. It's used as a filter in the search report.
default: desktop
example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0
type:
type: string
title: type
description: 'Type of event, which can be one of the following: `page.cart`, `page.empty_cart`, `search.query`, `page.confirmation`, `session.ping`, `search.click`.'
example: search.query
text:
type: string
title: text
description: Query used in the search.
example: tv
misspelled:
type: boolean
title: misspelled
description: Indicates whether the query has a typo (`true`) or not (`false`).
example: true
match:
type: number
title: match
description: Amount of products retrieved by the search.
example: 396
operator:
type: string
title: operator
description: 'Identifies the type of operator used on the search. The possible values are: `and`, `or`. Find more details in [this Elastic Search guide](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-query.html).'
example: and
CartProduct:
type: object
description: Product information.
required:
- productId
- quantity
properties:
productId:
type: string
description: Unique identifier of the product.
example: ABC123
quantity:
type: number
description: Quantity of the product.
example: 2
OrderProduct:
type: object
description: Product information.
required:
- productId
- price
- quantity
properties:
productId:
type: string
description: Unique identifier of the product.
example: ABC123
price:
type: number
description: Price of the product.
example: 9.99
quantity:
type: number
description: Quantity of the product.
example: 3
tags:
- name: Events