vtexads-api-docs

5.2. Catalog Synchronization

The first step is synchronization, which occurs on two fronts:

Note for VTEX stores: For stores on the VTEX platform, catalog synchronization occurs transparently, with no additional integration required for this purpose.

Product Synchronization

Sends product registration information. Requires authentication.

Field Description Type Required?
product_sku Unique product ID/SKU. String Yes
parent_sku Parent product SKU (for variations). String No
name Product name. String Yes
url Canonical URL of the product page. String Yes
image_url URL of the main product image. String No
categories List of categories. Array[String] Yes
brand Product brand. String No
gtins Barcodes (EAN). Required for campaigns on the VTEX Ads Network. Array[String] No/Yes
tags “Tags” to contextualize searches. Max 10 per SKU, 64 chars per tag. Only for product campaigns. Array[String] No
sellers List of sellers who sell the product (in a marketplace). Array[String] No
metadata Object for additional information (key-value). Object No

Structuring Categories

Important: The categories field is crucial for campaign targeting and product organization. It must be structured hierarchically, representing the full path from the root category to the product’s specific category.

The categories field must be an array of strings, where each string is a level of the category tree. The hierarchy is built by sending all parent categories up to the most specific one.

Correct Example:

For a product in the “For Women” perfume category, the categories array should be:

"categories": [
    "Beauty",
    "Beauty > Fragrances",
    "Beauty > Fragrances > Perfume",
    "Beauty > Fragrances > Perfume > For Women"
]

This structure allows the platform to understand the product’s context at all levels, from the broadest (“Beauty”) to the most specific (“For Women”).

Request Example:

curl --location 'https://api-retail-media.newtail.com.br/product/bulk/products' \
--header 'x-app-id: XXXX' \
--header 'x-api-key: YYYY' \
--header 'Content-Type: application/json' \
--data '[
    {
        "product_sku": "allan",
        "name": "allan",
        "url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616",
        "image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629",
        "categories": [
            "Beauty",
            "Beauty > Fragrances",
            "Beauty > Fragrances > Perfume",
            "Beauty > Fragrances > Perfume > For Women"
        ],
        "brand": "SALVADOR DALÍ",
        "profit_margin": null,
        "gtins": [
            "3331438450103"
        ],
        "sellers": [],
        "skus": []
    },
    {
        "product_sku": "allan2",
        "name": "allan2",
        "url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616",
        "image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629",
        "categories": [
            "Beauty",
            "Beauty > Fragrances",
            "Beauty > Fragrances > Perfume",
            "Beauty > Fragrances > Perfume > For Women"
        ],
        "brand": "SALVADOR DALÍ",
        "profit_margin": null,
        "gtins": [
            "3331438450103"
        ],
        "sellers": [],
        "skus": [],
        "tags": ["Abart", "Mega Maio"]
    }
]'

Success Response Example:

Status: 202 Accepted
Content-Type: application/json

{
    "messages": [
        "products will be processed soon"
    ]
}

Inventory Synchronization

Sends price and stock information for products. Requires authentication.

Field Description Type Required?
product_sku Unique product ID/SKU. String Yes
price Current product price. Float Yes
promotional_price “From” price (list/original). Float Yes
is_available Available product (in stock). Boolean Yes
store_id Store ID. If store_id is not provided, it will be interpreted as meaning this inventory information will be used for all stores. String No
metadata Object for additional information (key-value). Object No

Request Example:

curl --location 'https://api-retail-media.newtail.com.br/product/bulk/inventories' \
--header 'x-app-id: XXXX' \
--header 'x-api-key: YYYY' \
--header 'Content-Type: application/json' \
--data '[
    {
      "product_sku": "120210",
      "store_id": "1",
      "price": 18.20,
      "promotional_price": 16.32,
      "is_available": true
    },
    {
      "product_sku": "120212",
      "price": 18.20,
      "promotional_price": 0, // Remove promotional price
      "is_available": true
    }
]'

Success Response Example:

Status: 202 Accepted
Content-Type: application/json

{
    "messages": [
        "inventory will be processed soon"
    ]
}

Best Practices for Synchronization

  1. Complete Initial Synchronization:
    • Send the entire catalog in the first synchronization.
    • Divide into batches of up to 500 products to avoid timeouts.
  2. Incremental Updates:
    • After the initial synchronization, send only new or changed products.
    • Keep a record of the last modification date of each product.
  3. Update Frequency:
    • Prices and stock: Update at least once a day, ideally in real-time for significant changes.
    • Registration information: Update when there are changes.
  4. Error Handling:
    • Implement retries with exponential backoff for temporary failures.
    • Monitor API responses to identify persistent problems.
  5. Data Validation:
    • Verify that all required fields are filled in.
    • Ensure that product and image URLs are valid and accessible.
    • Make sure categories follow the recommended hierarchical structure.