VTEX Ads Core Package Custom Hydration

Build your own hydration strategy to fetch product data and associate it with ad offers using custom fetchers and matchers.

By default, VTEX Ads expects you to provide a hydration strategy that defines how to fetch product data and how to associate it with the offers returned by the ad server. This gives you full control over where and how product data is retrieved — whether it’s via a REST API, a GraphQL endpoint, or any custom service.

To build your own hydration strategy, you’ll need to implement two functions:

Fetcher: a function that receives a list of ad offers and returns the corresponding product data.
Matcher: a function that determines which offer belongs to which product, so they can be merged into hydrated ads.

Below are a couple of examples to help you get started, using both a REST API and a GraphQL endpoint.

REST API hydration


_24const customRestFetcher = async (offers, identity) => {
_24  const skuIds = offers.map((offer) => offer.skuId);
_24
_24  const response = await fetch(`/api/products/batch`, {
_24    method: "POST",
_24    headers: {
_24      "Content-Type": "application/json",
_24    },
_24    body: JSON.stringify({
_24      skuIds,
_24      accountName: identity.accountName,
_24    }),
_24  });
_24
_24  if (!response.ok) {
_24    throw new Error(`Failed to fetch products: $\{response.statusText\}`);
_24  }
_24
_24  return response.json();
_24};
_24
_24const customMatcher = (product, offer) => {
_24  return product.skuId === offer.skuId && product.sellerId === offer.sellerId;
_24};

GraphQL hydration


_37const graphqlFetcher = async (offers, identity) => {
_37  const skuIds = offers.map((offer) => offer.skuId);
_37
_37  const query = `
_37    query GetProducts($skuIds: [String!]!) \{
_37      products(skuIds: $skuIds) \{
_37        id
_37        sku
_37        name
_37        price
_37        description
_37        images
_37        brand
_37        seller \{
_37          id
_37          name
_37        \}
_37      \}
_37    \}
_37  `;
_37
_37  const response = await fetch("/graphql", {
_37    method: "POST",
_37    headers: { "Content-Type": "application/json" },
_37    body: JSON.stringify({
_37      query,
_37      variables: { skuIds },
_37    }),
_37  });
_37
_37  const data = await response.json();
_37  return data.data.products;
_37};
_37
_37const customMatcher = (product, offer) => {
_37  return product.sku === offer.skuId && product.seller.id === offer.sellerId;
_37};