vtexads-api-docs

5.5. Ad Query

With the catalog synchronized, your platform requests ads to fill the ad spaces (placements). The request is a POST and the publisher_id must be provided in the URL.

Request Best Practices

Request Parameters

Field Description Type Required?
session_id Persistent visitor identifier (≥ 14 days). String Yes
user_id Unique ID of the logged-in user (alphanumeric). String No (Recommended)
store_id Filters ads by a specific store’s stock. String No
channel Access channel: site, msite, app (for ad query). String Yes
context Context: home, category, search, product_page, brand_page, digital_signage. String Yes
term Term searched by the user. String Only context: 'search'
category_name Browsed category (full breadcrumb). String Only context: 'category'
product_sku SKU of the product being viewed. String Only context: 'product_page'
brand_name Name of the brand being viewed. String Only context: 'brand_page'
device_id Unique device ID (screen, totem). String Only context: 'digital_signage'
store_name Name of the store where the device is located. String Only context: 'digital_signage'
placements Object defining the ad placements. Object Yes
placements.{name}.quantity Desired number of ads. Integer Yes
placements.{name}.size Expected size (Image: desktop/mobile; Video: 1080p/720p/480p/360p/320p). String Only types: ['banner', 'sponsored_brand']
placements.{name}.types Allowed types (product, banner, etc.). Array[String] Yes
placements.{name}.assets_type Accepted media (image, video). Default: ["image"]. Array[String] Only types: ['banner', 'sponsored_brand']
placements.{name}.allow_sku_duplications Allows the same SKU to appear more than once within the same placement. Boolean No (Default=false)
userAgent Client environment identification (body field, not the HTTP User-Agent header). String No
segmentation Data for real-time targeting. Array[Object] No
segmentation.#.key The type of segmentation. String No
segmentation.#.values Array of values for the segmentation. Array[String] No
tags “Tags” to contextualize searches (primarily for search). Max 10 per SKU, 64 chars per tag. Only for product campaigns. Array[String] No
brand Publisher’s site name. String Required when the publisher has multiple sites
dedup_campaign_ads Deduplicate by campaign (response contains at most one ad per campaign). Boolean No (Default=false)
dedup_ads Deduplicate by ad_id across multiple placements (use only when querying multiple placements at the same time). Boolean No (Default=false)
Fields by Context
Context Additional required fields
home —
search term
category category_name
product_page product_sku
brand_page brand_name
digital_signage device_id, store_name

⚠️ Important Context and Ad Eligibility Rules

Filter Limitations

Important: It is not possible to filter by specific placement. Ad selection is based on context and request parameters.

Eligibility by Context
home Context

In the home context, the following can be returned:

Example:

{
  "context": "home",
  "placements": {
    "site_home_middle_banner": {
      "quantity": 3,
      "types": ["banner", "sponsored_brand"],
      "assets_type": ["image", "video"],
      "size": "desktop"
    },
    "site_home_shelf_product": {
      "quantity": 10,
      "types": ["product"]
    }
  }
}
brand_page Context

In the brand_page context, the following can be returned:

Example:

{
  "context": "brand_page",
  "brand_name": "Nike",
  "placements": {
    "site_brand_top_banner": {
      "quantity": 1,
      "types": ["banner", "sponsored_brand"],
      "assets_type": ["image"],
      "size": "desktop"
    },
    "site_brand_shelf_product": {
      "quantity": 12,
      "types": ["product"]
    }
  }
}
digital_signage Context

In the digital_signage context, ads can be returned for physical screens/totems.

Example:

{
  "context": "digital_signage",
  "device_id": "totem-abc-001",
  "store_name": "Downtown Store",
  "placements": {
    "totem_home_main_video": {
      "quantity": 1,
      "types": ["banner"],
      "assets_type": ["video"],
      "size": "720p"
    }
  }
}
search Context

In the search context, the following can be returned:

⚠️ Exact Keyword Matching:

Keyword matching in the search context is exact (no stemming/synonyms). This means:

Example:

{
  "context": "search",
  "term": "nike shoes",
  "placements": {
    "site_search_top_banner": {
      "quantity": 1,
      "types": ["banner", "sponsored_brand"],
      "assets_type": ["image"],
      "size": "desktop"
    },
    "site_search_shelf_product": {
      "quantity": 20,
      "types": ["product"]
    }
  }
}

Expected behavior:

category Context

In the category context, the following can be returned:

Example:

{
  "context": "category",
  "category_name": "Sports > Shoes > Sneakers",
  "placements": {
    "site_category_top_banner": {
      "quantity": 1,
      "types": ["banner", "sponsored_brand"],
      "assets_type": ["image", "video"]
    }
  }
}
product_page Context

