VTEX Product List Page API

openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account Product List Page API
  description: ">ℹ️ Onboarding guide\r\n>\r\n> Check the new [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.\r\n\r\nThe Anti-fraud Provider Protocol is a set of definitions to help you integrate your anti-fraud service API into VTEX platform.\r\n\r\nTo achieve this, you need to implement a web API (REST) following the specifications described in this documentation.\r\n\r\n>⚠️ You can also access our [template on GitHub](https://github.com/vtex-apps/antifraud-provider-example) to help you quickly develop your anti-fraud connector using the Anti-fraud Provider Protocol and VTEX IO.\r\n\r\nTo learn more about the Anti-fraud Provider Protocol, check our [developer guide](https://developers.vtex.com/docs/guides/how-the-integration-protocol-between-vtex-and-antifraud-companies-works).\r\n\r\n## Anti-fraud Provider API Index\r\n\r\n### Anti-fraud  Flow\r\n\r\n- `POST` [Send Anti-fraud Pre-Analysis Data (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/pre-analysis)\r\n- `POST` [Send Anti-fraud Data](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/transactions)\r\n- `PUT` [Update Anti-fraud Transactions (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#put-/transactions/-transactionId-)\r\n- `GET` [List Anti-fraud Provider Manifest](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/manifest)\r\n- `GET` [Get Anti-fraud Status](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/transactions/-transactions.id-)\r\n- `DELETE` [Stop Anti-fraud Analysis (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#delete-/transactions/-transactions.Id-)\r\n\r\n### OAuth Flow\r\n\r\n1. `POST` [Retrieve Token](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/authorization/token)\r\n2. `GET` [Redirect](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/redirect)\r\n3. `GET` [Return to VTEX](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorizationCode)\r\n4. `GET` [Get Credentials](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorization/credentials)"
  version: '1.0'
servers:
- url: https://{providerApiEndpoint}
  description: Anti-fraud provider endpoint URL.
  variables:
    providerApiEndpoint:
      description: Anti-fraud provider endpoint URL.
      default: '{providerApiEndpoint}'
