{ "openapi": "3.0.0", "info": { "version": "1.0.0", "title": "VTEX Ads API", "description": "VTEX Ads API enables merchants and marketplace operators to synchronize product catalogs, display ads in the storefront, record ad interactions, among other operations within the VTEX Ads platform.\n\nThis API is primarily used by:\n- Store developers\n- Marketplace operators\n- Integration partners\n- Advertising platform providers\n\nWith this API you can:\n- Synchronize product catalog information for advertising\n- Track ad impressions, clicks, and views\n- Monitor conversion events and campaign performance\n- Manage ad inventory and placements\n\n>ℹ️ Learn more about [VTEX Ads](https://help.vtex.com/en/docs/tracks/retail-media).\n\n## Architecture\n\nVTEX Ads is **cookie-less**. Identification and targeting rely on first-party identifiers — `user_id` and `session_id` — rather than third-party cookies, ensuring compliance with modern privacy regulations.\n\n- **`session_id`:** Persistent visitor identifier, required in every ad query and event. It must remain stable for at least 14 days (the default conversion window). For mobile applications, send the device ID as the `session_id` (GAID on Android, IDFA on iOS) so that the session is maintained indefinitely.\n- **`user_id`:** Unique customer identifier on the publisher's platform. It must be consistent across web, mobile app, and physical store. Required in conversion events; recommended for impressions, clicks, and views.\n\n## Before you begin\n\n- **Base URLs.** The API is served from three hosts depending on the operation:\n - `https://api-retail-media.newtail.com.br` — Catalog synchronization, Reports, Credit transfer webhook, and SSO.\n - `https://newtail-media.newtail.com.br` — Ad query.\n - `https://events.newtail-media.newtail.com.br` — Ads events notification (impression, click, view, conversion).\n- **Authentication.** Catalog synchronization, Reports, and SSO endpoints require the `X-App-Id` and `X-Api-Key` headers. Ad query and ads event notifications are public and do not require authentication. The Credit transfer webhook uses a different scheme: `X-Api-Key` and `X-Secret-Key` (it does not use `X-App-Id`). Contact [our support](https://help.vtex.com/en/tutorial/how-does-vtex-support-work--2eAT5EyOvaLoHdIWDVaxC3) to obtain credentials.\n- **Bulk operations.** A maximum of 500 objects per request and 3 simultaneous requests are allowed for catalog and inventory updates.\n- **Event URLs.** The event URLs for tracking impressions, clicks, and views must not be constructed manually — always use the URLs returned by `POST` [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-).\n- **Browser-side events.** Use `navigator.sendBeacon()` to fire impression, view, click, and conversion events from the browser. It ensures asynchronous delivery even when the user navigates away or closes the page.\n- **PII hashing.** All personally identifiable fields (`email_hashed`, `phone_hashed`, `social_id_hashed`, `first_name_hashed`, `last_name_hashed`) must be hashed with SHA-256 before being sent. Normalization before hashing is required and the rules differ per field. See the PII hashing and normalization section in `POST` [Track conversions](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/beacon/conversion).\n- **Reports export.** Reports return JSON by default. Set `download=true` to receive an XLSX file (capped at 20,000 rows per export).\n- **Rate limits.** Reports endpoints are limited to 100 requests per minute per account. This limit applies only to API Key-authenticated calls and does not affect normal platform use through the UI. Requests that exceed the limit receive `429 Too Many Requests` with \"Rate limit exceeded for this account\". Wait for the next window before retrying, and spread large export workloads over time. Contact [our support](https://help.vtex.com/en/tutorial/how-does-vtex-support-work--2eAT5EyOvaLoHdIWDVaxC3) if your integration needs a higher volume.\n- **Ad query performance.** Apply a 500-600 ms timeout to ad query calls and prefer persistent HTTP connections (`Connection: keep-alive`).\n\n## Attribution and deduplication\n\n- **Default conversion window:** 14 days from the user's interaction (click for product campaigns; view for banner, video, and sponsored brand campaigns).\n- **Conversion idempotency:** Re-sending the same `order_id` within 30 days is ignored.\n- **Event deduplication:** For the same user and ad, impressions are deduplicated for 1 minute and clicks for 1 hour.\n- **Data latency:** Conversions appear in reports approximately 30 minutes (API integrations) or up to 2 hours (VTEX platform) after the order is placed.\n\n| Parameter name | Description | Type |\n| - | - | - |\n| `X-App-Id` | Publisher App ID for authorization | Authentication header |\n| `X-Api-Key` | API Key for authentication | Authentication header |\n| `X-Secret-Key` | Secret key paired with `X-Api-Key` for the credit transfer webhook | Authentication header |\n| `Content-Type` | Type of the content being sent | Request header |\n| `Accept` | HTTP Client Negotiation Accept Header | Request header |" }, "servers": [ { "url": "https://api-retail-media.newtail.com.br", "description": "VTEX Ads server." }, { "url": "https://newtail-media.newtail.com.br", "description": "VTEX Ads ad query server." }, { "url": "https://events.newtail-media.newtail.com.br", "description": "VTEX Ads events server." } ], "paths": { "/product/bulk/products": { "servers": [ { "url": "https://api-retail-media.newtail.com.br", "description": "VTEX Ads server." } ], "post": { "tags": [ "Catalog synchronization" ], "summary": "Synchronize product information", "description": "Updates the basic product data in the VTEX Ads catalog.\r\n\r\n>⚠️ For each batch insert/update, a maximum of 500 objects per request and 3 simultaneous requests are allowed.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "maxItems": 500, "items": { "type": "object", "description": "Product object.", "required": [ "product_sku", "name", "url", "categories" ], "properties": { "product_sku": { "type": "string", "description": "Product ID to be inserted/updated.", "example": "teste-120210" }, "parent_sku": { "type": "string", "description": "SKU of the parent product.", "example": "teste-120200" }, "name": { "type": "string", "description": "Product name.", "example": "TechBrand Laptop Model X-15 4GB 256GB SSD 15.6\" Display Windows 11 - Gray" }, "url": { "type": "string", "description": "URL of the product page.", "example": "https://www.example.com/product/4100903080" }, "image_url": { "type": "string", "description": "URL of the main product image.", "example": "https://images.example.com/products/01/00/img/4100903/1/4100903143_1GG.jpg" }, "categories": { "type": "array", "description": "List of product categories.", "items": { "type": "string", "description": "Product category." }, "example": [ "Computers", "Laptops" ] }, "brand": { "type": "string", "description": "Product brand.", "example": "TechBrand" }, "gtins": { "type": "array", "description": "Barcode. For Newtail Network, sending the GTIN is mandatory.", "items": { "type": "string", "description": "Product GTIN." }, "example": [ "7898915633481" ] }, "metadata": { "type": "object", "description": "Additional product information.", "example": { "key": "value1" } }, "tags": { "type": "array", "description": "List of product tags to be used later during ad queries (`POST` [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-)) to better contextualize the search. Maximum of 10 tags per SKU, maximum of 64 characters per tag. Only works for Product campaigns.", "maxItems": 10, "items": { "type": "string", "maxLength": 64, "description": "Product tag." }, "example": [ "Special Sale" ] }, "sellers": { "type": "array", "description": "List of sellers who sell that product. Maximum of 64 characters per seller.", "items": { "type": "string", "maxLength": 64, "description": "Seller name." }, "example": [ "Seller1", "Seller2" ] } } } }, "example": [ { "product_sku": "sample-120210", "name": "TechBrand Laptop Model X-15 4GB 256GB SSD 15.6\" Display Windows 11 - Gray", "url": "https://www.example.com/product/4100903080", "image_url": "https://images.example.com/products/01/00/img/4100903/1/4100903143_1GG.jpg", "categories": [ "Computers", "Laptops" ], "brand": "TechBrand", "gtins": [ "7898915633481" ], "metadata": { "key": "value1" } }, { "product_sku": "sample-120211", "name": "TechBrand Laptop Model X-15 4GB 256GB SSD 15.6\" Display Windows 11 - Gray", "url": "https://www.example.com/product/4100903080", "categories": [ "Computers", "Laptops" ], "brand": "TechBrand", "gtins": [ "7898915633481" ], "tags": [ "Mega Maio" ] } ] } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "description": "List of messages from the server.", "items": { "type": "string", "description": "Message from the server." } } } }, "example": { "messages": [ "products will be processed soon" ] } } } }, "422": { "description": "Validation Error" } } } }, "/product/bulk/inventories": { "servers": [ { "url": "https://api-retail-media.newtail.com.br", "description": "VTEX Ads server." } ], "post": { "tags": [ "Catalog synchronization" ], "summary": "Synchronize inventory information", "description": "Update inventory information, which defines the price, promotional price, and product availability.\r\n\r\n>⚠️ For each batch insert/update, a maximum of 500 objects per request and three simultaneous requests are allowed.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "maxItems": 500, "items": { "type": "object", "description": "Inventory object.", "required": [ "product_sku", "price", "promotional_price", "is_available" ], "properties": { "product_sku": { "type": "string", "description": "Product ID to be inserted/updated.", "example": "120210" }, "store_id": { "type": "string", "description": "Store identifier. If store_id is not sent, it will be interpreted that this inventory information will be used for all stores.", "example": "1" }, "price": { "type": "number", "description": "Product price.", "format": "double", "example": 18.2 }, "promotional_price": { "type": "number", "description": "Promotional price of the product. Use 0 to remove the promotional price.", "format": "double", "example": 16.32 }, "is_available": { "type": "boolean", "description": "Indicates if the product is available for sale.", "example": true }, "metadata": { "type": "object", "description": "Additional inventory information.", "example": { "warehouse": "central" } } } } }, "example": [ { "product_sku": "120210", "store_id": "1", "price": 18.2, "promotional_price": 16.32, "is_available": true }, { "product_sku": "120212", "price": 18.2, "promotional_price": 0, "is_available": true } ] } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "description": "List of messages from the server.", "items": { "type": "string", "description": "Message from the server." } } } }, "example": { "messages": [ "inventory will be processed soon" ] } } } }, "422": { "description": "Validation Error" } } } }, "/v1/beacon/impression/{ad_id}": { "servers": [ { "url": "https://events.newtail-media.newtail.com.br", "description": "VTEX Ads events server." } ], "post": { "tags": [ "Ads events notification" ], "summary": "Track ad impressions", "description": "Track when an ad is rendered on a page. An impression does not determine whether the ad became visible to the user. Visibility is tracked by the separate `view` event. Do not construct the event URL manually. Always use the URL provided from `POST` [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-).\r\n\r\n>ℹ️ Fire this event whenever a page loads that contains rendered ads.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "ad_id", "in": "path", "description": "Unique identifier of the ad.", "required": true, "schema": { "type": "string", "example": "4a94bc6e-7db1-425f-8430-cb4d17488b3b" } }, { "name": "pos", "in": "query", "description": "Position of the ad.", "required": false, "schema": { "type": "string", "example": "1" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "title": "Identified user", "type": "object", "description": "Use this variant when an identified user is sending the event. Provide `user_id`; `session_id` is optional but recommended.", "required": [ "user_id" ] }, { "title": "Anonymous session", "type": "object", "description": "Use this variant when no identified user is available yet. Provide `session_id`; `user_id` is optional.", "required": [ "session_id" ] } ], "properties": { "user_id": { "type": "string", "description": "Unique identifier for the user within your platform. It must remain consistent across all user touchpoints and sales channels. Required when `session_id` is not provided." }, "session_id": { "type": "string", "description": "Persistent visitor identifier. Must remain stable for at least 14 days. For mobile apps, use the device ID (GAID on Android, IDFA on iOS). Required when `user_id` is not provided." } } }, "examples": { "with_user_id": { "summary": "Identified user", "value": { "user_id": "6f92d1e9-00b6-4f8b-9645-faeab321e1cc" } }, "with_session_id": { "summary": "Anonymous session", "value": { "session_id": "5898b8d1-c250-4bb5-931b-8b9d0ee7b499" } } } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "description": "List of messages from the server.", "items": { "type": "string", "description": "Message from the server." } } } }, "example": { "messages": [ "impression will be processed soon" ] } } } }, "422": { "description": "Validation Error" } } } }, "/v1/beacon/click/{ad_id}": { "servers": [ { "url": "https://events.newtail-media.newtail.com.br", "description": "VTEX Ads events server." } ], "post": { "tags": [ "Ads events notification" ], "summary": "Track ad clicks", "description": "Track when a user clicks on an ad. The event URL must not be constructed manually — always use the URL provided from `POST` [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-).\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "ad_id", "in": "path", "description": "Unique identifier of the ad.", "required": true, "schema": { "type": "string", "example": "4a94bc6e-7db1-425f-8430-cb4d17488b3b" } }, { "name": "pos", "in": "query", "description": "Position of the ad.", "required": false, "schema": { "type": "string", "example": "1" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "title": "Identified user", "type": "object", "description": "Use this variant when an identified user is sending the event. Provide `user_id`; `session_id` is optional but recommended.", "required": [ "user_id" ] }, { "title": "Anonymous session", "type": "object", "description": "Use this variant when no identified user is available yet. Provide `session_id`; `user_id` is optional.", "required": [ "session_id" ] } ], "properties": { "user_id": { "type": "string", "description": "Unique identifier for the user within your platform. It must remain consistent across all user touchpoints and sales channels. Required when `session_id` is not provided." }, "session_id": { "type": "string", "description": "Persistent visitor identifier. Must remain stable for at least 14 days. For mobile apps, use the device ID (GAID on Android, IDFA on iOS). Required when `user_id` is not provided." } } }, "examples": { "with_user_id": { "summary": "Identified user", "value": { "user_id": "6f92d1e9-00b6-4f8b-9645-faeab321e1cc" } }, "with_session_id": { "summary": "Anonymous session", "value": { "session_id": "5898b8d1-c250-4bb5-931b-8b9d0ee7b499" } } } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "description": "List of messages from the server.", "items": { "type": "string", "description": "Message from the server." } } } }, "example": { "messages": [ "click will be processed soon" ] } } } }, "422": { "description": "Validation Error" } } } }, "/v1/beacon/view/{ad_id}": { "servers": [ { "url": "https://events.newtail-media.newtail.com.br", "description": "VTEX Ads events server." } ], "post": { "tags": [ "Ads events notification" ], "summary": "Track ad views", "description": "Track when an ad becomes visible to the user. Do not construct the event URL manually. Always use the URL provided from `POST` [Get ads](https://developers.vtex.com/docs/api-reference/vtex-ads-api#post-/v1/rma/-publisher_id-).\r\n\r\n>ℹ️ Fire this event when the ad occupies at least 50% of the viewport for at least 1 second.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "ad_id", "in": "path", "description": "Unique identifier of the ad.", "required": true, "schema": { "type": "string", "example": "4a94bc6e-7db1-425f-8430-cb4d17488b3b" } }, { "name": "pos", "in": "query", "description": "Position of the ad.", "required": false, "schema": { "type": "string", "example": "1" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "title": "Identified user", "type": "object", "description": "Use this variant when an identified user is sending the event. Provide `user_id`; `session_id` is optional but recommended.", "required": [ "user_id" ] }, { "title": "Anonymous session", "type": "object", "description": "Use this variant when no identified user is available yet. Provide `session_id`; `user_id` is optional.", "required": [ "session_id" ] } ], "properties": { "user_id": { "type": "string", "description": "Unique identifier for the user within your platform. It must remain consistent across all user touchpoints and sales channels. Required when `session_id` is not provided." }, "session_id": { "type": "string", "description": "Persistent visitor identifier. Must remain stable for at least 14 days. For mobile apps, use the device ID (GAID on Android, IDFA on iOS). Required when `user_id` is not provided." } } }, "examples": { "with_user_id": { "summary": "Identified user", "value": { "user_id": "6f92d1e9-00b6-4f8b-9645-faeab321e1cc" } }, "with_session_id": { "summary": "Anonymous session", "value": { "session_id": "5898b8d1-c250-4bb5-931b-8b9d0ee7b499" } } } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "description": "List of messages from the server.", "items": { "type": "string", "description": "Message from the server." } } } }, "example": { "messages": [ "view will be processed soon" ] } } } }, "422": { "description": "Validation Error" } } } }, "/v1/beacon/conversion": { "servers": [ { "url": "https://events.newtail-media.newtail.com.br", "description": "VTEX Ads events server." } ], "post": { "tags": [ "Ads events notification" ], "summary": "Track conversions", "description": "Track completed sales for conversion attribution. Send this event for every completed sale, regardless of whether an ad led to the purchase. Notifying all sales enables attribution within time windows after ad-impacted navigation and metrics such as assisted sales. Send one or more orders in a batch request.\r\n\r\n## PII hashing and normalization\r\n\r\nHash each personally identifiable information (PII) field listed in the following table with SHA-256 and send the resulting hexadecimal digest. Normalize each value as described in the following table before hashing. Hashes computed from non-normalized values will not match:\r\n\r\n| Field | Normalization before hashing |\r\n| --- | --- |\r\n| `email_hashed` | Lowercase and trim the email, removing extra whitespace. |\r\n| `phone_hashed` | Use E.164 format (for example, `+5511999999999`), with no masks or separators. |\r\n| `social_id_hashed` | Use CPF or CNPJ digits only, with no dots or dashes. |\r\n| `first_name_hashed` | Trim the name and remove double spaces. |\r\n| `last_name_hashed` | Trim the name and remove double spaces. |\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "channel", "publisher_id", "user_id", "session_id", "order_id", "email_hashed", "items", "created_at" ], "properties": { "channel": { "type": "string", "description": "Identifies the conversion channel (for example, `ecommerce`, `app`, or `physical_store`)." }, "brand": { "type": "string", "description": "Brand or site where the sale occurred. Required when the publisher operates more than one site." }, "publisher_id": { "type": "string", "description": "Publisher identification." }, "user_id": { "type": "string", "description": "User identification." }, "session_id": { "type": "string", "description": "Identification of the session in which the purchase was made, to help attribute the sale to ads." }, "order_id": { "type": "string", "description": "Order identification." }, "email_hashed": { "type": "string", "description": "Hashed user email identification." }, "items": { "type": "array", "description": "List of items purchased in the order.", "items": { "type": "object", "description": "Order item information", "required": [ "sku", "quantity", "price", "promotional_price" ], "properties": { "sku": { "type": "string", "description": "Product SKU identification." }, "quantity": { "type": "number", "description": "Quantity of product purchased.", "format": "double" }, "price": { "type": "number", "description": "Product 'from' price. Not multiplied by quantity.", "format": "double" }, "promotional_price": { "type": "number", "description": "Product 'for' price (discounted price). Not multiplied by quantity.", "format": "double" }, "seller_id": { "type": "string", "description": "Seller ID identification.", "nullable": true }, "product_id": { "type": "string", "description": "Unique product identification that includes the SKU." } } } }, "created_at": { "type": "string", "description": "Order creation date in ISO 8601 format in UTC (for example, `2026-01-01T09:20:00Z`)." }, "is_company": { "type": "boolean", "description": "Indicates if the sale was made to an individual or a company.", "default": false }, "gender": { "type": "string", "description": "Indicates customer's gender. F: female, M: male, O: other.", "enum": [ "F", "M", "O" ], "nullable": true }, "uf": { "type": "string", "description": "Indicates the state where the order was made." }, "city": { "type": "string", "description": "Indicates the name of the city where the customer bought." }, "phone_hashed": { "type": "string", "description": "Hashed user phone number identification." }, "social_id_hashed": { "type": "string", "description": "Hashed user identification document, such as social ID, CPF, or CNPJ." }, "first_name_hashed": { "type": "string", "description": "Hashed user first name identification." }, "last_name_hashed": { "type": "string", "description": "Hashed user last name identification." } } }, "example": { "publisher_id": "xxx", "user_id": "6f92d1e9-00b6-4f8b-9645-faeab321e1cc", "session_id": "5898b8d1-c250-4bb5-931b-8b9d0ee7b499", "order_id": "123", "email_hashed": "xyz", "items": [ { "sku": "12221", "quantity": 1, "price": 2000, "promotional_price": 1899, "seller_id": "1234", "product_id": "4567" }, { "sku": "12222", "quantity": 2, "price": 1500, "promotional_price": 1200, "seller_id": "1234", "product_id": "4568" } ], "created_at": "2026-01-01T09:20:00Z", "channel": "ecommerce", "is_company": false, "gender": "M", "uf": "SP", "city": "São Paulo", "phone_hashed": "abc123", "social_id_hashed": "def456", "first_name_hashed": "ghi789", "last_name_hashed": "jkl012" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "description": "List of messages from the server.", "items": { "type": "string", "description": "Message from the server." } } } }, "example": { "messages": [ "conversion will be processed soon" ] } } } }, "422": { "description": "Validation Error" } } } }, "/v1/rma/{publisher_id}": { "servers": [ { "url": "https://newtail-media.newtail.com.br", "description": "VTEX Ads server." } ], "post": { "tags": [ "Ads" ], "summary": "Get ads", "description": "Retrieve Product and Banner ad formats based on context and placements.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).\r\n\r\n## Request best practices\r\n\r\n- **HTTP persistence:** Prefer persistent connections (`Connection: keep-alive`).\r\n- **Timeout:** Apply a 500-600 ms timeout to the ad query.\r\n\r\n## Context-specific fields\r\n\r\nThe `context` value determines which additional fields are required in the request body. The example below uses the `search` context — adapt it to your context using the table below. Include only the fields listed for your context (in addition to the common required fields `session_id`, `context`, `channel`, and `placements`).\r\n\r\n| `context` | Additional required fields | Notes |\r\n| --- | --- | --- |\r\n| `home` | None | Use generic placements (top banner, home shelf). |\r\n| `category` | `category_name` | Provide the full breadcrumb path (for example, `Daily Care > Deodorant > Spray`). |\r\n| `search` | `term` | Send the search query. Optionally pass `tags` to scope eligible ads. |\r\n| `product_page` | `product_sku` | SKU of the product currently being viewed. |\r\n| `brand_page` | `brand_name` | Name of the brand. Pair with `sponsored_brand` placements when applicable. |\r\n| `digital_signage` | `device_id`, `store_name` | Use `digital_signage` placements and the `app` channel. |", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "publisher_id", "in": "path", "description": "Publisher identifier provided by your account manager", "required": true, "schema": { "type": "string", "example": "0d675bf6-03f6-4b81-9617-e79dffddc3ab" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "context", "placements", "channel" ], "properties": { "session_id": { "type": "string", "description": "Persistent visitor identifier (at least 14 days). Must contain only alphanumeric characters.", "example": "f361661f5986477990092a34562f18347" }, "user_id": { "type": "string", "description": "Unique identifier for the user. Must contain only alphanumeric characters.", "example": "6a746448cf5942bcaa3da426844ad115" }, "store_id": { "type": "string", "description": "Filters ads based on the store's inventory. If not provided, ads with any available inventory will be returned.", "example": "1" }, "context": { "type": "string", "description": "Context where the ad will be displayed.", "example": "search", "enum": [ "home", "category", "search", "product_page", "brand_page", "digital_signage" ] }, "term": { "type": "string", "description": "Search terms used for product searches. Required only in search context.", "example": "desodorante" }, "category_name": { "type": "string", "description": "Name of the category used for targeting. Always provide the full breadcrumb path of the current category. Required only in category context.", "example": "Daily Care > Deodorant > Spray" }, "product_sku": { "type": "string", "description": "SKU ID used for targeting. Required only in product context.", "example": "12345" }, "brand_name": { "type": "string", "description": "Name of the brand to filter products by. Required only in brand context.", "example": "Nivea" }, "placements": { "type": "object", "description": "Placements are used to query multiple ads for different site regions with their own configurations.", "additionalProperties": { "type": "object", "description": "Placement configuration.", "required": [ "quantity", "types" ], "properties": { "quantity": { "type": "integer", "description": "Number of ads to be returned.", "example": 3 }, "size": { "type": "string", "description": "Expected ad size. Important when a region has a predefined size and requires a media asset fitting that size. For images: `desktop` or `mobile`. For videos: `1080p`, `720p`, `480p`, `360p`, or `320p`. Required only when types include `banner` or `sponsored_brand`.", "example": "desktop" }, "types": { "type": "array", "description": "Types of ads that can be returned in this request.", "items": { "type": "string", "description": "Ad type.", "enum": [ "product", "banner", "sponsored_brand", "digital_signage" ] }, "example": [ "banner", "product" ] }, "assets_type": { "type": "array", "description": "Accepted media types. Only valid for `banner` and `sponsored_brand` types. Default: `[\"image\"]`.", "items": { "type": "string", "description": "Media type.", "enum": [ "image", "video" ] }, "example": [ "image" ] }, "allow_sku_duplications": { "type": "boolean", "description": "Allows the same SKU ads to appear multiple times in the same placement. Default=false.", "example": false } } } }, "product_attributes": { "type": "object", "description": "Additional product information. Used when catalog data is incomplete and these details need to be sent during ad queries.", "properties": { "category_name": { "type": "string", "description": "Product category.", "example": "Daily Care > Deodorant > Spray" }, "brand_name": { "type": "string", "description": "Product brand.", "example": "Dove" } } }, "channel": { "type": "string", "description": "Indicates the device type accessing the ad.", "example": "site", "enum": [ "site", "msite", "app" ] }, "device_id": { "type": "string", "description": "Unique device ID (screen, totem). Required only in digital_signage context.", "example": "screen identifier" }, "store_name": { "type": "string", "description": "Name of the store where the device is located. Required only in digital_signage context.", "example": "Downtown Store" }, "brand": { "type": "string", "description": "Publisher's site name. Required when the publisher has multiple sites.", "example": "MyStore" }, "userAgent": { "type": "string", "description": "Client environment identification (body field, not the HTTP User-Agent header). Provides meta-information about the client environment accessing the ad.", "example": "App/1.0 (Pixel 6; Android 12.0)" }, "tags": { "type": "array", "description": "Tags to contextualize searches (primarily for search context). Filters ads that contain at least one of the requested tags. Max 10 per SKU, 64 chars per tag. Only works with product campaigns.", "items": { "type": "string", "description": "Tag name.", "maxLength": 64 }, "maxItems": 10, "example": [ "Mega Maio" ] }, "skus": { "type": "array", "description": "SKU filter for querying sponsored products. Note: Only sponsored product campaigns respect this filter.", "items": { "type": "string", "description": "Product SKU." }, "example": [ "12345", "67890" ] }, "dedup_campaign_ads": { "type": "boolean", "description": "Specifies whether results should be deduplicated by campaign, so at most one ad per campaign is returned. Default=false.", "example": false }, "dedup_ads": { "type": "boolean", "description": "Specifies whether results should deduplicate ads across multiple placements (use only when querying multiple placements simultaneously). Default=false.", "example": false }, "segmentation": { "type": "array", "description": "Allows campaign segmentation based on user information.", "items": { "type": "object", "description": "Segmentation rule.", "required": [ "key", "values" ], "properties": { "key": { "type": "string", "description": "Type of segmentation.", "enum": [ "AGE", "GENDER", "STATE", "CITY", "AUDIENCES", "NBO_CATEGORIES" ], "example": "STATE" }, "values": { "type": "array", "description": "One or more accepted values.", "items": { "type": "string", "description": "Segmentation value." }, "minItems": 1, "example": [ "RJ" ] } } } } } }, "example": { "session_id": "f361661f5986477990092a34562f18347", "user_id": "6a746448cf5942bcaa3da426844ad115", "context": "search", "channel": "site", "term": "desodorante", "placements": { "searchTopBanner": { "quantity": 1, "size": "desktop", "types": [ "banner" ], "assets_type": [ "image" ] }, "searchShelf": { "quantity": 3, "types": [ "product" ] } }, "tags": [ "Mega Maio" ] } } } }, "responses": { "200": { "description": "OK\n\nQuery processed successfully.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "description": "List of ads for a specific placement.", "items": { "type": "object", "description": "Ad object.", "properties": { "ad_id": { "type": "string", "description": "Unique identifier of the ad." }, "media_url": { "type": "string", "description": "URL of the image or video to be displayed. Present for banner, sponsored_brand, and digital_signage ad types." }, "type": { "type": "string", "description": "Type of ad.", "enum": [ "banner", "product", "sponsored_brand", "digital_signage" ] }, "seller_id": { "type": "string", "description": "Identifier of the seller.", "nullable": true }, "click_url": { "type": "string", "description": "URL of the click event beacon for the ad." }, "impression_url": { "type": "string", "description": "URL of the impression event beacon for the ad." }, "view_url": { "type": "string", "description": "URL of the view event beacon for the ad." }, "product_sku": { "type": "string", "description": "Product identifier. Present when ad type is 'product'." }, "products": { "type": "array", "description": "Array of products associated with the sponsored brand. Present when ad type is 'sponsored_brand'.", "items": { "type": "object", "description": "Product associated with the sponsored brand.", "properties": { "product_sku": { "type": "string", "description": "SKU of the associated product." }, "media_url": { "type": "string", "description": "URL of the product image." } } } }, "duration": { "type": "number", "description": "Duration of the ad display in seconds. Present when ad type is 'digital_signage'.", "format": "double" } } } } }, "example": { "placementName1": [ { "ad_id": "6d2d8837-bf5a-4ba4-90d2-5546cb18d5ce", "media_url": "https://cdn.newtail.com.br/retail_media/ads/2023/05/03/f97a938660e56fe38a9c9ade21c27df8-1280x256-red.png", "type": "banner", "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", "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", "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" } ], "placementName2": [ { "ad_id": "846fbf5e-6980-4a5e-a4a1-9b2a2dcbafb7", "product_sku": "10001236", "type": "product", "click_url": "https://events.newtail-media.newtail.com.br/v1/beacon/click/846fbf5e-6980-4a5e-a4a1-9b2a2dcbafb7?publisher_id=0d675bf6-03f6-4b81-9617-e79dffddc3ab&ad_type=product", "impression_url": "https://events.newtail-media.newtail.com.br/v1/beacon/impression/846fbf5e-6980-4a5e-a4a1-9b2a2dcbafb7?publisher_id=0d675bf6-03f6-4b81-9617-e79dffddc3ab&ad_type=product", "view_url": "https://events.newtail-media.newtail.com.br/v1/beacon/view/846fbf5e-6980-4a5e-a4a1-9b2a2dcbafb7?publisher_id=0d675bf6-03f6-4b81-9617-e79dffddc3ab&ad_type=product" } ] } } } }, "400": { "description": "Bad Request\n\nInvalid request." }, "404": { "description": "Not Found\n\nResource not found." }, "422": { "description": "Unprocessable Entity\n\nField validation error." }, "429": { "description": "Too Many Requests\n\nRate limit exceeded." } } } }, "/report/v2/advertisers": { "servers": [ { "url": "https://api-retail-media.newtail.com.br", "description": "VTEX Ads server." } ], "get": { "tags": [ "Reports" ], "summary": "Get advertisers report", "description": "Retrieves information from all advertisers associated with a publisher account. The data is returned in JSON format by default, but can be exported as an XLSX file by setting `download=true`.\r\n\r\n>ℹ️ Only available in the publisher view (publisher account).\r\n\r\n>⚠️ This endpoint is limited to 100 requests per minute per account. Exceeding the limit returns `429 Too Many Requests`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "$ref": "#/components/parameters/AccountInfo" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Quantity" }, { "$ref": "#/components/parameters/Count" }, { "$ref": "#/components/parameters/Download" } ], "responses": { "200": { "description": "OK\n\nReport returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of advertisers available." }, "pages": { "type": "integer", "description": "Total number of pages for pagination." }, "currentPage": { "type": "integer", "description": "Current page number." }, "data": { "type": "array", "description": "Array of advertiser objects.", "items": { "type": "object", "description": "Advertiser object.", "properties": { "id": { "type": "string", "description": "Unique advertiser identifier." }, "name": { "type": "string", "description": "Advertiser name." }, "account_id": { "type": "string", "description": "Account identifier." }, "checking_account_id": { "type": "string", "description": "Checking account identifier." }, "seller_id": { "type": "string", "description": "Seller identifier (when applicable).", "nullable": true }, "advertiser_tags": { "type": "array", "description": "Tags associated with the advertiser.", "nullable": true, "items": { "type": "string", "description": "Advertiser tag." } }, "metrics": { "type": "object", "description": "Performance metrics object. All metric values are returned as strings regardless of their numeric nature.", "properties": { "total_campaigns": { "type": "string", "description": "Total number of campaigns." }, "total_daily_budget": { "type": "string", "description": "Total daily budget amount." }, "balance": { "type": "string", "description": "Account balance." }, "advertiser_id": { "type": "string", "description": "Advertiser identifier." }, "impressions": { "type": "string", "description": "Total number of ad impressions." }, "views": { "type": "string", "description": "Total number of ad views." }, "clicks": { "type": "string", "description": "Total number of ad clicks." }, "conversions": { "type": "string", "description": "Total number of conversions." }, "conversions_click": { "type": "string", "description": "Total number of ad-driven conversions attributed to a click." }, "conversion_rate": { "type": "string", "description": "Conversion rate percentage." }, "conversion_rate_click": { "type": "string", "description": "Click-attributed conversion rate percentage, calculated as `conversions_click / clicks`." }, "total_conversions_items_quantity": { "type": "string", "description": "Total quantity of items across all ad-driven conversions. Sums the quantities of every item in each conversion event (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 2)." }, "total_conversions_items_quantity_click": { "type": "string", "description": "Total quantity of items across all click-attributed conversions. Sums the quantities of every item in each click-attributed conversion event (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 2)." }, "ctr": { "type": "string", "description": "Click-through rate percentage." }, "income": { "type": "string", "description": "Total income generated." }, "income_click": { "type": "string", "description": "Total income generated from click-attributed conversions." }, "ecpm": { "type": "string", "description": "Effective cost per mille (CPM)." }, "total_spent": { "type": "string", "description": "Total amount spent." }, "cpa": { "type": "string", "description": "Cost per acquisition." }, "avg_cpc": { "type": "string", "description": "Average cost per click." }, "avg_cpm": { "type": "string", "description": "Average cost per mille." }, "conversions_quantity": { "type": "string", "description": "Total number of ad-driven conversions (sales attributed to an ad). Counts each conversion event as 1, regardless of how many items were purchased (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 1)." }, "roas": { "type": "string", "description": "Return on ad spend." }, "roas_click": { "type": "string", "description": "Return on ad spend calculated using click-attributed conversion value only (`income_click / total_spent`)." }, "click_roas": { "type": "string", "description": "Deprecated. Use `roas_click` instead, which returns the same value. This field is kept for backward compatibility and will be removed in a future version.", "deprecated": true }, "overall_roas": { "type": "string", "description": "Combined return on ad spend across direct and assisted conversions (`(income + assisted_income) / total_spent`)." }, "assisted_orders": { "type": "string", "description": "Number of orders that include at least one item purchased as a result of ad exposure, in addition to (or instead of) the directly clicked or viewed product. These are orders where the ad influenced the overall purchase beyond its direct conversion. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_items": { "type": "string", "description": "Total quantity of additional items sold that are credited to an ad's influence on a purchase, separate from the ad's direct conversions. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_income": { "type": "string", "description": "Total revenue generated from additional items purchased as a result of an ad's influence on a purchase, beyond the ad's direct conversions. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_roas": { "type": "string", "description": "Return on ad spend calculated using assisted revenue only (assisted income divided by total ad spend), separate from the ad's direct-conversion ROAS. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "adcost": { "type": "string", "description": "Ad cost." }, "consumed_daily_budget": { "type": "string", "description": "Amount of daily budget consumed." } } }, "account_logo": { "type": "string", "description": "URL of the advertiser's logo." }, "account_theme": { "type": "object", "description": "Theme configuration object.", "properties": { "primary_color": { "type": "string", "description": "Primary color code (hex format)." }, "header_color": { "type": "string", "description": "Header color code (hex format)." }, "second_color": { "type": "string", "description": "Secondary color code (hex format)." }, "dark_color": { "type": "string", "description": "Dark color code (hex format)." } } } } } } } }, "example": { "total": 1, "pages": 1, "currentPage": 1, "data": [ { "id": "id", "name": "name", "account_id": "account-id", "checking_account_id": "checking-account-id", "seller_id": "1234", "advertiser_tags": ["premium"], "metrics": { "total_campaigns": "100", "total_daily_budget": "50000.00", "balance": "6756756.40", "advertiser_id": "advertiser-id", "impressions": "395696", "views": "323720", "clicks": "1237", "conversions": "0", "conversions_click": "0", "conversion_rate": "0.00", "conversion_rate_click": "0.00", "total_conversions_items_quantity": "0", "total_conversions_items_quantity_click": "0", "ctr": "0.31", "income": "0.0000", "income_click": "0.0000", "ecpm": "0.00", "total_spent": "213122.6000", "cpa": "0", "avg_cpc": "31.99", "avg_cpm": "100.00", "conversions_quantity": "0", "roas": "0.00", "roas_click": "0.00", "click_roas": "0.00", "overall_roas": "0.00", "assisted_orders": "0", "assisted_items": "0", "assisted_income": "0.0000", "assisted_roas": "0.00", "adcost": "0.0", "consumed_daily_budget": "4407.70" }, "account_logo": "https://cdn.newtail.com.br/accounts/4852asd4q-3b0a-11ef-b7a2-014ea2680b7e/assets/advertiser-logo.png", "account_theme": { "primary_color": "#00B941", "header_color": "#00B941", "second_color": "#00B941", "dark_color": "#00B941" } } ] } } } }, "401": { "description": "Unauthorized\n\nMissing or invalid authentication credentials." }, "429": { "description": "Too Many Requests\n\nThis endpoint is limited to 100 requests per minute per account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Rate limit error message." } } }, "example": { "error": "Rate limit exceeded for this account" } } } } } } }, "/report/v2/publishers": { "servers": [ { "url": "https://api-retail-media.newtail.com.br", "description": "VTEX Ads server." } ], "get": { "tags": [ "Reports" ], "summary": "Get publishers report", "description": "Retrieves information about the publishers associated with an advertiser account. The data is returned in JSON format by default, but can be exported as an XLSX file by setting `download=true`.\r\n\r\n>ℹ️ Only available in the advertiser view (advertiser account).\r\n\r\n>⚠️ This endpoint is limited to 100 requests per minute per account. Exceeding the limit returns `429 Too Many Requests`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "name": "publisher_name", "in": "query", "description": "Filters results by publisher name.", "required": false, "schema": { "type": "string", "example": "MyStore" } }, { "$ref": "#/components/parameters/AccountInfo" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Quantity" }, { "$ref": "#/components/parameters/Count" }, { "name": "order_by", "in": "query", "description": "Field used to sort results.", "required": false, "schema": { "type": "string", "enum": [ "name", "balance", "total_daily_budget", "total_campaigns", "impressions", "clicks", "ctr", "total_spent", "conversions", "conversion_rate", "income", "roas" ], "example": "income" } }, { "$ref": "#/components/parameters/OrderDirection" }, { "$ref": "#/components/parameters/Download" } ], "responses": { "200": { "description": "OK\n\nReport returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of publishers available." }, "pages": { "type": "integer", "description": "Total number of pages for pagination." }, "currentPage": { "type": "integer", "description": "Current page number." }, "data": { "type": "array", "description": "Array of publisher objects.", "items": { "type": "object", "description": "Publisher object.", "properties": { "id": { "type": "string", "description": "Unique publisher identifier." }, "name": { "type": "string", "description": "Publisher name." }, "account_id": { "type": "string", "description": "Account identifier." }, "checking_account_id": { "type": "string", "description": "Checking account identifier." }, "metrics": { "type": "object", "description": "Performance metrics object. All metric values are returned as strings regardless of their numeric nature.", "properties": { "total_campaigns": { "type": "string", "description": "Total number of campaigns." }, "total_daily_budget": { "type": "string", "description": "Total daily budget amount." }, "balance": { "type": "string", "description": "Account balance." }, "publisher_id": { "type": "string", "description": "Publisher identifier." }, "impressions": { "type": "string", "description": "Total number of ad impressions." }, "views": { "type": "string", "description": "Total number of ad views." }, "clicks": { "type": "string", "description": "Total number of ad clicks." }, "conversions": { "type": "string", "description": "Total number of conversions." }, "conversions_click": { "type": "string", "description": "Total number of ad-driven conversions attributed to a click." }, "conversion_rate": { "type": "string", "description": "Conversion rate percentage." }, "conversion_rate_click": { "type": "string", "description": "Click-attributed conversion rate percentage, calculated as `conversions_click / clicks`." }, "total_conversions_items_quantity": { "type": "string", "description": "Total quantity of items across all ad-driven conversions. Sums the quantities of every item in each conversion event (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 2)." }, "total_conversions_items_quantity_click": { "type": "string", "description": "Total quantity of items across all click-attributed conversions. Sums the quantities of every item in each click-attributed conversion event (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 2)." }, "ctr": { "type": "string", "description": "Click-through rate percentage." }, "impression_share": { "type": "string", "description": "Impression share (IS): percentage of eligible auction opportunities the advertiser's campaigns won on this publisher, out of the estimated total. This field, `lost_is_rank`, and `lost_is_budget` add up to approximately 100%. `0` means the advertiser's campaigns received no impressions on this publisher in the selected period. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "lost_is_rank": { "type": "string", "description": "Lost impression share by rank: percentage of eligible auction opportunities the advertiser's campaigns lost on this publisher due to a bid or ad rank below the competition. `0` means the advertiser's campaigns contested every eligible auction with no rank-related loss. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "lost_is_budget": { "type": "string", "description": "Lost impression share by budget: percentage of eligible auction opportunities the advertiser's campaigns lost on this publisher due to insufficient budget to compete. `0` means the advertiser's campaigns contested every eligible auction with no budget-related loss. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "income": { "type": "string", "description": "Total income generated." }, "income_click": { "type": "string", "description": "Total income generated from click-attributed conversions." }, "ecpm": { "type": "string", "description": "Effective cost per mille (CPM)." }, "total_spent": { "type": "string", "description": "Total amount spent." }, "cpa": { "type": "string", "description": "Cost per acquisition." }, "avg_cpc": { "type": "string", "description": "Average cost per click." }, "avg_cpm": { "type": "string", "description": "Average cost per mille." }, "conversions_quantity": { "type": "string", "description": "Total number of ad-driven conversions (sales attributed to an ad). Counts each conversion event as 1, regardless of how many items were purchased (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 1)." }, "roas": { "type": "string", "description": "Return on ad spend." }, "roas_click": { "type": "string", "description": "Return on ad spend calculated using click-attributed conversion value only (`income_click / total_spent`)." }, "click_roas": { "type": "string", "description": "Deprecated. Use `roas_click` instead, which returns the same value. This field is kept for backward compatibility and will be removed in a future version.", "deprecated": true }, "overall_roas": { "type": "string", "description": "Combined return on ad spend across direct and assisted conversions (`(income + assisted_income) / total_spent`)." }, "assisted_orders": { "type": "string", "description": "Number of orders that include at least one item purchased as a result of ad exposure, in addition to (or instead of) the directly clicked or viewed product. These are orders where the ad influenced the overall purchase beyond its direct conversion. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_items": { "type": "string", "description": "Total quantity of additional items sold that are credited to an ad's influence on a purchase, separate from the ad's direct conversions. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_income": { "type": "string", "description": "Total revenue generated from additional items purchased as a result of an ad's influence on a purchase, beyond the ad's direct conversions. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_roas": { "type": "string", "description": "Return on ad spend calculated using assisted revenue only (assisted income divided by total ad spend), separate from the ad's direct-conversion ROAS. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "adcost": { "type": "string", "description": "Ad cost." } } }, "account_logo": { "type": "string", "description": "URL of the publisher's logo." }, "account_theme": { "type": "object", "description": "Theme configuration object.", "properties": { "primary_color": { "type": "string", "description": "Primary color code (hex format)." }, "header_color": { "type": "string", "description": "Header color code (hex format)." }, "second_color": { "type": "string", "description": "Secondary color code (hex format)." }, "dark_color": { "type": "string", "description": "Dark color code (hex format)." } } } } } } } }, "example": { "total": 1, "pages": 1, "currentPage": 1, "data": [ { "id": "publisher-id", "name": "publisher-name", "account_id": "publisher-account-name", "checking_account_id": "checking-account-id", "metrics": { "total_campaigns": "560", "total_daily_budget": "00999.00", "balance": "60001.29", "publisher_id": "publisher-id", "impressions": "999999", "views": "0", "clicks": "4954", "conversions": "214", "conversions_click": "214", "conversion_rate": "4.32", "conversion_rate_click": "4.32", "total_conversions_items_quantity": "214", "total_conversions_items_quantity_click": "214", "ctr": "0.09", "impression_share": "62.40", "lost_is_rank": "21.10", "lost_is_budget": "16.50", "income": "581620.1500", "income_click": "581620.1500", "ecpm": "0.11", "total_spent": "1340.4000", "cpa": "6.26", "avg_cpc": "0.27", "avg_cpm": "0.25", "conversions_quantity": "214", "roas": "433.92", "roas_click": "433.92", "click_roas": "433.92", "overall_roas": "471.22", "assisted_orders": "18", "assisted_items": "25", "assisted_income": "50000.0000", "assisted_roas": "37.30", "adcost": "0.23" }, "account_logo": "https://cdn.newtail.com.br/accounts/4852asd4q-3b0a-11ef-b7a2-014ea2680b7e/assets/publisher-logo.png", "account_theme": { "primary_color": "#00B941", "header_color": "#00B941", "second_color": "#00B941", "dark_color": "#00B941" } } ] } } } }, "401": { "description": "Unauthorized\n\nMissing or invalid authentication credentials." }, "429": { "description": "Too Many Requests\n\nThis endpoint is limited to 100 requests per minute per account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Rate limit error message." } } }, "example": { "error": "Rate limit exceeded for this account" } } } } } } }, "/report/network/publishers": { "servers": [ { "url": "https://api-retail-media.newtail.com.br", "description": "VTEX Ads server." } ], "get": { "tags": [ "Reports" ], "summary": "Get network publishers report", "description": "Retrieves information about publishers associated with a Network Publisher account. The data is returned in JSON format by default, but can be exported as an XLSX file by setting `download=true`.\r\n\r\n>ℹ️ Only publishers operating in the Network format are allowed to access this report.\r\n\r\n>⚠️ This endpoint is limited to 100 requests per minute per account. Exceeding the limit returns `429 Too Many Requests`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "name": "publisher_name", "in": "query", "description": "Filters results by publisher name.", "required": false, "schema": { "type": "string", "example": "MyStore" } }, { "$ref": "#/components/parameters/AccountInfo" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Quantity" }, { "$ref": "#/components/parameters/Count" }, { "name": "order_by", "in": "query", "description": "Field used to sort results.", "required": false, "schema": { "type": "string", "enum": [ "name", "impressions", "clicks", "ctr", "conversions", "conversion_rate", "income", "roas", "requests" ], "example": "impressions" } }, { "$ref": "#/components/parameters/OrderDirection" }, { "$ref": "#/components/parameters/Download" } ], "responses": { "200": { "description": "OK\n\nReport returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of network publishers available." }, "pages": { "type": "integer", "description": "Total number of pages for pagination." }, "currentPage": { "type": "integer", "description": "Current page number." }, "data": { "type": "array", "description": "Array of network publisher objects.", "items": { "type": "object", "description": "Network publisher object.", "properties": { "id": { "type": "string", "description": "Unique network publisher identifier." }, "name": { "type": "string", "description": "Publisher name." }, "account_id": { "type": "string", "description": "Account identifier." }, "metrics": { "type": "object", "description": "Performance metrics object. All metric values are returned as strings regardless of their numeric nature.", "properties": { "publisher_id": { "type": "string", "description": "Publisher identifier." }, "impressions": { "type": "string", "description": "Total number of ad impressions." }, "views": { "type": "string", "description": "Total number of ad views." }, "clicks": { "type": "string", "description": "Total number of ad clicks." }, "conversions": { "type": "string", "description": "Total number of conversions." }, "conversions_click": { "type": "string", "description": "Total number of ad-driven conversions attributed to a click." }, "conversion_rate": { "type": "string", "description": "Conversion rate percentage." }, "conversion_rate_click": { "type": "string", "description": "Click-attributed conversion rate percentage, calculated as `conversions_click / clicks`." }, "total_conversions_items_quantity": { "type": "string", "description": "Total quantity of items across all ad-driven conversions. Sums the quantities of every item in each conversion event (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 2)." }, "total_conversions_items_quantity_click": { "type": "string", "description": "Total quantity of items across all click-attributed conversions. Sums the quantities of every item in each click-attributed conversion event (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 2)." }, "ctr": { "type": "string", "description": "Click-through rate percentage." }, "income": { "type": "string", "description": "Total income generated." }, "income_click": { "type": "string", "description": "Total income generated from click-attributed conversions." }, "ecpm": { "type": "string", "description": "Effective cost per mille (CPM)." }, "total_spent": { "type": "string", "description": "Total amount spent." }, "cpa": { "type": "string", "description": "Cost per acquisition." }, "avg_cpc": { "type": "string", "description": "Average cost per click." }, "avg_cpm": { "type": "string", "description": "Average cost per mille." }, "conversions_quantity": { "type": "string", "description": "Total number of ad-driven conversions (sales attributed to an ad). Counts each conversion event as 1, regardless of how many items were purchased (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 1)." }, "roas": { "type": "string", "description": "Return on ad spend." }, "roas_click": { "type": "string", "description": "Return on ad spend calculated using click-attributed conversion value only (`income_click / total_spent`)." }, "click_roas": { "type": "string", "description": "Deprecated. Use `roas_click` instead, which returns the same value. This field is kept for backward compatibility and will be removed in a future version.", "deprecated": true }, "overall_roas": { "type": "string", "description": "Combined return on ad spend across direct and assisted conversions (`(income + assisted_income) / total_spent`)." }, "assisted_orders": { "type": "string", "description": "Number of orders that include at least one item purchased as a result of ad exposure, in addition to (or instead of) the directly clicked or viewed product. These are orders where the ad influenced the overall purchase beyond its direct conversion. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_items": { "type": "string", "description": "Total quantity of additional items sold that are credited to an ad's influence on a purchase, separate from the ad's direct conversions. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_income": { "type": "string", "description": "Total revenue generated from additional items purchased as a result of an ad's influence on a purchase, beyond the ad's direct conversions. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_roas": { "type": "string", "description": "Return on ad spend calculated using assisted revenue only (assisted income divided by total ad spend), separate from the ad's direct-conversion ROAS. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "adcost": { "type": "string", "description": "Ad cost." }, "requests": { "type": "string", "description": "Total number of ad requests." } } }, "account_logo": { "type": "string", "description": "URL of the publisher's logo." }, "account_theme": { "type": "object", "description": "Theme configuration object.", "properties": { "primary_color": { "type": "string", "description": "Primary color code (hex format)." }, "header_color": { "type": "string", "description": "Header color code (hex format)." }, "second_color": { "type": "string", "description": "Secondary color code (hex format)." }, "dark_color": { "type": "string", "description": "Dark color code (hex format)." } } } } } } } }, "example": { "total": 1, "pages": 1, "currentPage": 1, "data": [ { "id": "publisher-id", "name": "publisher-name", "account_id": "publisher-account-name", "metrics": { "publisher_id": "publisher-id", "impressions": "0", "views": "0", "clicks": "0", "conversions": "0", "conversions_click": "0", "conversion_rate": "0", "conversion_rate_click": "0", "total_conversions_items_quantity": "0", "total_conversions_items_quantity_click": "0", "ctr": "0", "income": "0.00", "income_click": "0.00", "ecpm": "0", "total_spent": "0.0000", "cpa": "0", "avg_cpc": "0", "avg_cpm": "0", "conversions_quantity": "0", "roas": "0.0", "roas_click": "0.0", "click_roas": "0.0", "overall_roas": "0.0", "assisted_orders": "0", "assisted_items": "0", "assisted_income": "0.00", "assisted_roas": "0.0", "adcost": "0.0", "requests": "1" }, "account_logo": "https://cdn.newtail.com.br/accounts/4852asd4q-3b0a-11ef-b7a2-014ea2680b7e/assets/publisher-logo.png", "account_theme": { "primary_color": "#00B941", "header_color": "#00B941", "second_color": "#00B941", "dark_color": "#00B941" } } ] } } } }, "401": { "description": "Unauthorized\n\nMissing or invalid authentication credentials." }, "429": { "description": "Too Many Requests\n\nThis endpoint is limited to 100 requests per minute per account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Rate limit error message." } } }, "example": { "error": "Rate limit exceeded for this account" } } } } } } }, "/report/publisher/hour": { "servers": [ { "url": "https://api-retail-media.newtail.com.br", "description": "VTEX Ads server." } ], "get": { "tags": [ "Reports" ], "summary": "Get publisher hourly report", "description": "Retrieves hourly performance metrics for the publisher on a single date and, optionally, on a second date to compare against.\r\n\r\nThe publisher is always resolved from the authenticated account. This endpoint takes no path parameter and no `publisher_id` query parameter, and it ignores `publisher_id` when sent in the query string. This is the same account resolution model used by `GET` [Get network publishers report](https://developers.vtex.com/docs/api-reference/vtex-ads-api#get-/report/network/publishers). Unlike that report, this endpoint is not restricted to accounts operating in the Network format. It behaves the same way for Network format accounts and regular publisher accounts.\r\n\r\nThis endpoint is not paginated and accepts no `page`, `quantity`, `count`, `order_by`, or `order_direction` parameters. The response is capped at 48 rows: up to 24 hourly rows for `date`, plus up to 24 more rows when `compare_date` is sent. Rows are always ordered by `date` and then `hour`, in ascending order.\r\n\r\n>ℹ️ The `date` and `hour` values in the response are already localized to the publisher's time zone. Do not convert them.\r\n\r\n>⚠️ This endpoint is limited to 100 requests per minute per account. Exceeding the limit returns `429 Too Many Requests`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "date", "in": "query", "description": "Date for hourly metrics in `YYYY-MM-DD` format. This parameter is required. If it is missing or malformed, the request returns `422 Unprocessable Entity`.", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-09-08" } }, { "name": "compare_date", "in": "query", "description": "Second date to compare against `date`, in `YYYY-MM-DD` format. Use it to compare two periods, such as the current date and the same weekday of the previous week. This date must be a different date from `date`. Otherwise, the request returns `422 Unprocessable Entity`. If this parameter is omitted, the response contains rows for `date` only.", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-01" } } ], "responses": { "200": { "description": "OK\n\nReport returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Array of hourly metrics rows, ordered by `date` and then `hour`, in ascending order. It contains up to 24 rows for `date`, plus up to 24 more rows when `compare_date` is sent, for a maximum of 48 rows.", "items": { "type": "object", "description": "Hourly metrics row.", "properties": { "date": { "type": "string", "format": "date", "description": "Date covered by the metrics row, in `YYYY-MM-DD` format. This value is already localized to the publisher's time zone, so no conversion is needed." }, "hour": { "type": "integer", "minimum": 0, "maximum": 23, "description": "Hour of the day covered by the metrics row, from `0` to `23`. This value is already localized to the publisher's time zone, so no conversion is needed." }, "metrics": { "type": "object", "description": "Performance metrics object. Values cover only the `date` and `hour` of the row. All metric values are returned as strings regardless of their numeric nature.", "properties": { "impressions": { "type": "string", "description": "Total number of ad impressions." }, "views": { "type": "string", "description": "Total number of ad views." }, "clicks": { "type": "string", "description": "Total number of ad clicks." }, "conversions": { "type": "string", "description": "Total number of conversions." }, "conversions_click": { "type": "string", "nullable": true, "description": "Total number of ad-driven conversions attributed to a click. Returns `null` when click attribution is not available for the hour." }, "conversion_rate": { "type": "string", "description": "Conversion rate percentage." }, "conversion_rate_click": { "type": "string", "nullable": true, "description": "Click-attributed conversion rate percentage, calculated as `conversions_click / clicks`. Returns `null` when click attribution is not available for the hour." }, "total_conversions_items_quantity": { "type": "string", "description": "Total quantity of items across all ad-driven conversions. Sums the quantities of every item in each conversion event (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 2)." }, "total_conversions_items_quantity_click": { "type": "string", "nullable": true, "description": "Total quantity of items across all click-attributed conversions. Sums the quantities of every item in each click-attributed conversion event (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 2). Returns `null` when click attribution is not available for the hour." }, "ctr": { "type": "string", "description": "Click-through rate percentage." }, "income": { "type": "string", "description": "Total income generated." }, "income_click": { "type": "string", "nullable": true, "description": "Total income generated from click-attributed conversions. Returns `null` when click attribution is not available for the hour." }, "ecpm": { "type": "string", "description": "Effective cost per mille (CPM)." }, "total_spent": { "type": "string", "description": "Total amount spent." }, "cpa": { "type": "string", "description": "Cost per acquisition." }, "avg_cpc": { "type": "string", "description": "Average cost per click." }, "avg_cpm": { "type": "string", "description": "Average cost per mille." }, "conversions_quantity": { "type": "string", "description": "Total number of ad-driven conversions (sales attributed to an ad). Counts each conversion event as 1, regardless of how many items were purchased (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 1)." }, "roas": { "type": "string", "description": "Return on ad spend." }, "roas_click": { "type": "string", "nullable": true, "description": "Return on ad spend calculated using click-attributed conversion value only (`income_click / total_spent`). Returns `null` when click attribution is not available for the hour." }, "adcost": { "type": "string", "description": "Ad cost." } } } } } }, "metricsColumns": { "type": "object", "description": "Type information for the metrics returned in `data`, keyed by metric name. Each entry has a `type` field whose value is a metric type, such as `integer`, `percent`, or `money`. This object may not include every metric returned in `data`." } } }, "example": { "data": [ { "date": "2026-09-01", "hour": 0, "metrics": { "impressions": "1120471", "views": "139888", "clicks": "1578", "conversions": "45", "conversions_click": "7", "conversion_rate": "0.03", "conversion_rate_click": "0.44", "total_conversions_items_quantity": "46", "total_conversions_items_quantity_click": "8", "ctr": "0.14", "income": "58437.41", "income_click": "4610.0100", "ecpm": "0.05", "total_spent": "1209.13418000", "cpa": "26.29", "avg_cpc": "0.77", "avg_cpm": "1.08", "conversions_quantity": "46", "roas": "48.33", "adcost": "2.07", "roas_click": "3.81" } }, { "date": "2026-09-01", "hour": 1, "metrics": { "impressions": "1061675", "views": "122341", "clicks": "1046", "conversions": "22", "conversions_click": "7", "conversion_rate": "0.02", "conversion_rate_click": "0.67", "total_conversions_items_quantity": "22", "total_conversions_items_quantity_click": "7", "ctr": "0.10", "income": "20369.11", "income_click": "4782.8900", "ecpm": "0.02", "total_spent": "861.39154000", "cpa": "39.15", "avg_cpc": "0.82", "avg_cpm": "0.81", "conversions_quantity": "22", "roas": "23.65", "adcost": "4.23", "roas_click": "5.55" } }, { "date": "2026-09-01", "hour": 2, "metrics": { "impressions": "835349", "views": "81169", "clicks": "692", "conversions": "36", "conversions_click": "6", "conversion_rate": "0.04", "conversion_rate_click": "0.87", "total_conversions_items_quantity": "36", "total_conversions_items_quantity_click": "6", "ctr": "0.08", "income": "23577.10", "income_click": "1483.1000", "ecpm": "0.03", "total_spent": "613.10489000", "cpa": "17.03", "avg_cpc": "0.89", "avg_cpm": "0.73", "conversions_quantity": "36", "roas": "38.46", "adcost": "2.60", "roas_click": "2.42" } }, { "date": "2026-09-08", "hour": 0, "metrics": { "impressions": "653032", "views": "136902", "clicks": "1561", "conversions": "65", "conversions_click": "25", "conversion_rate": "0.05", "conversion_rate_click": "1.60", "total_conversions_items_quantity": "67", "total_conversions_items_quantity_click": "27", "ctr": "0.24", "income": "56963.86", "income_click": "7489.0500", "ecpm": "0.09", "total_spent": "1085.92282000", "cpa": "16.21", "avg_cpc": "0.70", "avg_cpm": "1.66", "conversions_quantity": "67", "roas": "52.46", "adcost": "1.91", "roas_click": "6.90" } } ], "metricsColumns": { "impressions": { "type": "integer" }, "views": { "type": "integer" }, "clicks": { "type": "integer" }, "ctr": { "type": "percent" }, "conversions": { "type": "integer" }, "conversions_click": { "type": "integer" }, "conversion_rate": { "type": "percent" }, "conversion_rate_click": { "type": "percent" }, "income": { "type": "money" }, "ecpm": { "type": "money" }, "roas": { "type": "money" }, "adcost": { "type": "percent" }, "total_spent": { "type": "money" } } } } } }, "401": { "description": "Unauthorized\n\nMissing or invalid authentication credentials." }, "422": { "description": "Unprocessable Entity\n\nField validation error." }, "429": { "description": "Too Many Requests\n\nThis endpoint is limited to 100 requests per minute per account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Rate limit error message." } } }, "example": { "error": "Rate limit exceeded for this account" } } } } } } }, "/campaign/v2": { "servers": [ { "url": "https://api-retail-media.newtail.com.br", "description": "VTEX Ads server." } ], "get": { "tags": [ "Reports" ], "summary": "List campaigns", "description": "Fetches all available campaigns, applying filters as needed. The data is returned in JSON format by default, but can be exported as an XLSX file by setting `download=true`.\r\n\r\n>⚠️ This endpoint is limited to 100 requests per minute per account. Exceeding the limit returns `429 Too Many Requests`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "name": "status", "in": "query", "description": "Filters by campaign status.", "required": false, "schema": { "type": "string", "example": "running" } }, { "name": "advertiser_id", "in": "query", "description": "Filters campaigns by advertiser ID.", "required": false, "schema": { "type": "string", "example": "advertiser-id" } }, { "name": "ad_type", "in": "query", "description": "Filters by ad type.", "required": false, "schema": { "type": "string", "enum": [ "banner", "product", "sponsored_brand", "digital_signage" ], "example": "product" } }, { "name": "name", "in": "query", "description": "Searches campaigns by name.", "required": false, "schema": { "type": "string", "example": "Holiday Sale" } }, { "$ref": "#/components/parameters/AccountInfo" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Quantity" }, { "$ref": "#/components/parameters/Count" }, { "name": "order_by", "in": "query", "description": "Field used to sort results.", "required": false, "schema": { "type": "string", "enum": [ "name", "impressions", "clicks", "ctr", "conversions", "conversion_rate", "income", "roas", "created_at", "start_at", "daily_budget", "ad_type", "advertiser_name", "status" ], "example": "created_at" } }, { "$ref": "#/components/parameters/OrderDirection" }, { "$ref": "#/components/parameters/Download" } ], "responses": { "200": { "description": "OK\n\nCampaigns returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of campaigns." }, "pages": { "type": "integer", "description": "Total number of pages for pagination." }, "currentPage": { "type": "integer", "description": "Current page number." }, "data": { "type": "array", "description": "Array of campaign objects.", "items": { "type": "object", "description": "Campaign object.", "properties": { "id": { "type": "string", "description": "Unique campaign identifier." }, "advertiser_id": { "type": "string", "description": "Advertiser identifier." }, "name": { "type": "string", "description": "Campaign name." }, "status": { "type": "string", "description": "Campaign status." }, "type": { "type": "string", "description": "Campaign type." }, "settings": { "type": "object", "description": "Campaign settings object. The fields are dynamic and may vary depending on the campaign type.", "properties": { "daily_budget": { "type": "number", "description": "Daily budget amount.", "format": "double" }, "cpc": { "type": "number", "description": "Cost per click value.", "format": "double" }, "cpm": { "type": "number", "description": "Cost per mille value.", "format": "double" }, "budget_type": { "type": "string", "description": "Budget distribution type." } } }, "start_at": { "type": "string", "description": "Campaign start date in ISO 8601 format." }, "end_at": { "type": "string", "description": "Campaign end date in ISO 8601 format." }, "disabled_at": { "type": "string", "description": "Campaign disabled date in ISO 8601 format.", "nullable": true }, "created_at": { "type": "string", "description": "Campaign creation date in ISO 8601 format." }, "updated_at": { "type": "string", "description": "Campaign last update date in ISO 8601 format." }, "deleted_at": { "type": "string", "description": "Campaign deletion date in ISO 8601 format.", "nullable": true }, "description": { "type": "string", "description": "Campaign description.", "nullable": true }, "publisher_id": { "type": "string", "description": "Publisher identifier." }, "ad_type": { "type": "string", "description": "Advertisement type." }, "cid": { "type": "integer", "description": "Campaign internal ID." }, "seller_id": { "type": "string", "description": "Seller identifier (when applicable).", "nullable": true }, "target": { "type": "string", "description": "Campaign target (when applicable)." }, "network_id": { "type": "string", "description": "Network identifier (when applicable).", "nullable": true }, "audience_id": { "type": "string", "description": "Audience identifier (when applicable).", "nullable": true }, "targeting_type": { "type": "string", "description": "Targeting type.", "nullable": true }, "strategy_type": { "type": "string", "description": "Campaign strategy type." }, "total_budget": { "type": "string", "description": "Total campaign budget." }, "active": { "type": "boolean", "description": "Whether the campaign is active." }, "advertiser_name": { "type": "string", "description": "Advertiser name." }, "advertiser_account_id": { "type": "string", "description": "Advertiser account identifier." }, "publisher_name": { "type": "string", "description": "Publisher name." }, "publisher_account_id": { "type": "string", "description": "Publisher account identifier." }, "consumed_budget": { "type": "string", "description": "Amount of budget consumed." }, "daily_budget": { "type": "string", "description": "Daily budget amount." }, "campaign_status": { "type": "integer", "description": "Campaign status code." }, "advertiser_tags": { "type": "array", "description": "Tags associated with the advertiser.", "nullable": true, "items": { "type": "string", "description": "Advertiser tag." } }, "pending": { "type": "array", "description": "Pending operations awaiting review for this campaign/ad. Empty when there is nothing pending.", "items": { "type": "object", "description": "Pending operation entry, grouping a `label` with its `quantity`.", "properties": { "label": { "type": "string", "description": "Type of pending operation. Currently, only `ads` is returned, indicating ads awaiting review.", "enum": [ "ads" ] }, "quantity": { "type": "integer", "description": "Number of pending items of the given `label`." } } } }, "metrics": { "type": "object", "description": "Performance metrics object. All metric values are returned as strings regardless of their numeric nature.", "properties": { "clicks": { "type": "integer", "description": "Total number of clicks." }, "conversions": { "type": "integer", "description": "Total number of conversions." }, "impressions": { "type": "integer", "description": "Total number of impressions." }, "views": { "type": "integer", "description": "Total number of views." }, "total_conversions_items_quantity_click": { "type": "string", "description": "Total quantity of items across all click-attributed conversions. Sums the quantities of every item in each click-attributed conversion event (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 2)." }, "conversions_click": { "type": "string", "description": "Total number of ad-driven conversions attributed to a click." }, "conversion_rate": { "type": "string", "description": "Consolidated conversion rate percentage, calculated as total conversions divided by the sum of clicks and views (`total_conversions / (total_clicks + total_views)`). This is the default conversion rate and considers both click- and view-attributed conversions." }, "conversion_rate_click": { "type": "string", "description": "Click-attributed conversion rate percentage, calculated as `conversions_click / clicks`." }, "ctr": { "type": "string", "description": "Click-through rate percentage." }, "impression_share": { "type": "string", "description": "Impression share (IS): percentage of eligible auction opportunities the campaign won, out of the estimated total (eligible auctions with available budget plus auctions lost due to insufficient budget). This field, `lost_is_rank`, and `lost_is_budget` add up to approximately 100%. `0` means the campaign received no impressions in the selected period. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "lost_is_rank": { "type": "string", "description": "Lost impression share by rank: percentage of eligible auction opportunities the campaign lost due to a bid or ad rank below the competition. `0` means the campaign contested every eligible auction with no rank-related loss. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "lost_is_budget": { "type": "string", "description": "Lost impression share by budget: percentage of eligible auction opportunities the campaign lost due to insufficient budget to compete. `0` means the campaign contested every eligible auction with no budget-related loss. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "roas": { "type": "string", "description": "Consolidated return on ad spend, combining click- and view-attributed revenue across all ad formats." }, "roas_click": { "type": "string", "description": "Return on ad spend calculated using click-attributed conversion value only (`income_click / total_spent`)." }, "click_roas": { "type": "string", "description": "Deprecated. Use `roas_click` instead, which returns the same value. This field is kept for backward compatibility and will be removed in a future version.", "deprecated": true }, "overall_roas": { "type": "string", "description": "Combined return on ad spend across direct and assisted conversions (`(income + assisted_income) / total_spent`)." }, "adcost": { "type": "string", "description": "Ad cost percentage." }, "income": { "type": "string", "description": "Total income generated." }, "income_click": { "type": "string", "description": "Total income generated from click-attributed conversions." }, "total_spent": { "type": "string", "description": "Total amount spent." }, "ecpm": { "type": "string", "description": "Effective cost per mille (CPM)." }, "cpa": { "type": "string", "description": "Cost per acquisition." }, "avg_cpc": { "type": "string", "description": "Average cost per click." }, "avg_cpm": { "type": "string", "description": "Average cost per mille." }, "assisted_orders": { "type": "string", "description": "Number of orders that include at least one item purchased as a result of ad exposure, in addition to (or instead of) the directly clicked or viewed product. These are orders where the ad influenced the overall purchase beyond its direct conversion. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_items": { "type": "string", "description": "Total quantity of additional items sold that are credited to an ad's influence on a purchase, separate from the ad's direct conversions. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_income": { "type": "string", "description": "Total revenue generated from additional items purchased as a result of an ad's influence on a purchase, beyond the ad's direct conversions. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_roas": { "type": "string", "description": "Return on ad spend calculated using assisted revenue only (assisted income divided by total ad spend), separate from the ad's direct-conversion ROAS. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true } } } } } } } }, "example": { "total": 1, "pages": 1, "currentPage": 1, "data": [ { "id": "campaign-id", "advertiser_id": "advertiser-id", "name": "Campaign Name", "status": "partial_running", "type": "on_site", "settings": { "daily_budget": 10000, "cpc": 250, "budget_type": "evenly" }, "start_at": "2025-01-01T00:00:00.000Z", "end_at": "2025-01-31T00:00:00.000Z", "created_at": "2025-01-01T07:33:08.482Z", "updated_at": "2025-01-26T16:16:08.482Z", "publisher_id": "publisher-id", "ad_type": "product", "cid": 16674, "target": "target-name", "strategy_type": "standard", "total_budget": "0.0000", "active": true, "advertiser_name": "advertiser name", "advertiser_account_id": "advertiser-account-id", "publisher_name": "publisher-name", "publisher_account_id": "publisher-account-id", "consumed_budget": "1750.0000", "daily_budget": "10000.00", "campaign_status": 1, "pending": [], "metrics": { "clicks": 39, "conversions": 4, "impressions": 7603, "views": 51, "total_conversions_items_quantity_click": "5", "conversions_click": "3", "conversion_rate": "4.44", "conversion_rate_click": "7.69", "ctr": ".51", "impression_share": "62.40", "lost_is_rank": "21.10", "lost_is_budget": "16.50", "roas": "2.64", "roas_click": "1.80", "click_roas": "1.80", "overall_roas": "3.59", "adcost": "37.87", "income": "25747.00", "income_click": "17550.00", "total_spent": "9750.00", "ecpm": "3.3864", "cpa": "2437.50", "avg_cpc": "250.00", "avg_cpm": "1282.39", "assisted_orders": "2", "assisted_items": "5", "assisted_income": "9260.00", "assisted_roas": "0.95" } } ] } } } }, "401": { "description": "Unauthorized\n\nMissing or invalid authentication credentials." }, "429": { "description": "Too Many Requests\n\nThis endpoint is limited to 100 requests per minute per account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Rate limit error message." } } }, "example": { "error": "Rate limit exceeded for this account" } } } } } } }, "/campaign/{campaign_id}": { "servers": [ { "url": "https://api-retail-media.newtail.com.br", "description": "VTEX Ads server." } ], "get": { "tags": [ "Reports" ], "summary": "Get campaign details", "description": "Retrieves detailed information about a campaign, such as the products associated with the campaign, status history, ads, and metrics. The data is returned only in JSON format.\r\n\r\n>⚠️ This endpoint is limited to 100 requests per minute per account. Exceeding the limit returns `429 Too Many Requests`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "campaign_id", "in": "path", "description": "Unique identifier of the campaign to fetch.", "required": true, "schema": { "type": "string", "example": "ab90a43b-582e-4be9-b126-2067dd8f30a3" } }, { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" } ], "responses": { "200": { "description": "OK\n\nCampaign returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique campaign identifier." }, "advertiser_id": { "type": "string", "description": "Advertiser identifier." }, "name": { "type": "string", "description": "Campaign name." }, "description": { "type": "string", "description": "Campaign description.", "nullable": true }, "status": { "type": "string", "description": "Campaign status." }, "type": { "type": "string", "description": "Campaign type." }, "settings": { "type": "object", "description": "Campaign settings object. The fields are dynamic and may vary depending on the campaign type.", "properties": { "daily_budget": { "type": "number", "description": "Daily budget amount.", "format": "double" }, "cpc": { "type": "number", "description": "Cost per click value.", "format": "double" }, "cpm": { "type": "number", "description": "Cost per mille value.", "format": "double" }, "budget_type": { "type": "string", "description": "Budget distribution type." } } }, "start_at": { "type": "string", "description": "Campaign start date in ISO 8601 format." }, "end_at": { "type": "string", "description": "Campaign end date in ISO 8601 format." }, "created_at": { "type": "string", "description": "Campaign creation date in ISO 8601 format." }, "updated_at": { "type": "string", "description": "Campaign last update date in ISO 8601 format." }, "deleted_at": { "type": "string", "description": "Campaign deletion date in ISO 8601 format.", "nullable": true }, "ad_type": { "type": "string", "description": "Advertisement type." }, "targeting_type": { "type": "string", "description": "Targeting type." }, "strategy_type": { "type": "string", "description": "Campaign strategy type." }, "total_budget": { "type": "string", "description": "Total campaign budget." }, "active": { "type": "boolean", "description": "Whether the campaign is active." }, "publisher_id": { "type": "string", "description": "Publisher identifier." }, "seller_id": { "type": "string", "description": "Seller identifier (when applicable).", "nullable": true }, "target": { "type": "string", "description": "Campaign target (when applicable)." }, "network_id": { "type": "string", "description": "Network identifier (when applicable).", "nullable": true }, "audience_id": { "type": "string", "description": "Audience identifier (when applicable).", "nullable": true }, "advertiser_name": { "type": "string", "description": "Advertiser name." }, "advertiser_account_id": { "type": "string", "description": "Advertiser account identifier." }, "publisher_name": { "type": "string", "description": "Publisher name." }, "publisher_account_id": { "type": "string", "description": "Publisher account identifier." }, "conversions_quantity": { "type": "string", "description": "Total quantity of conversions." }, "consumed_budget": { "type": "string", "description": "Amount of budget consumed." }, "pending": { "type": "array", "description": "Pending operations awaiting review for this campaign/ad. Empty when there is nothing pending.", "items": { "type": "object", "description": "Pending operation entry, grouping a `label` with its `quantity`.", "properties": { "label": { "type": "string", "description": "Type of pending operation. Currently, only `ads` is returned, indicating ads awaiting review.", "enum": [ "ads" ] }, "quantity": { "type": "integer", "description": "Number of pending items of the given `label`." } } } }, "metrics": { "type": "object", "description": "Performance metrics object. All metric values are returned as strings regardless of their numeric nature.", "properties": { "clicks": { "type": "integer", "description": "Total number of clicks." }, "conversions": { "type": "integer", "description": "Total number of conversions." }, "impressions": { "type": "integer", "description": "Total number of impressions." }, "views": { "type": "integer", "description": "Total number of views." }, "total_conversions_items_quantity_click": { "type": "string", "description": "Total quantity of items across all click-attributed conversions. Sums the quantities of every item in each click-attributed conversion event (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 2)." }, "conversions_click": { "type": "string", "description": "Total number of ad-driven conversions attributed to a click." }, "conversion_rate": { "type": "string", "description": "Consolidated conversion rate percentage, calculated as total conversions divided by the sum of clicks and views (`total_conversions / (total_clicks + total_views)`). This is the default conversion rate and considers both click- and view-attributed conversions." }, "conversion_rate_click": { "type": "string", "description": "Click-attributed conversion rate percentage, calculated as `conversions_click / clicks`." }, "ctr": { "type": "string", "description": "Click-through rate percentage." }, "impression_share": { "type": "string", "description": "Impression share (IS): percentage of eligible auction opportunities the campaign won, out of the estimated total (eligible auctions with available budget plus auctions lost due to insufficient budget). This field, `lost_is_rank`, and `lost_is_budget` add up to approximately 100%. `0` means the campaign received no impressions in the selected period. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "lost_is_rank": { "type": "string", "description": "Lost impression share by rank: percentage of eligible auction opportunities the campaign lost due to a bid or ad rank below the competition. `0` means the campaign contested every eligible auction with no rank-related loss. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "lost_is_budget": { "type": "string", "description": "Lost impression share by budget: percentage of eligible auction opportunities the campaign lost due to insufficient budget to compete. `0` means the campaign contested every eligible auction with no budget-related loss. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "roas": { "type": "string", "description": "Consolidated return on ad spend, combining click- and view-attributed revenue across all ad formats." }, "roas_click": { "type": "string", "description": "Return on ad spend calculated using click-attributed conversion value only (`income_click / total_spent`)." }, "click_roas": { "type": "string", "description": "Deprecated. Use `roas_click` instead, which returns the same value. This field is kept for backward compatibility and will be removed in a future version.", "deprecated": true }, "overall_roas": { "type": "string", "description": "Combined return on ad spend across direct and assisted conversions (`(income + assisted_income) / total_spent`)." }, "adcost": { "type": "string", "description": "Ad cost percentage." }, "income": { "type": "string", "description": "Total income generated." }, "income_click": { "type": "string", "description": "Total income generated from click-attributed conversions." }, "total_spent": { "type": "string", "description": "Total amount spent." }, "ecpm": { "type": "string", "description": "Effective cost per mille (CPM)." }, "cpa": { "type": "string", "description": "Cost per acquisition." }, "avg_cpc": { "type": "string", "description": "Average cost per click." }, "avg_cpm": { "type": "string", "description": "Average cost per mille." }, "assisted_orders": { "type": "string", "description": "Number of orders that include at least one item purchased as a result of ad exposure, in addition to (or instead of) the directly clicked or viewed product. These are orders where the ad influenced the overall purchase beyond its direct conversion. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_items": { "type": "string", "description": "Total quantity of additional items sold that are credited to an ad's influence on a purchase, separate from the ad's direct conversions. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_income": { "type": "string", "description": "Total revenue generated from additional items purchased as a result of an ad's influence on a purchase, beyond the ad's direct conversions. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_roas": { "type": "string", "description": "Return on ad spend calculated using assisted revenue only (assisted income divided by total ad spend), separate from the ad's direct-conversion ROAS. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true } } }, "ads": { "type": "array", "description": "Array of ad objects associated with the campaign.", "items": { "type": "object", "description": "Ad object.", "properties": { "id": { "type": "string", "description": "Unique ad identifier." }, "campaign_id": { "type": "string", "description": "Associated campaign identifier." }, "url": { "type": "string", "description": "Ad destination URL." }, "settings": { "type": "object", "description": "Ad-specific settings object. The fields are dynamic and may vary depending on the ad type.", "properties": { "ad_size": { "type": "string", "description": "Ad dimensions/size specification." }, "media_url": { "type": "string", "description": "URL of the ad media asset." }, "type": { "type": "string", "description": "Ad type." } } }, "disabled_at": { "type": "string", "description": "Ad disabled date in ISO 8601 format.", "nullable": true }, "created_at": { "type": "string", "description": "Ad creation date in ISO 8601 format." }, "updated_at": { "type": "string", "description": "Ad last update date in ISO 8601 format." }, "deleted_at": { "type": "string", "description": "Ad deletion date in ISO 8601 format.", "nullable": true }, "status": { "type": "string", "description": "Ad status." }, "aid": { "type": "integer", "description": "Ad internal ID." }, "asset_type": { "type": "string", "description": "Asset type (for example, `image`, `video`)." }, "active": { "type": "boolean", "description": "Whether the ad is active." }, "campaign_name": { "type": "string", "description": "Associated campaign name." }, "ad_type": { "type": "string", "description": "Advertisement type." }, "campaign_status": { "type": "string", "description": "Associated campaign status." }, "is_running": { "type": "boolean", "description": "Whether the ad is currently running." }, "campaign_settings": { "type": "object", "description": "Associated campaign settings. The fields are dynamic and may vary depending on the campaign type.", "properties": { "daily_budget": { "type": "number", "description": "Daily budget amount.", "format": "double" }, "cpm": { "type": "number", "description": "Cost per mille value.", "format": "double" }, "budget_type": { "type": "string", "description": "Budget distribution type." } } }, "metrics": { "type": "object", "description": "Ad-specific performance metrics. Most metric values are returned as strings, but count metrics such as `clicks`, `conversions`, `impressions`, and `views` may be returned as numbers. Per-ad metric keys may differ from the parent `metrics` object." } } } }, "products": { "type": "array", "description": "Array of products associated with the campaign.", "items": { "type": "object", "description": "Product object.", "properties": { "id": { "type": "string", "description": "Unique product identifier." }, "name": { "type": "string", "description": "Product name." }, "sku": { "type": "string", "description": "Product SKU." }, "image_url": { "type": "string", "description": "Product image URL." } } } }, "status_history": { "type": "array", "description": "Array of status change history.", "items": { "type": "object", "description": "Status change object.", "properties": { "id": { "type": "string", "description": "Unique status change identifier." }, "status": { "type": "string", "description": "Status value." }, "created_at": { "type": "string", "description": "Status change date in ISO 8601 format." } } } } } }, "example": { "id": "campaign-001", "advertiser_id": "advertiser-xyz", "name": "Sample Campaign Name", "description": "Sample Campaign Description", "status": "running", "type": "on_site", "settings": { "daily_budget": 10000, "cpm": 1000, "budget_type": "evenly" }, "start_at": "2025-01-01T00:00:00.000Z", "end_at": "2025-01-31T00:00:00.000Z", "created_at": "2025-07-14T17:14:56.513Z", "updated_at": "2025-07-14T17:14:56.513Z", "ad_type": "banner", "targeting_type": "category", "strategy_type": "standard", "total_budget": "0.0000", "active": true, "publisher_id": "publisher-id", "target": "target-name", "advertiser_name": "advertiser-name", "advertiser_account_id": "advertiser-account-id", "publisher_name": "publisher-name", "publisher_account_id": "publisher-account-id", "conversions_quantity": "82", "consumed_budget": "36070.0000", "pending": [], "metrics": { "clicks": 39, "conversions": 4, "impressions": 7603, "views": 51, "total_conversions_items_quantity_click": "5", "conversions_click": "3", "conversion_rate": "4.44", "conversion_rate_click": "7.69", "ctr": ".51", "impression_share": "62.40", "lost_is_rank": "21.10", "lost_is_budget": "16.50", "roas": "2.64", "roas_click": "1.80", "click_roas": "1.80", "overall_roas": "3.59", "adcost": "37.87", "income": "25747.00", "income_click": "17550.00", "total_spent": "9750.00", "ecpm": "3.3864", "cpa": "2437.50", "avg_cpc": "250.00", "avg_cpm": "1282.39", "assisted_orders": "2", "assisted_items": "5", "assisted_income": "9260.00", "assisted_roas": "0.95" }, "ads": [ { "id": "ad-001", "campaign_id": "ab90a43b-582e-4be9-b126-2067dd8f30a3", "url": "https://example.com", "settings": { "ad_size": "example-size", "media_url": "https://cdn.example.com/ad-image.jpeg", "type": "banner" }, "created_at": "2025-07-14T17:14:56.513Z", "updated_at": "2025-07-14T17:14:56.513Z", "status": "enabled", "aid": 255272, "asset_type": "image", "active": true, "campaign_name": "Sample Campaign Name", "ad_type": "banner", "campaign_status": "pending_review", "is_running": true, "campaign_settings": { "daily_budget": 10000, "cpm": 1000, "budget_type": "evenly" }, "metrics": { "clicks": 39, "conversions": 4, "impressions": 7603, "views": 51, "conversion_rate": "10.26", "ctr": ".51", "roas": "2.64", "adcost": "37.87", "income": "25747.00", "total_spent": "9750.00", "ecpm": "3.3864", "cpa": "2437.50", "avg_cpc": "250.00", "avg_cpm": "1282.39" } } ], "products": [ { "id": "product-001", "name": "Example Product Name", "sku": "123456", "image_url": "https://example.com/product.jpg" } ], "status_history": [ { "id": "status-001", "status": "running", "created_at": "2025-07-03T22:53:57.272Z" } ] } } } }, "401": { "description": "Unauthorized\n\nMissing or invalid authentication credentials." }, "404": { "description": "Not Found\n\nCampaign not found." }, "429": { "description": "Too Many Requests\n\nThis endpoint is limited to 100 requests per minute per account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Rate limit error message." } } }, "example": { "error": "Rate limit exceeded for this account" } } } } } } }, "/report/advertisers/campaigns-detailed": { "servers": [ { "url": "https://api-retail-media.newtail.com.br", "description": "VTEX Ads server." } ], "get": { "tags": [ "Reports" ], "summary": "Get advertiser campaigns detailed report", "description": "Exports a mixed campaign report for advertiser accounts, including both regular campaigns and subpublisher information for network campaigns. The data is returned in JSON format by default, but can be exported as an XLSX file by setting `download=true`.\r\n\r\n>ℹ️ This route is intended for advertiser accounts. For non white-label accounts, only non-private publisher rows are returned.\r\n\r\n>⚠️ This endpoint is limited to 100 requests per minute per account. Exceeding the limit returns `429 Too Many Requests`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "name": "campaign_id", "in": "query", "description": "Filters by campaign ID.", "required": false, "schema": { "type": "string", "example": "campaign-id" } }, { "name": "campaign_status", "in": "query", "description": "Filters by campaign status.", "required": false, "schema": { "type": "string", "example": "running" } }, { "name": "publisher_id", "in": "query", "description": "Filters by publisher ID.", "required": false, "schema": { "type": "string", "example": "publisher-id" } }, { "name": "publisher_name", "in": "query", "description": "Filters by publisher name.", "required": false, "schema": { "type": "string", "example": "MyStore" } }, { "name": "ad_type", "in": "query", "description": "Filters by ad type.", "required": false, "schema": { "type": "string", "enum": [ "banner", "product", "sponsored_brand", "digital_signage" ], "example": "product" } }, { "name": "ad_status", "in": "query", "description": "Filters by ad status.", "required": false, "schema": { "type": "string", "enum": [ "enabled", "paused", "rejected", "pending_review", "stock_out", "invalid_cost" ], "example": "enabled" } }, { "name": "seller_id", "in": "query", "description": "Filters by seller ID.", "required": false, "schema": { "type": "string", "example": "seller-id" } }, { "name": "tag_id", "in": "query", "description": "Filters by advertiser tag ID.", "required": false, "schema": { "type": "string", "example": "tag-id" } }, { "name": "targeting_type", "in": "query", "description": "Filters by targeting type.", "required": false, "schema": { "type": "string", "example": "category" } }, { "name": "sub_publisher_id", "in": "query", "description": "Filters network rows by subpublisher ID.", "required": false, "schema": { "type": "string", "example": "subpublisher-id" } }, { "name": "sub_publisher_name", "in": "query", "description": "Filters network rows by subpublisher name.", "required": false, "schema": { "type": "string", "example": "Subpublisher Name" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Quantity" }, { "name": "count", "in": "query", "description": "If `true`, returns pagination metadata.", "required": false, "schema": { "type": "boolean", "default": true, "example": true } }, { "name": "order_by", "in": "query", "description": "Field used to sort results.", "required": false, "schema": { "type": "string", "enum": [ "advertiser_name", "name", "ad_type", "status", "sub_publisher_name", "daily_budget", "impressions", "views", "clicks", "ctr", "total_spent", "conversions", "conversion_rate", "income", "roas", "created_at", "start_at" ], "example": "income" } }, { "$ref": "#/components/parameters/OrderDirection" }, { "$ref": "#/components/parameters/Download" } ], "responses": { "200": { "description": "OK\n\nReport returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of campaigns." }, "pages": { "type": "integer", "description": "Total number of pages for pagination." }, "currentPage": { "type": "integer", "description": "Current page number." }, "data": { "type": "array", "description": "Array of detailed campaign objects.", "items": { "type": "object", "description": "Detailed campaign object.", "properties": { "id": { "type": "string", "description": "Unique campaign identifier." }, "advertiser_id": { "type": "string", "description": "Advertiser identifier." }, "name": { "type": "string", "description": "Campaign name." }, "status": { "type": "string", "description": "Campaign status." }, "type": { "type": "string", "description": "Campaign type." }, "publisher_id": { "type": "string", "description": "Publisher identifier." }, "publisher_name": { "type": "string", "description": "Publisher name." }, "advertiser_name": { "type": "string", "description": "Advertiser name." }, "sub_publisher_id": { "type": "string", "description": "Subpublisher identifier (only present for network campaigns).", "nullable": true }, "sub_publisher_name": { "type": "string", "description": "Subpublisher name (only present for network campaigns).", "nullable": true }, "active": { "type": "boolean", "description": "Whether the campaign is active." }, "daily_budget": { "type": "string", "description": "Daily budget amount." }, "consumed_budget": { "type": "string", "description": "Amount of budget consumed." }, "pending": { "type": "array", "description": "Pending operations awaiting review for this campaign/ad. Empty when there is nothing pending.", "items": { "type": "object", "description": "Pending operation entry, grouping a `label` with its `quantity`.", "properties": { "label": { "type": "string", "description": "Type of pending operation. Currently, only `ads` is returned, indicating ads awaiting review.", "enum": [ "ads" ] }, "quantity": { "type": "integer", "description": "Number of pending items of the given `label`." } } } }, "metrics": { "type": "object", "description": "Performance metrics object. All metric values are returned as strings regardless of their numeric nature.", "properties": { "clicks": { "type": "integer", "description": "Total number of clicks." }, "conversions": { "type": "integer", "description": "Total number of conversions." }, "total_conversions_items_quantity": { "type": "integer", "description": "Total quantity of converted items." }, "total_conversions_items_quantity_click": { "type": "string", "description": "Total quantity of items across all click-attributed conversions. Sums the quantities of every item in each click-attributed conversion event (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 2)." }, "impressions": { "type": "integer", "description": "Total number of impressions." }, "views": { "type": "integer", "description": "Total number of views." }, "conversions_click": { "type": "string", "description": "Total number of ad-driven conversions attributed to a click." }, "conversion_rate": { "type": "string", "description": "Consolidated conversion rate percentage, calculated as total conversions divided by the sum of clicks and views (`total_conversions / (total_clicks + total_views)`). This is the default conversion rate and considers both click- and view-attributed conversions." }, "conversion_rate_click": { "type": "string", "description": "Click-attributed conversion rate percentage, calculated as `conversions_click / clicks`." }, "ctr": { "type": "string", "description": "Click-through rate percentage." }, "impression_share": { "type": "string", "description": "Impression share (IS): percentage of eligible auction opportunities the campaign won, out of the estimated total (eligible auctions with available budget plus auctions lost due to insufficient budget). This field, `lost_is_rank`, and `lost_is_budget` add up to approximately 100%. `0` means the campaign received no impressions in the selected period. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "lost_is_rank": { "type": "string", "description": "Lost impression share by rank: percentage of eligible auction opportunities the campaign lost due to a bid or ad rank below the competition. `0` means the campaign contested every eligible auction with no rank-related loss. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "lost_is_budget": { "type": "string", "description": "Lost impression share by budget: percentage of eligible auction opportunities the campaign lost due to insufficient budget to compete. `0` means the campaign contested every eligible auction with no budget-related loss. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "roas": { "type": "string", "description": "Consolidated return on ad spend, combining click- and view-attributed revenue across all ad formats." }, "roas_click": { "type": "string", "description": "Return on ad spend calculated using click-attributed conversion value only (`income_click / total_spent`)." }, "click_roas": { "type": "string", "description": "Deprecated. Use `roas_click` instead, which returns the same value. This field is kept for backward compatibility and will be removed in a future version.", "deprecated": true }, "overall_roas": { "type": "string", "description": "Combined return on ad spend across direct and assisted conversions (`(income + assisted_income) / total_spent`)." }, "adcost": { "type": "string", "description": "Ad cost percentage." }, "income": { "type": "string", "description": "Total income generated." }, "income_click": { "type": "string", "description": "Total income generated from click-attributed conversions." }, "total_spent": { "type": "string", "description": "Total amount spent." }, "ecpm": { "type": "string", "description": "Effective cost per mille (CPM)." }, "cpa": { "type": "string", "description": "Cost per acquisition." }, "avg_cpc": { "type": "string", "description": "Average cost per click." }, "avg_cpm": { "type": "string", "description": "Average cost per mille." }, "assisted_orders": { "type": "string", "description": "Number of orders that include at least one item purchased as a result of ad exposure, in addition to (or instead of) the directly clicked or viewed product. These are orders where the ad influenced the overall purchase beyond its direct conversion. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_items": { "type": "string", "description": "Total quantity of additional items sold that are credited to an ad's influence on a purchase, separate from the ad's direct conversions. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_income": { "type": "string", "description": "Total revenue generated from additional items purchased as a result of an ad's influence on a purchase, beyond the ad's direct conversions. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_roas": { "type": "string", "description": "Return on ad spend calculated using assisted revenue only (assisted income divided by total ad spend), separate from the ad's direct-conversion ROAS. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true } } } } } } } }, "example": { "total": 1, "pages": 1, "currentPage": 1, "data": [ { "id": "campaign-id", "advertiser_id": "advertiser-id", "name": "Campaign Name", "status": "partial_running", "type": "on_site", "publisher_id": "publisher-id", "publisher_name": "Publisher Name", "advertiser_name": "Advertiser Name", "sub_publisher_id": "subpublisher-id", "sub_publisher_name": "Subpublisher Name", "active": true, "daily_budget": "10000.00", "consumed_budget": "1750.0000", "pending": [], "metrics": { "clicks": 39, "conversions": 4, "total_conversions_items_quantity": 7, "total_conversions_items_quantity_click": "5", "impressions": 7603, "views": 51, "conversions_click": "3", "conversion_rate": "4.44", "conversion_rate_click": "7.69", "ctr": ".51", "impression_share": "62.40", "lost_is_rank": "21.10", "lost_is_budget": "16.50", "roas": "2.64", "roas_click": "1.80", "click_roas": "1.80", "overall_roas": "3.59", "adcost": "37.87", "income": "25747.00", "income_click": "17550.00", "total_spent": "9750.00", "ecpm": "3.3864", "cpa": "2437.50", "avg_cpc": "250.00", "avg_cpm": "1282.39", "assisted_orders": "2", "assisted_items": "5", "assisted_income": "9260.00", "assisted_roas": "0.95" } } ] } } } }, "401": { "description": "Unauthorized\n\nMissing or invalid authentication credentials." }, "429": { "description": "Too Many Requests\n\nThis endpoint is limited to 100 requests per minute per account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Rate limit error message." } } }, "example": { "error": "Rate limit exceeded for this account" } } } } } } }, "/report/advertisers/ads-detailed": { "servers": [ { "url": "https://api-retail-media.newtail.com.br", "description": "VTEX Ads server." } ], "get": { "tags": [ "Reports" ], "summary": "Get advertiser ads detailed report", "description": "Exports a detailed ad report for advertiser accounts, including subpublisher breakdown for network campaigns. The data is returned in JSON format by default, but can be exported as an XLSX file by setting `download=true`.\r\n\r\n>ℹ️ This route is intended for advertiser accounts. Non-network campaigns return one row per ad, while network campaigns return one row per `ad + subpublisher`. For non white-label accounts, only non-private publisher rows are returned.\r\n\r\n>⚠️ This endpoint is limited to 100 requests per minute per account. Exceeding the limit returns `429 Too Many Requests`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "name": "campaign_name", "in": "query", "description": "Filters ads by campaign name.", "required": false, "schema": { "type": "string", "example": "Holiday Sale" } }, { "name": "campaign_id", "in": "query", "description": "Filters ads by campaign ID.", "required": false, "schema": { "type": "string", "example": "campaign-id" } }, { "name": "publisher_id", "in": "query", "description": "Filters ads by publisher ID.", "required": false, "schema": { "type": "string", "example": "publisher-id" } }, { "name": "advertiser_id", "in": "query", "description": "Filters ads by advertiser ID. In the BFF flow, this value is derived from the authenticated advertiser context.", "required": false, "schema": { "type": "string", "example": "advertiser-id" } }, { "name": "product_sku", "in": "query", "description": "Filters ads by product SKU.", "required": false, "schema": { "type": "string", "example": "SKU-123" } }, { "name": "ad_status", "in": "query", "description": "Filters ads by status.", "required": false, "schema": { "type": "string", "enum": [ "enabled", "paused", "rejected", "pending_review", "stock_out", "invalid_cost" ], "example": "enabled" } }, { "name": "ad_type", "in": "query", "description": "Filters by ad type.", "required": false, "schema": { "type": "string", "enum": [ "banner", "product", "sponsored_brand", "digital_signage" ], "example": "product" } }, { "name": "targeting_type", "in": "query", "description": "Filters by targeting type.", "required": false, "schema": { "type": "string", "example": "category" } }, { "name": "tag_id", "in": "query", "description": "Filters by advertiser tag ID.", "required": false, "schema": { "type": "string", "example": "tag-id" } }, { "name": "sub_publisher_id", "in": "query", "description": "Filters network rows by subpublisher ID.", "required": false, "schema": { "type": "string", "example": "subpublisher-id" } }, { "name": "sub_publisher_name", "in": "query", "description": "Filters network rows by subpublisher name.", "required": false, "schema": { "type": "string", "example": "Subpublisher Name" } }, { "name": "show_inactive", "in": "query", "description": "If `true`, includes paused ads.", "required": false, "schema": { "type": "boolean", "default": false, "example": false } }, { "name": "hide_pending_rejected", "in": "query", "description": "If `true`, excludes `pending_review` and `rejected` rows when `ad_status` is not provided.", "required": false, "schema": { "type": "boolean", "default": false, "example": false } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Quantity" }, { "name": "count", "in": "query", "description": "If `true`, returns pagination metadata.", "required": false, "schema": { "type": "boolean", "default": true, "example": true } }, { "name": "order_by", "in": "query", "description": "Field used to sort results.", "required": false, "schema": { "type": "string", "enum": [ "ad_type", "ad_status", "impressions", "conversion_rate", "ctr", "income", "total_spent", "roas", "conversions", "total_conversions_items_quantity", "advertiser_name", "campaign_name", "clicks", "adcost", "created_at", "sub_publisher_name" ], "example": "income" } }, { "$ref": "#/components/parameters/OrderDirection" }, { "$ref": "#/components/parameters/Download" } ], "responses": { "200": { "description": "OK\n\nReport returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of ads." }, "pages": { "type": "integer", "description": "Total number of pages for pagination." }, "currentPage": { "type": "integer", "description": "Current page number." }, "data": { "type": "array", "description": "Array of detailed ad objects.", "items": { "type": "object", "description": "Detailed ad object.", "properties": { "id": { "type": "string", "description": "Unique ad identifier." }, "campaign_id": { "type": "string", "description": "Associated campaign identifier." }, "url": { "type": "string", "description": "Ad destination URL." }, "status": { "type": "string", "description": "Ad status." }, "active": { "type": "boolean", "description": "Whether the ad is active." }, "product_sku": { "type": "string", "description": "Associated product SKU (when applicable).", "nullable": true }, "campaign_name": { "type": "string", "description": "Associated campaign name." }, "campaign_status": { "type": "string", "description": "Associated campaign status." }, "ad_type": { "type": "string", "description": "Advertisement type." }, "publisher_id": { "type": "string", "description": "Publisher identifier." }, "publisher_name": { "type": "string", "description": "Publisher name." }, "publisher_account_id": { "type": "string", "description": "Publisher account identifier." }, "advertiser_id": { "type": "string", "description": "Advertiser identifier." }, "advertiser_name": { "type": "string", "description": "Advertiser name." }, "advertiser_account_id": { "type": "string", "description": "Advertiser account identifier." }, "sub_publisher_id": { "type": "string", "description": "Subpublisher identifier (only present for network campaigns).", "nullable": true }, "sub_publisher_name": { "type": "string", "description": "Subpublisher name (only present for network campaigns).", "nullable": true }, "sub_publisher_account_id": { "type": "string", "description": "Subpublisher account identifier (only present for network campaigns).", "nullable": true }, "metrics": { "type": "object", "description": "Ad performance metrics object. All metric values are returned as strings regardless of their numeric nature.", "properties": { "clicks": { "type": "string", "description": "Total number of clicks." }, "conversions": { "type": "string", "description": "Total number of conversions." }, "total_conversions_items_quantity": { "type": "string", "description": "Total quantity of items across all ad-driven conversions. Sums the quantities of every item in each conversion event (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 2)." }, "impressions": { "type": "string", "description": "Total number of impressions." }, "views": { "type": "string", "description": "Total number of views." }, "conversion_rate": { "type": "string", "description": "Conversion rate percentage." }, "ctr": { "type": "string", "description": "Click-through rate percentage." }, "impression_share": { "type": "string", "description": "Impression share (IS): percentage of eligible auction opportunities the ad won, out of the estimated total (eligible auctions with available budget plus auctions lost due to insufficient budget). Computed for the ad itself, not inherited from its campaign. This field, `lost_is_rank`, and `lost_is_budget` add up to approximately 100%. `0` means the ad received no impressions in the selected period. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "lost_is_rank": { "type": "string", "description": "Lost impression share by rank: percentage of eligible auction opportunities the ad lost due to a bid or ad rank below the competition. `0` means the ad contested every eligible auction with no rank-related loss. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "lost_is_budget": { "type": "string", "description": "Lost impression share by budget: percentage of eligible auction opportunities the ad lost due to insufficient budget to compete. `0` means the ad contested every eligible auction with no budget-related loss. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "roas": { "type": "string", "description": "Return on ad spend." }, "adcost": { "type": "string", "description": "Ad cost percentage." }, "income": { "type": "string", "description": "Total income generated." }, "total_spent": { "type": "string", "description": "Total amount spent." }, "ecpm": { "type": "string", "description": "Effective cost per mille (CPM)." }, "cpa": { "type": "string", "description": "Cost per acquisition." }, "avg_cpc": { "type": "string", "description": "Average cost per click." }, "avg_cpm": { "type": "string", "description": "Average cost per mille." } } } } } } } }, "example": { "total": 1, "pages": 1, "currentPage": 1, "data": [ { "id": "ad-id", "campaign_id": "campaign-id", "url": "https://example.com/product", "status": "enabled", "active": true, "product_sku": "SKU-123", "campaign_name": "Campaign Name", "campaign_status": "running", "ad_type": "product", "publisher_id": "publisher-id", "publisher_name": "Publisher Name", "publisher_account_id": "publisher-account-id", "advertiser_id": "advertiser-id", "advertiser_name": "Advertiser Name", "advertiser_account_id": "advertiser-account-id", "sub_publisher_id": "subpublisher-id", "sub_publisher_name": "Subpublisher Name", "sub_publisher_account_id": "subpublisher-account-id", "metrics": { "clicks": "3", "conversions": "1", "total_conversions_items_quantity": "2", "impressions": "10691", "views": "0", "conversion_rate": "33.33", "ctr": "0.03", "impression_share": "62.40", "lost_is_rank": "21.10", "lost_is_budget": "16.50", "roas": "2.64", "adcost": "37.87", "income": "818.00", "total_spent": "309.82000000", "ecpm": "28.98", "cpa": "309.82", "avg_cpc": "103.27", "avg_cpm": "28.98" } } ] } } } }, "401": { "description": "Unauthorized\n\nMissing or invalid authentication credentials." }, "429": { "description": "Too Many Requests\n\nThis endpoint is limited to 100 requests per minute per account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Rate limit error message." } } }, "example": { "error": "Rate limit exceeded for this account" } } } } } } }, "/ad/results/v2": { "servers": [ { "url": "https://api-retail-media.newtail.com.br", "description": "VTEX Ads server." } ], "get": { "tags": [ "Reports" ], "summary": "Get ads performance report", "description": "Fetches all available ads, applying filters as needed. The data is returned in JSON format by default, but can be exported as an XLSX file by setting `download=true`.\r\n\r\n>ℹ️ Paused ads are excluded from the default response. To include paused ads, set `show_inactive=true`.\r\n\r\n>⚠️ This endpoint is limited to 100 requests per minute per account. Exceeding the limit returns `429 Too Many Requests`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "name": "campaign_name", "in": "query", "description": "Filters ads by campaign name.", "required": false, "schema": { "type": "string", "example": "Holiday Sale" } }, { "name": "campaign_id", "in": "query", "description": "Filters ads by campaign ID.", "required": false, "schema": { "type": "string", "example": "campaign-id" } }, { "name": "advertiser_id", "in": "query", "description": "Filters ads by advertiser ID.", "required": false, "schema": { "type": "string", "example": "advertiser-id" } }, { "name": "product_sku", "in": "query", "description": "Filters ads by product SKU.", "required": false, "schema": { "type": "string", "example": "SKU-123" } }, { "name": "ad_status", "in": "query", "description": "Filters ads by status.", "required": false, "schema": { "type": "string", "enum": [ "enabled", "paused", "rejected", "pending_review", "stock_out", "invalid_cost" ], "example": "enabled" } }, { "name": "ad_type", "in": "query", "description": "Filters by ad type.", "required": false, "schema": { "type": "string", "enum": [ "banner", "product", "sponsored_brand", "digital_signage" ], "example": "banner" } }, { "name": "targeting_type", "in": "query", "description": "Filters by targeting type.", "required": false, "schema": { "type": "string", "example": "category" } }, { "name": "show_inactive", "in": "query", "description": "If `true`, includes paused ads.", "required": false, "schema": { "type": "boolean", "default": false, "example": false } }, { "$ref": "#/components/parameters/AccountInfo" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Quantity" }, { "$ref": "#/components/parameters/Count" }, { "name": "order_by", "in": "query", "description": "Field used to sort results.", "required": false, "schema": { "type": "string", "enum": [ "ad_type", "ad_status", "impressions", "conversion_rate", "ctr", "income", "total_spent", "roas", "conversions", "total_conversions_item_quantity" ], "example": "income" } }, { "$ref": "#/components/parameters/OrderDirection" }, { "$ref": "#/components/parameters/Download" } ], "responses": { "200": { "description": "OK\n\nReport returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of ads." }, "pages": { "type": "integer", "description": "Total number of pages for pagination." }, "currentPage": { "type": "integer", "description": "Current page number." }, "data": { "type": "array", "description": "Array of ad objects.", "items": { "type": "object", "description": "Ad object.", "properties": { "id": { "type": "string", "description": "Unique ad identifier." }, "campaign_id": { "type": "string", "description": "Associated campaign identifier." }, "url": { "type": "string", "description": "Ad destination URL." }, "settings": { "type": "object", "description": "Ad-specific settings object. The fields are dynamic and may vary depending on the ad type.", "properties": { "cpc": { "type": "number", "description": "Cost per click value.", "format": "double" }, "cpm": { "type": "number", "description": "Cost per mille value.", "format": "double" }, "type": { "type": "string", "description": "Ad type." }, "categories": { "type": "array", "description": "Targeted categories array.", "items": { "type": "string", "description": "Category name." } }, "keywords": { "type": "array", "description": "Targeted keywords array.", "items": { "type": "string", "description": "Keyword." } } } }, "disabled_at": { "type": "string", "description": "Ad disabled date in ISO 8601 format.", "nullable": true }, "created_at": { "type": "string", "description": "Ad creation date in ISO 8601 format." }, "updated_at": { "type": "string", "description": "Ad last update date in ISO 8601 format." }, "deleted_at": { "type": "string", "description": "Ad deletion date in ISO 8601 format.", "nullable": true }, "status": { "type": "string", "description": "Ad status." }, "aid": { "type": "integer", "description": "Ad internal ID." }, "asset_type": { "type": "string", "description": "Asset type (for example, `image`, `video`)." }, "active": { "type": "boolean", "description": "Whether the ad is active." }, "product_id": { "type": "string", "description": "Associated product identifier (when applicable).", "nullable": true }, "product_sku": { "type": "string", "description": "Associated product SKU (when applicable).", "nullable": true }, "name": { "type": "string", "description": "Product name (when applicable).", "nullable": true }, "image_url": { "type": "string", "description": "Product image URL (when applicable).", "nullable": true }, "categories": { "type": "array", "description": "Ad categories array (when applicable).", "items": { "type": "string", "description": "Category name." } }, "campaign_name": { "type": "string", "description": "Associated campaign name." }, "ad_type": { "type": "string", "description": "Advertisement type." }, "campaign_status": { "type": "string", "description": "Associated campaign status." }, "campaign_settings": { "type": "object", "description": "Associated campaign settings. The fields are dynamic and may vary depending on the campaign type.", "properties": { "daily_budget": { "type": "number", "description": "Daily budget amount.", "format": "double" }, "cpm": { "type": "number", "description": "Cost per mille value.", "format": "double" }, "budget_type": { "type": "string", "description": "Budget distribution type." } } }, "publisher_id": { "type": "string", "description": "Publisher identifier." }, "advertiser_id": { "type": "string", "description": "Advertiser identifier." }, "advertiser_name": { "type": "string", "description": "Advertiser name." }, "advertiser_account_id": { "type": "string", "description": "Advertiser account identifier." }, "publisher_name": { "type": "string", "description": "Publisher name." }, "publisher_account_id": { "type": "string", "description": "Publisher account identifier." }, "ad_id": { "type": "string", "description": "Unique identifier of the ad." }, "conversions_quantity": { "type": "string", "description": "Total quantity of conversions." }, "is_running": { "type": "boolean", "description": "Whether the ad is currently running." }, "advertiser_tags": { "type": "array", "description": "Tags associated with the advertiser.", "nullable": true, "items": { "type": "string", "description": "Advertiser tag." } }, "pending": { "type": "array", "description": "Pending operations awaiting review for this campaign/ad. Empty when there is nothing pending.", "items": { "type": "object", "description": "Pending operation entry, grouping a `label` with its `quantity`.", "properties": { "label": { "type": "string", "description": "Type of pending operation. Currently, only `ads` is returned, indicating ads awaiting review.", "enum": [ "ads" ] }, "quantity": { "type": "integer", "description": "Number of pending items of the given `label`." } } } }, "metrics": { "type": "object", "description": "Ad performance metrics object. All metric values are returned as strings regardless of their numeric nature.", "properties": { "clicks": { "type": "string", "description": "Total number of clicks." }, "conversions": { "type": "string", "description": "Total number of conversions." }, "total_conversions_items_quantity": { "type": "string", "description": "Total quantity of items across all ad-driven conversions. Sums the quantities of every item in each conversion event (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 2)." }, "total_conversions_items_quantity_click": { "type": "string", "description": "Total quantity of items across all click-attributed conversions. Sums the quantities of every item in each click-attributed conversion event (for example, if a shopper buys two units of a product after clicking an ad, this metric increases by 2)." }, "impressions": { "type": "string", "description": "Total number of impressions." }, "views": { "type": "string", "description": "Total number of views." }, "conversions_click": { "type": "string", "description": "Total number of ad-driven conversions attributed to a click." }, "conversion_rate": { "type": "string", "description": "Consolidated conversion rate percentage, calculated as total conversions divided by the sum of clicks and views (`total_conversions / (total_clicks + total_views)`). This is the default conversion rate and considers both click- and view-attributed conversions." }, "conversion_rate_click": { "type": "string", "description": "Click-attributed conversion rate percentage, calculated as `conversions_click / clicks`." }, "ctr": { "type": "string", "description": "Click-through rate percentage." }, "impression_share": { "type": "string", "description": "Impression share (IS): percentage of eligible auction opportunities the ad won, out of the estimated total (eligible auctions with available budget plus auctions lost due to insufficient budget). Computed for the ad itself, not inherited from its campaign. This field, `lost_is_rank`, and `lost_is_budget` add up to approximately 100%. `0` means the ad received no impressions in the selected period. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "lost_is_rank": { "type": "string", "description": "Lost impression share by rank: percentage of eligible auction opportunities the ad lost due to a bid or ad rank below the competition. `0` means the ad contested every eligible auction with no rank-related loss. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "lost_is_budget": { "type": "string", "description": "Lost impression share by budget: percentage of eligible auction opportunities the ad lost due to insufficient budget to compete. `0` means the ad contested every eligible auction with no budget-related loss. Returns `null` when the number of eligible auctions is below the minimum threshold, when there are no eligible auctions in the selected period, or when the underlying data has not yet been collected.", "nullable": true }, "roas": { "type": "string", "description": "Consolidated return on ad spend, combining click- and view-attributed revenue across all ad formats." }, "roas_click": { "type": "string", "description": "Return on ad spend calculated using click-attributed conversion value only (`income_click / total_spent`)." }, "click_roas": { "type": "string", "description": "Deprecated. Use `roas_click` instead, which returns the same value. This field is kept for backward compatibility and will be removed in a future version.", "deprecated": true }, "overall_roas": { "type": "string", "description": "Combined return on ad spend across direct and assisted conversions (`(income + assisted_income) / total_spent`)." }, "adcost": { "type": "string", "description": "Ad cost percentage." }, "income": { "type": "string", "description": "Total income generated." }, "income_click": { "type": "string", "description": "Total income generated from click-attributed conversions." }, "total_spent": { "type": "string", "description": "Total amount spent." }, "ecpm": { "type": "string", "description": "Effective cost per mille (CPM)." }, "cpa": { "type": "string", "description": "Cost per acquisition." }, "avg_cpc": { "type": "string", "description": "Average cost per click." }, "avg_cpm": { "type": "string", "description": "Average cost per mille." }, "assisted_orders": { "type": "string", "description": "Number of orders that include at least one item purchased as a result of ad exposure, in addition to (or instead of) the directly clicked or viewed product. These are orders where the ad influenced the overall purchase beyond its direct conversion. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_items": { "type": "string", "description": "Total quantity of additional items sold that are credited to an ad's influence on a purchase, separate from the ad's direct conversions. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_income": { "type": "string", "description": "Total revenue generated from additional items purchased as a result of an ad's influence on a purchase, beyond the ad's direct conversions. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true }, "assisted_roas": { "type": "string", "description": "Return on ad spend calculated using assisted revenue only (assisted income divided by total ad spend), separate from the ad's direct-conversion ROAS. Returns `null` when assisted attribution is not available for the selected period.", "nullable": true } } } } } } } }, "example": { "total": 1, "pages": 1, "currentPage": 1, "data": [ { "id": "ad-id", "campaign_id": "campaign-id", "url": "ad-url", "settings": { "cpc": 1.5, "type": "banner", "categories": [], "keywords": [ "keyword", "other keyword" ] }, "created_at": "2025-01-27T23:18:16.330Z", "updated_at": "2025-01-27T23:18:16.330Z", "status": "enabled", "aid": 1234, "asset_type": "image", "active": true, "product_id": "4567", "product_sku": "SKU-123", "name": "Product Name", "image_url": "https://example.com/image.png", "categories": [ "National Beers", "National Beers > Drinks" ], "campaign_name": "Campaign Name", "ad_type": "banner", "campaign_status": "running", "campaign_settings": { "daily_budget": 185000, "cpm": 10000, "budget_type": "evenly" }, "publisher_id": "publisher-id", "advertiser_id": "advertiser-id", "advertiser_name": "Advertiser Name", "advertiser_account_id": "advertiser-account-id", "publisher_name": "Publisher Name", "publisher_account_id": "publisher-account-id", "ad_id": "ad-id", "conversions_quantity": "1", "is_running": true, "advertiser_tags": ["premium"], "pending": [], "metrics": { "clicks": "53", "conversions": "1", "total_conversions_items_quantity": "1", "total_conversions_items_quantity_click": "1", "impressions": "2900", "views": "2689", "conversions_click": "1", "conversion_rate": "0.04", "conversion_rate_click": "1.89", "ctr": "1.83", "impression_share": "62.40", "lost_is_rank": "21.10", "lost_is_budget": "16.50", "roas": "0.18", "roas_click": "0.12", "click_roas": "0.12", "overall_roas": "0.26", "adcost": "540.94", "income": "5361.00", "income_click": "3480.00", "total_spent": "29000.0000", "ecpm": "1.85", "cpa": "29000.00", "avg_cpc": "547.17", "avg_cpm": "10000.00", "assisted_orders": "1", "assisted_items": "2", "assisted_income": "2100.00", "assisted_roas": "0.07" } } ] } } } }, "401": { "description": "Unauthorized\n\nMissing or invalid authentication credentials." }, "429": { "description": "Too Many Requests\n\nThis endpoint is limited to 100 requests per minute per account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Rate limit error message." } } }, "example": { "error": "Rate limit exceeded for this account" } } } } } } }, "/product/results": { "servers": [ { "url": "https://api-retail-media.newtail.com.br", "description": "VTEX Ads server." } ], "get": { "tags": [ "Reports" ], "summary": "Get product results by campaign", "description": "Retrieves per-product (SKU) performance metrics for every product linked to a campaign, including impressions, clicks, views, conversions, and the ad spend and conversion value attributed to each product. Metrics are aggregated over an inclusive date range, which defaults to the current date.\r\n\r\nUse this endpoint for a SKU-level breakdown of a single campaign, rather than the campaign-level totals returned by [Get campaign details](https://developers.vtex.com/docs/api-reference/vtex-ads-api#get-/campaign/-campaign_id-).\r\n\r\n>ℹ️ Do not confuse this endpoint with [Get ads performance report](https://developers.vtex.com/docs/api-reference/vtex-ads-api#get-/ad/results/v2), which also accepts `campaign_id` and returns some of the same product fields. That report lists results per ad across campaigns, with each item's metrics nested under a `metrics` object. This endpoint lists results per product (SKU) for the campaign identified by the `campaign_id` query parameter, with each product's metrics flat on the product object.\r\n\r\n>ℹ️ By default, the response is wrapped in a pagination envelope. To receive a bare array of product objects instead, set `count=false`.\r\n\r\n>⚠️ This endpoint is limited to 100 requests per minute per account. Exceeding the limit returns `429 Too Many Requests`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "name": "campaign_id", "in": "query", "description": "Unique identifier of the campaign to fetch product results for.", "required": true, "schema": { "type": "string", "example": "ab90a43b-582e-4be9-b126-2067dd8f30a3" } }, { "$ref": "#/components/parameters/Page" }, { "name": "quantity", "in": "query", "description": "Number of items per page.", "required": false, "schema": { "type": "integer", "default": 100, "example": 100 } }, { "name": "order_by", "in": "query", "description": "Field used to sort results. Unrecognized values fall back to `name`.", "required": false, "schema": { "type": "string", "enum": [ "name", "impressions", "clicks", "views", "conversions_quantity", "conversions_value", "conversions" ], "default": "name", "example": "impressions" } }, { "name": "order_direction", "in": "query", "description": "Sort direction. Unrecognized values fall back to `desc`.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc", "example": "asc" } }, { "name": "start_date", "in": "query", "description": "Start date of the metrics range, in `YYYY-MM-DD` format. This date is inclusive and defaults to the current date when omitted.", "required": false, "schema": { "type": "string", "format": "date", "example": "2025-01-01" } }, { "name": "end_date", "in": "query", "description": "End date of the metrics range, in `YYYY-MM-DD` format. This date is inclusive and defaults to the current date when omitted.", "required": false, "schema": { "type": "string", "format": "date", "example": "2025-01-31" } }, { "name": "count", "in": "query", "description": "If `true`, the response is wrapped in a pagination envelope with `total`, `pages`, and `currentPage`. If `false`, the response is a bare array of product objects, without pagination metadata.", "required": false, "schema": { "type": "boolean", "default": true, "example": true } } ], "responses": { "200": { "description": "OK\n\nProduct results returned successfully.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Paginated response", "description": "Returned by default or when `count=true`. Wraps the product results in a pagination envelope.", "properties": { "total": { "type": "integer", "description": "Total number of products." }, "pages": { "type": "integer", "description": "Total number of pages for pagination." }, "currentPage": { "type": "integer", "description": "Current page number." }, "data": { "type": "array", "description": "Array of product result objects.", "items": { "type": "object", "description": "Product result object.", "properties": { "id": { "type": "string", "description": "Unique product identifier (UUID)." }, "name": { "type": "string", "description": "Product name." }, "product_sku": { "type": "string", "description": "Product SKU." }, "image_url": { "type": "string", "description": "Product image URL." }, "categories": { "type": "array", "description": "List of category breadcrumb paths the product belongs to, from the root category to the most specific one. Returns `null` when the product has no categories.", "nullable": true, "items": { "type": "string", "description": "Category breadcrumb path, with levels separated by ` > `." } }, "active": { "type": "boolean", "description": "Indicates whether the product is enabled on the campaign." }, "impressions": { "type": "string", "description": "Total number of ad impressions for the product in the selected date range, regardless of whether the ad became visible to the user." }, "impressions_cost": { "type": "string", "description": "Ad spend attributed to this product's impressions, for impression-billed formats such as CPM." }, "clicks": { "type": "string", "description": "Total number of clicks on the product's ad in the selected date range." }, "clicks_cost": { "type": "string", "description": "Ad spend attributed to this product's clicks, for click-billed formats such as CPC." }, "views": { "type": "string", "description": "Total number of ad views for the product in the selected date range. A view is counted when the ad becomes visible to the user, occupying at least 50% of the viewport for at least 1 second." }, "conversions": { "type": "string", "description": "Total number of conversion events attributed to the product, using last-touch click and view attribution. Each conversion counts once, regardless of how many items it contains. See `conversions_quantity` for the item-level count." }, "conversions_quantity": { "type": "string", "description": "Total quantity of items across all conversions attributed to the product. For example, buying two units in a single conversion increases `conversions_quantity` by 2, while `conversions` increases by 1." }, "conversions_value": { "type": "string", "description": "Total monetary value of the conversions attributed to the product." } } } } } }, { "type": "array", "title": "Array response", "description": "Returned when `count=false`. Contains the product results without the pagination envelope.", "items": { "type": "object", "description": "Product result object.", "properties": { "id": { "type": "string", "description": "Unique product identifier (UUID)." }, "name": { "type": "string", "description": "Product name." }, "product_sku": { "type": "string", "description": "Product SKU." }, "image_url": { "type": "string", "description": "Product image URL." }, "categories": { "type": "array", "description": "List of category breadcrumb paths the product belongs to, from the root category to the most specific one. Returns `null` when the product has no categories.", "nullable": true, "items": { "type": "string", "description": "Category breadcrumb path, with levels separated by ` > `." } }, "active": { "type": "boolean", "description": "Indicates whether the product is enabled on the campaign." }, "impressions": { "type": "string", "description": "Total number of ad impressions for the product in the selected date range, regardless of whether the ad became visible to the user." }, "impressions_cost": { "type": "string", "description": "Ad spend attributed to this product's impressions, for impression-billed formats such as CPM." }, "clicks": { "type": "string", "description": "Total number of clicks on the product's ad in the selected date range." }, "clicks_cost": { "type": "string", "description": "Ad spend attributed to this product's clicks, for click-billed formats such as CPC." }, "views": { "type": "string", "description": "Total number of ad views for the product in the selected date range. A view is counted when the ad becomes visible to the user, occupying at least 50% of the viewport for at least 1 second." }, "conversions": { "type": "string", "description": "Total number of conversion events attributed to the product, using last-touch click and view attribution. Each conversion counts once, regardless of how many items it contains. See `conversions_quantity` for the item-level count." }, "conversions_quantity": { "type": "string", "description": "Total quantity of items across all conversions attributed to the product. For example, buying two units in a single conversion increases `conversions_quantity` by 2, while `conversions` increases by 1." }, "conversions_value": { "type": "string", "description": "Total monetary value of the conversions attributed to the product." } } } } ] }, "examples": { "paginated": { "summary": "Paginated response (default)", "description": "Real response abridged to two products. The `total`, `pages`, and `currentPage` values describe the full result set, so `data` shows fewer products than a complete page.", "value": { "total": 51, "pages": 2, "currentPage": 1, "data": [ { "id": "a9c9e0e8-8e9a-41e5-af26-29f6eb5c3b83", "name": "Extratora de Sujeira e Água e Higienizadora Vertical Wap Comfort Cleaner Pro 2000W 2 em 1 para Tapetes Carpetes e Estofados", "product_sku": "55004728", "image_url": "https://imgs.casasbahia.com.br/55004728/1xg.jpg", "categories": [ "Eletroportáteis", "Eletroportáteis > Aspiradores e Acessórios", "Eletroportáteis > Aspiradores e Acessórios > Aspirador Água e Pó" ], "active": false, "impressions": "0", "impressions_cost": "0", "clicks": "0", "clicks_cost": "0", "views": "0", "conversions": "0", "conversions_quantity": "0", "conversions_value": "0" }, { "id": "2b19df76-0596-43cb-892d-a364dcaaf054", "name": "Lavadora de Alta Pressão WAP Ousada WL 2610 Ultra 1750PSI 1500W – Cinza e Amarelo", "product_sku": "55065795", "image_url": "https://imgs.casasbahia.com.br/55065795/1g.jpg", "categories": [ "Ferramentas", "Ferramentas > Lavadoras de Pressão", "Ferramentas > Lavadoras de Pressão > Lavadoras Residenciais" ], "active": true, "impressions": "0", "impressions_cost": "0.00000000", "clicks": "0", "clicks_cost": "0.00000000", "views": "0", "conversions": "2", "conversions_quantity": "2", "conversions_value": "1107.76" } ] } }, "rawArray": { "summary": "Array response when `count=false`", "description": "Real response abridged to the same two products.", "value": [ { "id": "a9c9e0e8-8e9a-41e5-af26-29f6eb5c3b83", "name": "Extratora de Sujeira e Água e Higienizadora Vertical Wap Comfort Cleaner Pro 2000W 2 em 1 para Tapetes Carpetes e Estofados", "product_sku": "55004728", "image_url": "https://imgs.casasbahia.com.br/55004728/1xg.jpg", "categories": [ "Eletroportáteis", "Eletroportáteis > Aspiradores e Acessórios", "Eletroportáteis > Aspiradores e Acessórios > Aspirador Água e Pó" ], "active": false, "impressions": "0", "impressions_cost": "0", "clicks": "0", "clicks_cost": "0", "views": "0", "conversions": "0", "conversions_quantity": "0", "conversions_value": "0" }, { "id": "2b19df76-0596-43cb-892d-a364dcaaf054", "name": "Lavadora de Alta Pressão WAP Ousada WL 2610 Ultra 1750PSI 1500W – Cinza e Amarelo", "product_sku": "55065795", "image_url": "https://imgs.casasbahia.com.br/55065795/1g.jpg", "categories": [ "Ferramentas", "Ferramentas > Lavadoras de Pressão", "Ferramentas > Lavadoras de Pressão > Lavadoras Residenciais" ], "active": true, "impressions": "0", "impressions_cost": "0.00000000", "clicks": "0", "clicks_cost": "0.00000000", "views": "0", "conversions": "2", "conversions_quantity": "2", "conversions_value": "1107.76" } ] } } } } }, "401": { "description": "Unauthorized\n\nMissing or invalid authentication credentials." }, "404": { "description": "Not Found\n\nCampaign not found." }, "429": { "description": "Too Many Requests\n\nThis endpoint is limited to 100 requests per minute per account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Rate limit error message." } } }, "example": { "error": "Rate limit exceeded for this account" } } } } } } }, "/webhook/marketplace/transfers/{publisher_id}": { "servers": [ { "url": "https://api-retail-media.newtail.com.br", "description": "VTEX Ads server." } ], "post": { "tags": [ "Credit transfer" ], "summary": "Notify credit transfer status", "description": "Notifies VTEX Ads about the final status of a credit transfer that was previously requested by VTEX Ads to the marketplace's `POST /checking_account/transfer` endpoint. The marketplace must call this webhook with the resolved status of each transfer transaction.\r\n\r\n>⚠️ In case of a webhook call failure, the marketplace must retry until a `204 No Content` response is received.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "security": [ { "X-Api-Key": [], "X-Secret-Key": [] } ], "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "publisher_id", "in": "path", "description": "Publisher identifier provided by your account manager.", "required": true, "schema": { "type": "string", "example": "0d675bf6-03f6-4b81-9617-e79dffddc3ab" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "transaction_id", "status" ], "properties": { "transaction_id": { "type": "string", "description": "Identifier of the transfer transaction returned by the marketplace when the transfer was requested." }, "status": { "type": "string", "description": "Final status of the transfer.", "enum": [ "success", "failure" ] }, "message": { "type": "string", "description": "Description of the failure reason. Required when `status` is `failure`." } } }, "example": { "transaction_id": "TRANSACTION_ID", "status": "success" } } } }, "responses": { "204": { "description": "No Content\n\nNotification accepted." }, "401": { "description": "Unauthorized\n\nMissing or invalid authentication credentials." } } } }, "/audience/upload-url": { "servers": [ { "url": "https://api-retail-media.newtail.com.br", "description": "VTEX Ads server." } ], "post": { "tags": [ "Audiences" ], "summary": "Generate audience upload URL", "description": "Returns a short-lived pre-signed Amazon S3 `POST` that lets a publisher upload an audience file without long-lived credentials. The response carries the destination `url` and the signed `fields` that must accompany the upload.\r\n\r\nThe backend builds the object `key` from the authenticated publisher, so a publisher cannot write to another publisher's path. The pre-signed `POST` is valid for `expires_in` seconds (900 by default) and Amazon S3 rejects files larger than `max_bytes` (2 GiB by default).\r\n\r\n>ℹ️ The file upload itself is a separate multipart `POST` request sent directly to Amazon S3 with the returned `url` and `fields`. It is not part of this API. See [Integrating audiences](https://developers.vtex.com/docs/guides/integrating-audiences) for the full flow, file format, and PII hashing rules.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK\n\nPresigned upload URL generated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Amazon S3 endpoint the publisher must send the multipart upload request to." }, "fields": { "type": "object", "description": "Signed Amazon S3 form fields that must be included in the upload request, before the `file` field.", "additionalProperties": { "type": "string", "description": "Value of a signed Amazon S3 form field (for example, policy, signature, or credential)." } }, "key": { "type": "string", "description": "Object key the file will be stored under. Generated by the backend from the authenticated publisher." }, "bucket": { "type": "string", "description": "Name of the Amazon S3 bucket that receives the upload." }, "expires_in": { "type": "integer", "description": "Number of seconds the pre-signed `POST` remains valid.", "default": 900 }, "max_bytes": { "type": "integer", "description": "Maximum file size, in bytes, accepted by Amazon S3. Larger files are rejected.", "default": 2147483648 }, "upload": { "type": "object", "description": "Hints describing how to perform the follow-up upload request.", "properties": { "method": { "type": "string", "description": "HTTP method to use for the upload request." }, "enctype": { "type": "string", "description": "Encoding type to use for the upload request." } } } } }, "example": { "url": "https://newtail-data-clean-room.s3.amazonaws.com/", "fields": { "key": "0d675bf6-03f6-4b81-9617-e79dffddc3ab/audiences/2026/06/03/14/1717340000.parquet.snappy", "Content-Type": "application/octet-stream", "Policy": "eyJleHBpcmF0aW9uIjoiMjAyNi0wNi0wM1QxNDoxNTowMFoiLCJjb25kaXRpb25zIjpbXX0=", "X-Amz-Signature": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" }, "key": "0d675bf6-03f6-4b81-9617-e79dffddc3ab/audiences/2026/06/03/14/1717340000.parquet.snappy", "bucket": "newtail-data-clean-room", "expires_in": 900, "max_bytes": 2147483648, "upload": { "method": "POST", "enctype": "multipart/form-data" } } } } }, "401": { "description": "Unauthorized\n\nMissing or invalid authentication credentials." } } } }, "/sso/marketplace": { "servers": [ { "url": "https://api-retail-media.newtail.com.br", "description": "VTEX Ads server." } ], "post": { "tags": [ "Single sign-on" ], "summary": "Generate seller single sign-on URL", "description": "Generates a redirect URL that allows a seller user to access the VTEX Ads platform without needing to log in again. Use this endpoint to enable a unified login experience for marketplace sellers.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "sso_token", "email", "user_id", "name", "marketplace_name" ], "properties": { "sso_token": { "type": "string", "description": "User identification token generated by the marketplace." }, "email": { "type": "string", "description": "Seller user's email address." }, "user_id": { "type": "string", "description": "Unique identifier of the user in the marketplace." }, "name": { "type": "string", "description": "Seller user's name." }, "marketplace_name": { "type": "string", "description": "Name of the marketplace." } } }, "example": { "sso_token": "sso-token-12345", "email": "seller@example.com", "user_id": "seller123", "name": "Seller Name", "marketplace_name": "My Marketplace" } } } }, "responses": { "200": { "description": "OK\n\nRedirect URL generated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect_url": { "type": "string", "description": "Redirect URL the seller user must follow to access the VTEX Ads platform." } } }, "example": { "redirect_url": "https://app.ads.vtex.com/sso/auth?token=GENERATED_TOKEN" } } } }, "401": { "description": "Unauthorized\n\nMissing or invalid authentication credentials." } } } } }, "components": { "securitySchemes": { "X-App-Id": { "name": "X-App-Id", "type": "apiKey", "in": "header", "description": "Publisher App ID for authorization." }, "X-Api-Key": { "name": "X-Api-Key", "type": "apiKey", "in": "header", "description": "API Key for authentication." }, "X-Secret-Key": { "name": "X-Secret-Key", "type": "apiKey", "in": "header", "description": "Secret key paired with `X-Api-Key` for authenticating webhook calls." } }, "parameters": { "Content-Type": { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, "Accept": { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, "StartDate": { "name": "start_date", "in": "query", "description": "Start date for metrics in `YYYY-MM-DD` format.", "required": true, "schema": { "type": "string", "format": "date", "example": "2025-01-01" } }, "EndDate": { "name": "end_date", "in": "query", "description": "End date for metrics in `YYYY-MM-DD` format.", "required": true, "schema": { "type": "string", "format": "date", "example": "2025-01-31" } }, "Page": { "name": "page", "in": "query", "description": "Page number of the results.", "required": false, "schema": { "type": "integer", "default": 1, "example": 1 } }, "Quantity": { "name": "quantity", "in": "query", "description": "Number of items per page. When `download=true`, the BFF requests up to `20000` rows for XLSX generation.", "required": false, "schema": { "type": "integer", "default": 100, "example": 100 } }, "Count": { "name": "count", "in": "query", "description": "If `true`, returns the total number of available records.", "required": false, "schema": { "type": "boolean", "default": false, "example": false } }, "AccountInfo": { "name": "account_info", "in": "query", "description": "If `true`, includes detailed account information in the result.", "required": false, "schema": { "type": "boolean", "default": false, "example": false } }, "Download": { "name": "download", "in": "query", "description": "If `true`, returns an XLSX file buffer for download instead of JSON.", "required": false, "schema": { "type": "boolean", "default": false, "example": false } }, "OrderDirection": { "name": "order_direction", "in": "query", "description": "Sort direction.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "example": "desc" } } } }, "security": [ { "X-App-Id": [], "X-Api-Key": [] } ], "tags": [ { "name": "Catalog synchronization" }, { "name": "Audiences" }, { "name": "Ads events notification" }, { "name": "Ads" }, { "name": "Reports" }, { "name": "Credit transfer" }, { "name": "Single sign-on" } ] }