In the product_page context, the following can be returned:

Example:

{
  "context": "product_page",
  "product_sku": "12345",
  "placements": {
    "site_product_recommendation": {
      "quantity": 5,
      "types": ["product"]
    }
  }
}

Query Response

The response is a JSON where each key is a placement name. The structure of each ad in the response depends on its type.

Common Response Fields for All Ad Types

These fields are present in all ad types:

Field Description
{placementName}.#.ad_id Unique ad ID.
{placementName}.#.type Ad type (product, banner, sponsored_brand, digital_signage).
{placementName}.#.click_url URL to notify the click event.
{placementName}.#.impression_url URL to notify the impression event.
{placementName}.#.view_url URL to notify the view event.
{placementName}.#.seller_id ID of the seller of the advertised product (optional).
Type-Specific Response Fields
Product Ads

Additional fields for ads of type product:

Field Description
{placementName}.#.product_sku SKU of the product being advertised.

Additional fields for ads of type banner:

Field Description
{placementName}.#.media_url URL of the image or video to be displayed.

Additional fields for ads of type sponsored_brand:

Field Description
{placementName}.#.media_url URL of the image or video to be displayed.
{placementName}.#.products Array of products associated with the sponsored brand.
{placementName}.#.products.#.product_sku SKU of the associated product.
{placementName}.#.products.#.media_url URL of the product image.
Digital Signage Ads

Additional fields for ads of type digital_signage:

Field Description
{placementName}.#.media_url URL of the image or video to be displayed.
{placementName}.#.duration Duration of the ad display in seconds.
Example Response (multi-placement)
{
  "site_home_middle_banner": [
    {
      "ad_id": "ad-001",
      "type": "banner",
      "media_url": "https://cdn.example.com/banner1.jpg",
      "impression_url": "https://events.../impression/abc",
      "view_url": "https://events.../view/abc",
      "click_url": "https://events.../click/abc"
    }
  ],
  "site_home_shelf_product": [
    {
      "ad_id": "ad-101",
      "type": "product",
      "product_sku": "SKU-123",
      "seller_id": "SELLER-9",
      "impression_url": "https://events.../impression/def",
      "view_url": "https://events.../view/def",
      "click_url": "https://events.../click/def"
    }
  ]
}

Best Practices

Placement Naming

Adopt a clear standard, such as {channel}_{context}_{position}_{type} (e.g., msite_search_top-shelf_product). For detailed recommendations, see en/docs/5.5.1-placement-naming.md.

channel context position type example
site home middle banner site_home_middle_banner
msite product top-shelf product msite_product_top-shelf_product
app search top-shelf product app_search_top-shelf_product
app search top-shelf banner app_search_top-shelf_banner
site category bottom-shelf banner site_category_bottom-shelf_banner
site product filter-bar product site_product_filter-bar_product

IAB Standard Image Sizes

For banner-type ads, it is important to use images in the standard formats defined by the IAB (Interactive Advertising Bureau). This ensures compatibility and a better visual experience across different sites and devices.

Main Formats:

Video Size Options

For video ad requests, you should specify the size parameter to filter by video resolution. The available options are:

Important: When requesting video ads, use only the resolution identifier (e.g., "720p") in the size parameter, not the full dimensions. For example, to filter by 1280x720 resolution, use "size": "720p" in your ad request.

Ad Targeting

Target ads to specific audiences to increase relevance.

Real-Time Targeting

Send demographic or audience data directly in the body of the ad query, in the segmentation field.

The segmentation field is an array of objects, where each object contains:

Segmentation Example:

[
    {
        "key": "STATE",
        "values": [
            "CA"
        ]
    },
    {
        "key": "CITY",
        "values": [
            "San Francisco"
        ]
    }
]

Available Segmentation Types:

Key Description Example Values
STATE User’s state “CA”, “NY”, “TX”
CITY User’s city “San Francisco”, “New York”
GENDER User’s gender “M”, “F”
AGE User’s age “22”, “35”
AUDIENCES Custom audience “high_value_customers”, “cart_abandoners”
NBO_CATEGORIES Indicates the possible categories that the user intends to buy “Electronics”, “Books”

Response Codes and Errors

Example 422 (partial):

[
  {
    "instancePath": "/context",
    "keyword": "enum",
    "message": "must be equal to one of the allowed values",
    "params": {"allowedValues": ["home","category","search","product_page","brand_page","digital_signage"]},
    "schemaPath": "#/properties/context/enum"
  }
]