Retrieving ads

Learn how to fetch relevant ads based on context like search terms, categories, or behavior.

The VTEX Ads API allows you to retrieve three types of ad formats:

Sponsored products (Product ads)
Sponsored brands
Banner / Display ads

Use the POST Get ads endpoint to fetch both formats through a unified interface.

Responses are cached for 10 minutes.

All ad requests require:

A context (search, category, brand, product, or home)
User identification (user_id and session_id)
Placement configuration

Learn more about each field in the API Reference.

Search context

Used when retrieving ads for search results pages.


_11{
_11    "context": "search",
_11    "term": "desodorante",
_11    "user_id": "6a746448-cf59-42bc-aa3d-a426844ad115",
_11    "session_id": "f361661f-5986-4779-9009-a34562f18347",
_11    "tags": ["Mega Maio"],
_11    "placements": {
_11        "placementName1": { "quantity": 1, "size": "desktop", "types": ["banner"] },
_11        "placementName2": { "quantity": 2, "size": "tamanho3", "types": ["product"] }
_11    }
_11}

Category context

Used for category pages.


_10{
_10    "context": "category",
_10    "category_name": "Telefones e Celulares > Smartphones > iPhone",
_10    "user_id": "6a746448-cf59-42bc-aa3d-a426844ad115",
_10    "session_id": "f361661f-5986-4779-9009-a34562f18347",
_10    "placements": {
_10        "placementName1": { "quantity": 1, "size": "tamanho1", "types": ["banner"] },
_10        "placementName2": { "quantity": 2, "size": "tamanho3", "types": ["product"] }
_10    }
_10}

Brand context

Used for brand-specific pages.


_10{
_10    "context": "brand",
_10    "brand_name": "iphone",
_10    "user_id": "6a746448-cf59-42bc-aa3d-a426844ad115",
_10    "session_id": "f361661f-5986-4779-9009-a34562f18347",
_10    "placements": {
_10        "placementName1": { "quantity": 1, "size": "tamanho1", "types": ["banner"] },
_10        "placementName2": { "quantity": 2, "size": "tamanho3", "types": ["product"] }
_10    }
_10}

Product context (PDP)

Used on product detail pages.


_14{
_14  "context": "product_page",
_14  "product_sku": "120210",
_14  "product_attributes": {
_14    "category_name": "Telefones e Celulares > Smartphones > iPhone",
_14    "brand": "iphone"
_14  },
_14  "user_id": "6f92d1e9-00b6-4f8b-9645-faeab321e1cc",
_14  "session_id": "5898b8d1-c250-4bb5-931b-8b9d0ee7b499",
_14  "placements": {
_14    "placementName1": { "quantity": 1, "size": "tamanho1", "types": ["banner"] },
_14    "placementName2": { "quantity": 2, "size": "tamanho3", "types": ["product"] }
_14  }
_14}

Home context

Used for homepage or non-targeted contexts. Shows ads most relevant to the user based on their history.


_10{
_10  "context": "home",
_10  "user_id": "6f92d1e9-00b6-4f8b-9645-faeab321e1cc",
_10  "session_id": "5898b8d1-c250-4bb5-931b-8b9d0ee7b499",
_10  "placements": {
_10    "placementName1": { "quantity": 1, "size": "tamanho1", "types": ["banner"] },
_10    "placementName2": { "quantity": 2, "size": "tamanho3", "types": ["product"] }
_10  }
_10}

Response structure

Successful responses return HTTP code 200.

The response is a dictionary where:

Each key corresponds to a placement name from the request.
Results maintain the same order as the query.
Each ad includes tracking URLs for clicks, impressions and views.

Standard ad response example


_13{
_13    "placementName1": [
_13        {
_13            "ad_id": "6d2d8837-bf5a-4ba4-90d2-5546cb18d5ce",
_13            "media_url": "https://cdn.newtail.com.br/retail_media/ads/2023/05/03/f97a938660e56fe38a9c9ade21c27df8-1280x256-red.png",
_13            "destination_url": null,
_13            "type": "banner",
_13            "click_url": "https://events.newtail-media.newtail.com.br/v1/beacon/click/6d2d8837-bf5a-4ba4-90d2-5546cb18d5ce?publisher_id=0d675bf6-03f6-4b81-9617-e79dffddc3ab&ad_type=banner",
_13            "impression_url": "https://events.newtail-media.newtail.com.br/v1/beacon/impression/6d2d8837-bf5a-4ba4-90d2-5546cb18d5ce?publisher_id=0d675bf6-03f6-4b81-9617-e79dffddc3ab&ad_type=banner",
_13            "view_url": "https://events.newtail-media.newtail.com.br/v1/beacon/view/6d2d8837-bf5a-4ba4-90d2-5546cb18d5ce?publisher_id=0d675bf6-03f6-4b81-9617-e79dffddc3ab&ad_type=banner"
_13        }
_13    ]
_13}

Sponsored brands example

Sponsored brands campaigns have a different response format that includes brand information and related products.

🚧 All events must be triggered for both the ad and its products.

Request example:


_10{
_10    "context": "search",
_10    "term": "smartphone",
_10    "placements": {
_10        "placement_name": { "quantity": 1, "types": ["sponsored_brand"] }
_10    }
_10}

Response example:


_34{
_34    "placement_name": [
_34        {
_34            "type": "sponsored_brand",
_34            "assets": [
_34                {
_34                   "type": "image|video",
_34                   "url": "Image URL"
_34                }
_34            ],
_34            "brand_url": "https://cdn.newtail.com.br/retail_media/brands/logo.jpeg",
_34            "brand_name": "Apple",
_34            "destination_url": "https://www.extra.com.br/c?Filter=D70653",
_34            "headline": "Titanium. Very robust, very light, very pro!",
_34            "description": "",
_34            "view_url": "VIEW URL",
_34            "impression_url": "IMPRESSION URL",
_34            "click_url": "CLICK URL",
_34            "products": [
_34                {  
_34                    "image_url": "PRODUCT IMAGE URL",
_34                    "seller_id": null,
_34                    "product_metadata": { },
_34                    "product_name": "iPhone 15 Pro MAX",
_34                    "product_sku": "55064355",
_34                    "destination_url": "PRODUCT URL",
_34                    "impression_url": "IMPRESSION URL for a specific PRODUCT",
_34                    "view_url": "VIEW URL for a specific PRODUCT",
_34                    "click_url": "CLICK URL for a specific PRODUCT"
_34                }
_34            ]
_34        }
_34    ]
_34}