VTEX Events API

openapi: 3.2.0
info:
  title: VTEX Intelligent Search API - Headless Events API
  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.
  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.
tags:
- name: Events
paths:
  /event:
    post:
      summary: VTex Save events
      description: 'Creates search events to integrate with VTEX Intelligent Search using a headless implementation.


        >⚠️ **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
      operationId: postEvent
      x-operation-id-source: derived
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
    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'
    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
    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
    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
    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
    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
    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