tags:
- name: Product List Page
paths:
  /correction_search:
    get:
      summary: VTex Get attempt of correction of a misspelled term
      description: "Tries to correct a misspelled term from the search.\r\n\r\nThis endpoint does not require authentication."
      tags:
      - Product List Page
      parameters:
      - $ref: '#/components/parameters/query'
      - $ref: '#/components/parameters/locale'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Correction'
              example:
                correction:
                  correction: true
                  misspelled: true
                  text: mountain bike
                  highlighted: mountain <em>bike</em>
  /banners/{facets}:
    get:
      summary: VTex Get list of banners registered for query
      description: "Lists the banners registered for a given query. Check the [configuring banners documentation](https://help.vtex.com/en/tracks/vtex-intelligent-search--19wrbB7nEQcmwzDPl1l4Cb/4ViKEivLJtJsvpaW0aqIQ5) for a full explanation of the banner feature.\r\n\r\nThis endpoint does not require authentication."
      tags:
      - Product List Page
      parameters:
      - $ref: '#/components/parameters/query'
      - $ref: '#/components/parameters/facetsPath'
      - $ref: '#/components/parameters/locale'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Banners'
              example:
                banners:
                - id: summersale
                  name: Summer Sale
                  area: '1'
                  html: <h1>This is a test</h1>
  /product_search/{facets}:
    get:
      summary: VTex Get list of products for a query
      description: "Lists the active products for a given query.\r\n\r\nThis endpoint does not require authentication."
      tags:
      - Product List Page
      parameters:
      - $ref: '#/components/parameters/facetsPath'
      - $ref: '#/components/parameters/query'
      - in: query
        name: simulationBehavior
        schema:
          type: string
          enum:
          - default
          - skip
          - only1P
          nullable: true
          default: default
        description: "Defines the simulation behavior.\n\n * `default` - Calls the simulation for every single seller.\n * `skip` - Never calls the simulation.\n * `only1P` - Only calls the simulation for first party sellers."
      - in: query
        name: count
        description: Number of products per page.
        schema:
          type: number
          nullable: true
          default: 24
      - in: query
        name: page
        description: Current search page.
        schema:
          type: number
          nullable: true
          default: 1
      - in: query
        name: sort
        description: "Defines the sort type. The possible values are: \r\n- `price:desc`: The results will be sorted by price in descending order, from highest to lowest.\r\n- `price:asc`: The results will be sorted by price in ascending order, from lowest to highest.\r\n- `orders:desc`: The results will be sorted by the amount of orders in the past 90 days, in descending order.\r\n- `name:desc`: The results will be sorted by name in descending alphabetical order.\r\n- `name:asc`: The results will be sorted by name in ascending alphabetical order.\r\n- `release:desc`: The results will be sorted by release date in descending order, from most recent to least recent.\r\n- `discount:desc`: The results will be sorted by discount percentage in descending order, from highest to lowest.\r\n\r\nIf `null`, the products will be sorted by relevance."
        schema:
          type: string
          nullable: true
          enum:
          - price:desc
          - price:asc
          - orders:desc
          - name:desc
          - name:asc
          - release:desc
          - discount:desc
          example: price:desc
      - $ref: '#/components/parameters/locale'
      - $ref: '#/components/parameters/hideUnavailableItems'
      responses:
        '200':
          description: List of products for the given query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductSearch'
              example:
                products:
                - cacheId: sp-2000003
                  productId: '2000003'
                  description: Introducing our exquisite Top Wood Clock, a timeless blend of elegance and craftsmanship. Crafted from premium-quality wood, this clock seamlessly combines functionality with aesthetic appeal. Its sleek design and rich wood finish make it a sophisticated addition to any space, from classic to contemporary interiors.
                  productName: Top Wood Clock
                  productReference: clock120
                  linkText: wood-clock
                  brand: Sony
                  brandId: 2000005
                  link: /wood-clock/p
                  categories:
                  - /Home & Decor/
                  categoryId: '40'
                  categoriesIds:
                  - /40/
                  priceRange:
                    sellingPrice:
                      highPrice: 197.99
                      lowPrice: 197.99
                    listPrice:
                      highPrice: 197.99
                      lowPrice: 197.99
                  specificationGroups:
                  - originalName: allSpecifications
                    name: allSpecifications
                    specifications:
                    - originalName: sellerId
                      name: sellerId
                      values:
                      - '1'
                  skuSpecifications: []
                  productClusters:
                  - id: '1970'
                    name: Summer
                  clusterHighlights:
                  - id: '1970'
                    name: Summer
                  properties:
                  - name: sellerId
                    originalName: sellerId
                    values:
                    - '1'
                  items:
                  - sellers:
                    - sellerId: '1'
                      sellerName: VTEX
                      addToCartLink: ''
                      sellerDefault: true
                      commertialOffer:
                        DeliverySlaSamplesPerRegion: {}
                        DeliverySlaSamples: []
                        AvailableQuantity: 10000
                        discountHighlights: []
                        Installments:
                        - Value: 197.99
                          InterestRate: 0
                          TotalValuePlusInterestRate: 197.99
                          NumberOfInstallments: 1
                          Name: American Express à vista
                          PaymentSystemName: American Express
                        - Value: 197.99
                          InterestRate: 0
                          TotalValuePlusInterestRate: 197.99
                          NumberOfInstallments: 1
                          Name: Visa à vista
                          PaymentSystemName: Visa
                        - Value: 98.99
                          InterestRate: 0
                          TotalValuePlusInterestRate: 197.99
                          NumberOfInstallments: 2
                          Name: Visa 2 vezes sem juros
                          PaymentSystemName: Visa
                        - Value: 65.99
                          InterestRate: 0
                          TotalValuePlusInterestRate: 197.99
                          NumberOfInstallments: 3
                          Name: Visa 3 vezes sem juros
                          PaymentSystemName: Visa
                        - Value: 49.49
                          InterestRate: 0
                          TotalValuePlusInterestRate: 197.99
                          NumberOfInstallments: 4
                          Name: Visa 4 vezes sem juros
                          PaymentSystemName: Visa
                        - Value: 39.59
                          InterestRate: 0
                          TotalValuePlusInterestRate: 197.99
                          NumberOfInstallments: 5
                          Name: Visa 5 vezes sem juros
                          PaymentSystemName: Visa
                        - Value: 32.99
                          InterestRate: 0
                          TotalValuePlusInterestRate: 197.99
                          NumberOfInstallments: 6
                          Name: Visa 6 vezes sem juros
                          PaymentSystemName: Visa
                        - Value: 197.99
                          InterestRate: 0
                          TotalValuePlusInterestRate: 197.99
                          NumberOfInstallments: 1
                          Name: Diners à vista
                          PaymentSystemName: Diners
                        - Value: 100.48
                          InterestRate: 100
                          TotalValuePlusInterestRate: 200.96
                          NumberOfInstallments: 2
                          Name: Diners 2 vezes com juros
                          PaymentSystemName: Diners
                        - Value: 197.99
                          InterestRate: 0
                          TotalValuePlusInterestRate: 197.99
                          NumberOfInstallments: 1
                          Name: Mastercard à vista
                          PaymentSystemName: Mastercard
                        - Value: 197.99
                          InterestRate: 0
                          TotalValuePlusInterestRate: 197.99
                          NumberOfInstallments: 1
                          Name: Boleto Bancário à vista
                          PaymentSystemName: Boleto Bancário
                        - Value: 197.99
                          InterestRate: 0
                          TotalValuePlusInterestRate: 197.99
                          NumberOfInstallments: 1
                          Name: Vale à vista
                          PaymentSystemName: Vale
                        - Value: 197.99
                          InterestRate: 0
                          TotalValuePlusInterestRate: 197.99
                          NumberOfInstallments: 1
                          Name: Promissory à vista
                          PaymentSystemName: Promissory
                        - Value: 197.99
                          InterestRate: 0
                          TotalValuePlusInterestRate: 197.99
                          NumberOfInstallments: 1
                          Name: Customer Credit à vista
                          PaymentSystemName: Customer Credit
                        - Value: 98.99
                          InterestRate: 0
                          TotalValuePlusInterestRate: 197.99
                          NumberOfInstallments: 2
                          Name: Customer Credit 2 vezes sem juros
                          PaymentSystemName: Customer Credit
                        - Value: 67.97
                          InterestRate: 100
                          TotalValuePlusInterestRate: 203.91
                          NumberOfInstallments: 3
                          Name: Customer Credit 3 vezes com juros
                          PaymentSystemName: Customer Credit
                        - Value: 197.99
                          InterestRate: 0
                          TotalValuePlusInterestRate: 197.99
                          NumberOfInstallments: 1
                          Name: Free à vista
                          PaymentSystemName: Free
                        Price: 197.99
                        ListPrice: 197.99
                        spotPrice: 197.99
                        taxPercentage: 0
                        PriceWithoutDiscount: 197.99
                        Tax: 0
                        GiftSkuIds: []
                        BuyTogether: []
                        ItemMetadataAttachment: []
                        RewardValue: 0
                        PriceValidUntil: '2023-04-01T13:13:20Z'
                        GetInfoErrorMessage: null
                        CacheVersionUsedToCallCheckout: ''
                        teasers:
                        - name: 8% Boleto
                          conditions:
                            minimumQuantity: 0
                            parameters:
                            - name: PaymentMethodId
                              value: '6'
                          effects:
                            parameters:
                            - name: PercentualDiscount
                              value: '8.0'
                    images:
                    - imageId: '155484'
                      cacheId: '155484'
                      imageTag: ''
                      imageLabel: ''
                      imageText: ''
                      imageUrl: https://storecomponents.vtexassets.com/arquivos/ids/155484/Frame.jpg?v=636793817478300000
                    - imageId: '155485'
                      cacheId: '155485'
                      imageTag: ''
                      imageLabel: ''
                      imageText: ''
                      imageUrl: https://storecomponents.vtexassets.com/arquivos/ids/155485/Frame-1.jpg?v=636793817642000000
                    - imageId: '155486'
                      cacheId: '155486'
                      imageTag: ''
                      imageLabel: ''
                      imageText: ''
                      imageUrl: https://storecomponents.vtexassets.com/arquivos/ids/155486/Frame-2.jpg?v=636793817785530000
                    itemId: '2000534'
                    name: '1'
                    nameComplete: Top Wood Clock 1
                    complementName: ''
                    referenceId:
                    - Key: RefId
                      Value: '16001'
                    measurementUnit: un
                    unitMultiplier: 1
                    variations: []
                    ean: '16001'
                    modalType: ''
                    videos: []
                    attachments: []
                    isKit: false
                  origin: intelligent-search
                - cacheId: sp-2000214
                  productId: '2000214'
                  description: ''
                  productName: kevin1
                  linkText: kevin1-lkn
                  brand: Sony
                  brandId: 2000005
                  link: /kevin1-lkn/p
                  categories:
                  - /Home & Decor/
                  categoryId: '40'
                  categoriesIds:
                  - /40/
                  priceRange:
                    sellingPrice:
                      highPrice: 10
                      lowPrice: 10
                    listPrice:
                      highPrice: 10
                      lowPrice: 10
                  specificationGroups:
                  - originalName: allSpecifications
                    name: allSpecifications
                    specifications:
                    - originalName: sellerId
                      name: sellerId
                      values:
                      - '1'
                  skuSpecifications: []
                  productClusters: []
                  clusterHighlights: []
                  properties:
                  - name: sellerId
                    originalName: sellerId
                    values:
                    - '1'
                  items:
                  - sellers:
                    - sellerId: '1'
                      sellerName: VTEX
                      addToCartLink: ''
                      sellerDefault: true
                      commertialOffer:
                        DeliverySlaSamplesPerRegion: {}
                        DeliverySlaSamples: []
                        AvailableQuantity: 10000
                        discountHighlights: []
                        Installments:
                        - Value: 10
                          InterestRate: 0
                          TotalValuePlusInterestRate: 10
                          NumberOfInstallments: 1
                          Name: American Express à vista
                          PaymentSystemName: American Express
                        - Value: 10
                          InterestRate: 0
                          TotalValuePlusInterestRate: 10
                          NumberOfInstallments: 1
                          Name: Visa à vista
                          PaymentSystemName: Visa
                        - Value: 10
                          InterestRate: 0
                          TotalValuePlusInterestRate: 10
                          NumberOfInstallments: 1
                          Name: Diners à vista
                          PaymentSystemName: Diners
                        - Value: 10
                          InterestRate: 0
                          TotalValuePlusInterestRate: 10
                          NumberOfInstallments: 1
                          Name: Mastercard à vista
                          PaymentSystemName: Mastercard
                        - Value: 10
                          InterestRate: 0
                          TotalValuePlusInterestRate: 10
                          NumberOfInstallments: 1
                          Name: Boleto Bancário à vista
                          PaymentSystemName: Boleto Bancário
                        - Value: 10
                          InterestRate: 0
                          TotalValuePlusInterestRate: 10
                          NumberOfInstallments: 1
                          Name: Vale à vista
                          PaymentSystemName: Vale
                        - Value: 10
                          InterestRate: 0
                          TotalValuePlusInterestRate: 10
                          NumberOfInstallments: 1
                          Name: Promissory à vista
                          PaymentSystemName: Promissory
                        - Value: 10
                          InterestRate: 0
                          TotalValuePlusInterestRate: 10
                          NumberOfInstallments: 1
                          Name: Customer Credit à vista
                          PaymentSystemName: Customer Credit
                        - Value: 5
                          InterestRate: 0
                          TotalValuePlusInterestRate: 10
                          NumberOfInstallments: 2
                          Name: Customer Credit 2 vezes sem juros
                          PaymentSystemName: Customer Credit
                        - Value: 3.43
                          InterestRate: 100
                          TotalValuePlusInterestRate: 10.29
                          NumberOfInstallments: 3
                          Name: Customer Credit 3 vezes com juros
                          PaymentSystemName: Customer Credit
                        - Value: 10
                          InterestRate: 0
                          TotalValuePlusInterestRate: 10
                          NumberOfInstallments: 1
                          Name: Free à vista
                          PaymentSystemName: Free
                        Price: 10
                        ListPrice: 10
                        spotPrice: 10
                        taxPercentage: 0
                        PriceWithoutDiscount: 10
                        Tax: 0
                        GiftSkuIds: []
                        BuyTogether: []
                        ItemMetadataAttachment: []
                        RewardValue: 0
                        PriceValidUntil: '2023-04-01T13:13:20Z'
                        GetInfoErrorMessage: null
                        CacheVersionUsedToCallCheckout: ''
                        teasers:
                        - name: 8% Boleto
                          conditions:
                            minimumQuantity: 0
                            parameters:
                            - name: PaymentMethodId
                              value: '6'
                          effects:
                            parameters:
                            - name: PercentualDiscount
                              value: '8.0'
                    images:
                    - imageId: '155675'
                      cacheId: '155675'
                      imageTag: ''
                      imageLabel: vtex
                      imageText: vtex
                      imageUrl: https://storecomponents.vtexassets.com/arquivos/ids/155675/vtex.jpg?v=637655270451200000
                    itemId: '310124211'
                    name: kevin1sku
                    nameComplete: kevin1sku
                    complementName: ''
                    referenceId:
                    - Key: RefId
                      Value: 2983678w63478
                    measurementUnit: un
                    unitMultiplier: 1
                    variations: []
                    ean: '2398428937489'
                    modalType: ''
                    videos: []
                    attachments: []
                    isKit: false
                  origin: intelligent-search
                recordsFiltered: 5
                correction:
                  misspelled: false
                fuzzy: '0'
                operator: and
                translated: false
  /facets/{facets}:
    get:
      summary: VTex Get list of the possible facets for a given query
      description: "Lists the possible facets for a given query.\r\n\r\nThis endpoint does not require authentication."
      tags:
      - Product List Page
      parameters:
      - $ref: '#/components/parameters/facetsPath'
      - $ref: '#/components/parameters/query'
      - $ref: '#/components/parameters/locale'
      - $ref: '#/components/parameters/hideUnavailableItems'
      responses:
        '200':
          description: List of facets for the given query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Facets'
              example:
                facets:
                - values:
                  - id: '47'
                    quantity: 1
                    name: Clothing
                    key: category-2
                    value: clothing
                    selected: false
                    href: shirt/blue/clothing?map=ft,color,category
                  type: TEXT
                  name: Category
                  hidden: false
                  key: category-2
                  quantity: 1
                - values:
                  - quantity: 1
                    name: ''
                    key: price
                    selected: false
                    range:
                      from: 45
                      to: 50
                  type: PRICERANGE
                  name: Price
                  hidden: false
                  key: price
                  quantity: 1
                - values:
                  - id: '2000045'
                    quantity: 1
                    name: New Offers!!
                    key: brand
                    value: new-offers--
                    selected: false
                    href: shirt/blue/new-offers--?map=ft,color,brand
                  type: TEXT
                  name: Brand
                  hidden: false
                  key: brand
                  quantity: 1
                - values:
                  - id: '103'
                    quantity: 1
                    name: Blue
                    key: color
                    value: blue
                    selected: true
                    href: shirt/blue/blue?map=ft,color,color
                  type: TEXT
                  name: Color
                  hidden: true
                  key: color
                  quantity: 1
                - values:
                  - id: '25'
                    quantity: 1
                    name: Apparel & Accessories
                    key: category-1
                    value: apparel---accessories
                    selected: false
                    href: shirt/blue/apparel---accessories?map=ft,color,department
                  type: TEXT
                  name: Department
                  hidden: false
                  key: category-1
                  quantity: 1
                - values:
                  - id: ''
                    quantity: 1
                    name: Test
                    key: filter-test
                    value: test
                    selected: false
                    href: shirt/blue/test?map=ft,color,filter-test
                  type: TEXT
                  name: Filter Test
                  hidden: false
                  key: filter-test
                  quantity: 1
                - values:
                  - id: '48'
                    quantity: 1
                    name: Tops
                    key: category-3
                    value: tops
                    selected: false
                    href: shirt/blue/tops?map=ft,color,subcategory
                  type: TEXT
                  name: Subcategory
                  hidden: false
                  key: category-3
                  quantity: 1
                sampling: false
                breadcrumb:
                - name: shirt
                  href: /shirt?map=ft
                - name: Blue
                  href: /shirt/blue?map=ft,color
                queryArgs:
                  query: shirt
                  selectedFacets:
                  - key: color
                    value: blue
                  - key: ft
                    value: shirt
                translated: false
