VTEX attribution: how to know which channel produces your sales

My store runs on VTEX. How do I know which channel is actually producing my sales?

VTEX is one of the most common platforms among large Latin American retailers, and most attribution advice is written for Shopify. That gap shows up in practice: pixels that never fire in the checkout, orders that reach Meta three times, dashboards that disagree with VTEX's own reports. This guide covers what VTEX records about the origin of a sale, where it stops, and how to connect Meta, Google and GA4 so the numbers can be trusted.

What VTEX already records

Every VTEX order carries an orderForm, and the orderForm has a marketingData object with the campaign data captured before checkout: utmSource, utmMedium and utmCampaign, VTEX's internal campaign fields (utmiCampaign, utmiPart, utmipage) and the coupon, if one was used.

That is genuinely useful and free: you can export orders and group them by source and campaign. But it is a last-touch record of the tagged visit that led to checkout. It does not know about the Meta ad the buyer clicked three days earlier, a visit without tags, or the Google search that came before.

Where VTEX attribution breaks

The checkout is a separate application. VTEX serves its checkout apart from the storefront, as a single-page application. Tags added to the storefront, including through a tag manager, may not load there, so checkout and purchase events never fire while the order exists in VTEX. If your GA4 or Meta pixel shows far fewer purchases than VTEX, this is the first thing to check.

The order arrives as a series of events. VTEX's Feed v3 and Hook guide describes the feed as a list of order updates, not a list of orders: each status change, such as payment approved and then shipping authorized, is a new event for the same order. An integration that sends a purchase to an ad platform on every event sends one sale several times.

Listing orders is not a reliable way to find them. The same guide says the List orders API only returns orders that are already indexed, that it is slower than the feed, and that integrations built on it should migrate to the feed. A backfill or report built by listing orders can come up short with no error anywhere, so always compare its counts with VTEX's own order report.

Several storefronts, one account. Many retailers run more than one storefront on a single VTEX account. Depending on how sales channels and hostnames are configured, an order may not say which storefront the buyer was on, so attribution has to decide it from other signals. Ask any tool how it does that.

Currency and time zone. VTEX records orders in your store's currency and time zone. Your ad accounts may bill in dollars and close their day at another hour, so daily comparisons will not line up until both are normalized.

How to set it up properly

• Take the purchase from VTEX, not from the browser. Use the order feed or hook as the source of truth for orders. The pixel is for the journey: visits, clicks and product views.
• Install the pixel where it runs. Make sure your tags load in the checkout as well as the storefront, following VTEX's options for adding scripts to checkout. If ad blockers are a concern, a first-party route through your own domain keeps more of the journey visible.
• Send conversions from the server once per order. For Meta's Conversions API and Google's conversion uploads, keep a record that an order was already sent, so a second status event does not resend it.
• Use the order number as the event ID. Meta deduplicates a server event against a browser event only when both carry the same event ID. The order number is the one value both sides know.
• Keep the marketingData. Store the order's UTMs along with the tool's own attribution, so you can always compare the two.

Connecting Meta, Google and GA4

Meta: send Purchase events through the Conversions API from your server, with the order number as event_id and hashed customer data, and keep the browser pixel for the journey. Google Ads: upload conversions from the server with the click identifier (gclid, gbraid or wbraid) captured when the buyer arrived; an order without one cannot be uploaded as a click conversion. GA4: make sure the purchase event fires in checkout, or send it from the server, and add the refund event when orders are refunded. We explain the Google side in Google Enhanced Conversions and the server side in server-side tracking.

The check that tells you it is working

For one week, compare three numbers in the same time zone: orders settled in VTEX, purchases each ad platform claims, and purchases your tools attribute to each channel. The attributed total should never exceed VTEX's orders. If it does, something is counting the same order twice. If each platform claims far more than the orders it could have influenced, read why Meta, Google, GA4 and your store never match.

How Adray handles VTEX

Adray receives VTEX orders through the platform's order hook, keeps the order's marketingData, stitches each order to the session and click that produced it, and sends purchases to Meta's Conversions API from the server once per order, with the order number as the event ID. Its pixel can run through a first-party route on your own domain on VTEX IO. VTEX appears with the other supported platforms on the integrations page. If your catalog also sells on marketplaces, the limits are different, and we cover them in attribution on Tiendanube and Mercado Libre.