This document describes how to integrate VTEX Ads with external marketplaces through bidirectional authentication, catalog synchronization, and unified campaign management.

Authentication occurs bidirectionally, both from the marketplace to VTEX Ads and from VTEX Ads to the marketplace.

The connection requires adding two parameters in the request headers sent to VTEX Ads.

Header	Description
x-app-id	The App ID identifies the API user
x-api-key	The API Key identifies the API "password"

Access credentials must be requested from our Support team.

In this scenario, the connection will be from VTEX Ads to the marketplace. To standardize this integration, we will use Basic Authentication format in the request.

Authentication	Description
username	Username for authentication
password	User password

For more information about Basic Authentication functionality, see the RFC 7617 specification.

The catalog API enables product synchronization between marketplaces and VTEX Ads. All product data must include the following attributes:

Attribute	Description	Type	Required
product_sku	Unique identifier of the parent product	String	Yes
name	Product title	String	Yes
image_url	Public product image URL, can be just a thumbnail	String	No
categories	List of categories	String	Yes
brand	Product brand name	String	Yes
gtins	List of EANs	Array	No
urls	Product URL information	Array	Yes
urls.site	Site brand name	String	No
urls.url	Product URL	String	Yes
stocks	Product stock information	Array	Yes
stocks.site	Site brand name	String	No
stocks.seller_id	Seller ID identifier	String	No
stocks.quantity	Stock quantity	Float	Yes
metadata	Information returned during ad queries without modification	Object<String, String>	No

For this step, we need an API to query the retailer's catalog, and this catalog must contain:

Attribute	Description
seller_id	Filter by seller identifier.
name	Partial search by product name.
skus	Filter by a list of SKUs.
eans	Filter by a list of EANs.
quantity	Number of items that should be returned.
page	Current page number. Starts at 0 (zero).

GET PREFIX/search?name=&seller_id=&skus=sku1,sku2,...,skuN&eans=ean1,ean2,...,eanN&quantity=&page=  

[
  {
    "product_sku": "sku123",
    "name": "Red Sneakers",
    "image_url": "https://example.com/image.jpg",
    "categories": "Sports/Shoes",
    "brand": "Nike",
    "gtins": ["1234567890123"],
    "urls": [
      {
        "site": "example-store",
        "url": "https://example.com/product/red-sneakers"
      }
    ],
    "stocks": [
      {
        "site": "example-store",
        "seller_id": "seller123",
        "quantity": 10
      }
    ],
    "metadata": {
      "color": "red",
      "size": "42"
    }
  }
]

Any status other than 200 is considered an error.

The Advertiser entity manages sellers and their associated data.

Endpoints	Description	Filters
GET /api/v1/advertisers	Search advertisers	quantity, page, name, seller_id
POST /api/v1/advertisers	Create advertiser	-
GET /api/v1/advertisers/:seller_id	Get advertiser by seller ID	-
PATCH /api/v1/advertisers/:seller_id	Update advertiser by seller ID	-

The Campaigns entity manages advertising campaign creation and updates.

Endpoints	Description	Filters
GET /api/v1/campaigns	List campaigns	seller_id, page, quantity, name, status, ad_type
POST /api/v1/campaigns	Create campaign	-
GET /api/v1/campaigns/:campaign_id	Get campaign by ID	-
PATCH /api/v1/campaigns/:campaign_id	Update campaign by ID	-

The Metrics entity provides macro and historical performance data for campaigns.

Endpoints	Description	Filters
GET /api/v1/metrics/macro/campaigns	Get macro metrics	start_at, end_at, campaign_id, seller_id
GET /api/v1/metrics/history/campaigns	Get historical metrics	start_at, end_at, campaign_id, seller_id

The Credits entity manages advertiser account balances and transactions.

Endpoints	Description	Filters
GET /api/v1/checking_accounts	List advertiser credit accounts	seller_id, page, quantity
GET /api/v1/checking_accounts/:seller_id/transactions	List credits for an account	page, quantity
POST /api/v1/checking_accounts/:seller_id/transactions	Add credits to an account	-

Endpoints	Description	Filters
GET /api/v1/payments	List payments	seller_id, page, quantity
POST /api/v1/payments/:payment_type	Create a new payment that will add credits	-
GET /api/v1/payments/:payment_id	Query a payment	-

The goal is that once the customer is connected to the marketplace platform, they can reuse that login when connecting to the Retail Media platform.

Any status other than 200 is considered an error.

Authentication uses a JWT token with a shared secret. The token must contain:

• publisher_id: Retailer ID on VTEX Ads.
• seller_id: Seller ID in the marketplace.
• user_id: User ID in the marketplace.
• 24h expiration time

GET https://app.ads.vtex.com/login/marketplace?sso=JWT

The marketplace must provide an endpoint to query user information by user ID that returns the following fields:

• name
• email

GET PREFIX/users/:user_id?seller_id=&publisher_id=

The marketplace must provide an endpoint to query seller information that returns the following fields:

• name
• cnpj (tax ID)

GET PREFIX/sellers/:seller_id?publisher_id=

SSO v2 allows retailers to send seller and user information to the VTEX Ads authentication API. VTEX Ads returns a redirect URL for the end user.

Authentication follows the same model described in the Authentication section.

POST https://api-retail-media.newtail.com.br/sso/marketplace

For the full request and response specification, see Generate seller single sign-on URL in the VTEX Ads API reference.

{
  "sso_token": "user-identification-token",
  "email": "user@example.com",
  "user_id": "user123",
  "name": "User Name",
  "marketplace_name": "Marketplace Name"
}

Success - Status 200

{
  "url_redirect": "https://app.ads.vtex.com/login/marketplace?token=JWT"
}

Failure

• Status 400 - Validation error

  {
    "message": "ValidationError",
    "errors": []
  }
  

• Status 500 - Internal application error

  {
    "message": "InternalServerError"
  }