components:
  parameters:
    hideUnavailableItems:
      in: query
      name: hideUnavailableItems
      description: Defines whether the result should hide unavailable items (`true`), or not (`false`).
      schema:
        type: boolean
        default: false
    locale:
      in: query
      name: locale
      description: Indicates the target language as a BCP 47 language code. The Intelligent Search must have indexed the account in the target language.
      example: en-US
      schema:
        type: string
        nullable: true
    facetsPath:
      in: path
      name: facets
      required: true
      description: "## Format\r\n\r\nThe `facets` parameter follows the format: `/${facetKey1}/${facetValue1}/${facetKey2}/${facetValue2}/.../${facetKeyN}/${facetValueN}`.\r\n\r\nThe order in which the terms appear is not relevant to the search.\r\n\r\nYou can also repeat the same `facetKey` several times for different values. For example: `category-1/shoes/color/blue/color/red/color/yellow`.\r\n\r\n## General filters\r\n\r\nThe `facets` parameter also allows the following general filters:\r\n\r\n| `facetKey` | Description | Example |\r\n| - | - | - |\r\n| `price` | Filter the search by a price range, following the format `${minPrice}:${maxPrice}`. | `/color/blue/price/100:500?query=shirt` |\r\n| `category-${n}` | Filter the search by category, where `n` represents the category tree level (1 = department, 2 = category, 3 = subcategory, and so on). | `category-1/clothing/category-2/shirts` |\r\n| `productClusterIds` | Filter the search by collection, following the format `productClusterIds/{collectionId}`. | `productClusterIds/262` |\r\n| `trade-policy` |  Filter the search by trade policy (also known as sales channel), following the format `trade-policy/{tradePolicyId}`. | `trade-policy/2`|\n"
      example: category-1/clothing/category-2/shirt/category-3/man
      schema:
        nullable: true
        type: string
        default: /
        example: color/blue
    query:
      in: query
      name: query
      description: Search term. It can contain any character.
      schema:
        type: string
        example: shirt
  schemas:
    Facets:
      type: object
      description: Response body object.
      properties:
        facets:
          type: array
          description: List of facets.
          items:
            type: object
            description: Facet information.
            properties:
              values:
                type: array
                description: Possible values.
                items:
                  type: object
                  description: Value information.
                  properties:
                    id:
                      type: string
                      description: Value ID.
                    quantity:
                      type: number
                      description: Number of resulting products.
                    name:
                      type: string
                      description: Human-readable format of the facet value.
                    key:
                      type: string
                      description: Facet key.
                    value:
                      type: string
                      description: Facet value.
                    selected:
                      type: boolean
                      description: Defines whether the value is selected (`true`) or not (`false`).
                    href:
                      type: string
                      description: Query URL.
              type:
                type: string
                description: "Facet type\n - `TEXT` - The value is a simple text.\n - `PRICERANGE` - The value contains the property `range` representing the minimum and the maximum price for the query."
                enum:
                - TEXT
                - PRICERANGE
         

# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-product-list-page-api-openapi.yml