Convert Integration: VTEX

IN THIS ARTICLE YOU WILL:

• Get an Overview
• Understand the Prerequisites
• Install the Convert Tag
• Add the snippet
• Set up Revenue Tracking
• Send Call for Order Confirmation
• Verify the Setup
• Troubleshoot

Overview

This article covers two things: installing the Convert tag on a VTEX store, and tracking revenue so experiment reports show revenue per visitor and conversion value. VTEX stores run on VTEX IO (Store Framework) or the legacy CMS Portal; both are covered below.

Pre-requisites

• A Convert account with a project and a Web experiments domain set up
• Your Convert project tracking code (Project Settings > Tracking Code)
• A revenue goal in the project (Goals > Add New Goal > Revenue Tracking)
• Admin access to your VTEX account
• A test order you can place (a staging account or a 100% discount code works well)

Installing the Convert tag

The Convert tag must load synchronously, as high in the page <head> as possible, on every page of the store (including the checkout and order confirmation pages). Google Tag Manager is not recommended for this integration, because it delays the tag and can cause flicker.

Add the snippet to your VTEX store

In Convert, open your project and go to Project Settings > Tracking Code, and copy the snippet. It looks like this, with your own account and project IDs:

<script src="//cdn-4.convertexperiments.com/v1/js/ACCOUNT_ID-PROJECT_ID.js"></script>

Paste it using the method that matches your store:

VTEX IO (Store Framework): add the snippet to the <head> of your store theme, for example in the theme's store/ template or a custom head app, then publish the theme workspace to master.

Legacy CMS Portal: go to Storefront > Layout, open the HTML template used by your pages, and paste the snippet as the first script inside <head>. Repeat for the shared header template if your store uses one.

Checkout: go to Store Settings > Checkout > Settings > Checkout code and paste the snippet in the Header code section so it also loads in checkout and on the order confirmation page.

After adding the snippet, open your store in a private window and view the page source or the browser console. Typing convert in the console should return an object, not an error.

Setting up revenue tracking

Revenue tracking works by firing a Convert revenue call once per completed order, with the order total and item count. On VTEX, the order confirmation page (/checkout/orderPlaced/) exposes this data, and VTEX also pushes it to the dataLayer as an orderPlaced event.

Step 1: Create the revenue goal in Convert

1. In your Convert project, go to Goals and click Add New Goal.
2. Choose Revenue Tracking as the goal type and give it a clear name, such as "VTEX Purchase Revenue".
3. Set the trigger to Advanced / Triggered Manually (the tag fires it from code), then save.
4. Note the goal ID shown in the goal list. You need it in the snippet below.
5. Attach the goal to every experiment where you want to report revenue.

Step 2: Send the revenue call on the order confirmation page

The call below pushes the order total, number of items and goal ID to Convert. Replace YOUR_GOAL_ID with the ID from Step 1.

window._conv_q = window._conv_q || [];
_conv_q.push(["pushRevenue", orderTotal, productsCount, "YOUR_GOAL_ID"]);

orderTotal is a number with a dot as the decimal separator (for example 149.90), without a currency symbol. productsCount is the total quantity of items in the order.

Send the call from the order confirmation page

VTEX IO exposes order data to custom pixels through the vtex:orderPlaced event. If you manage a custom pixel app, listen for it and push the revenue call:

window.addEventListener("message", function (e) {
 if (!e.data || e.data.eventName !== "vtex:orderPlaced") return;
 var o = e.data;
 var count = (o.transactionProducts || []).reduce(function (n, p) {
 return n + (parseInt(p.quantity, 10) || 1);
 }, 0);
 window._conv_q = window._conv_q || [];
 _conv_q.push(["pushRevenue", parseFloat(o.transactionTotal) || 0, count, "YOUR_GOAL_ID"]);
});

On the legacy CMS Portal, add the revenue call to the order confirmation template (Storefront > Layout > the checkout orderPlaced page), reading the total from the order data VTEX renders on that page.

Verifying the setup

Test the tag and the revenue call with one real order before you launch any experiment.

1. Check the tag. Open the store in a private window. In the browser console, type convert. It should return an object. In the Network tab, filter for convertexperiments and confirm the project script loads with status 200 on the home, product, cart, checkout and order confirmation pages.
2. Place a test order. Use a staging account or a 100% discount code. Stay on the order confirmation page.
3. Check the revenue call. In the Network tab, filter for convertexperiments and look for a request that carries your goal ID and the order amount. In the console, _conv_q should contain a pushRevenue entry with the right total.
4. Check Convert. In Convert, open an experiment that uses the revenue goal and confirm the conversion appears under Reports, or use the Live Logs view in the project to see the event arrive. Reports can take a few minutes to update.
5. Remove test data. Exclude your test traffic with an IP or cookie audience filter so it does not affect results.

Troubleshooting and FAQ

The Convert tag loads on the store but not in checkout. VTEX checkout is a separate application. Add the snippet in Store Settings > Checkout > Settings > Checkout code.

Pages flicker when experiments run. The tag is loading too late. Move it to the top of <head>, load it synchronously, and do not load it through a tag manager.

No revenue appears in Convert. Check that the goal ID in the snippet matches the goal in Convert, that the goal is attached to the experiment, and that the visitor was bucketed into the experiment before the purchase. Revenue is only attributed to visitors who saw an experiment.

Revenue is doubled. The order confirmation page was reloaded or the tag fires twice (for example in both the theme and a custom pixel). Keep only one revenue call and add the sessionStorage order ID guard.

Revenue is 100 times too high or low. The order total is in cents. Divide by 100 before sending, or use the item prices from transactionProducts.

Do I need a separate integration or app from the VTEX App Store? No. The tag and the revenue call are added with the steps above. No VTEX app is required for Convert.

Open items to confirm before publishing: the exact VTEX Admin menu names change between versions, and the Convert call syntax should be checked against the current Convert tracking documentation. Please test the steps in a VTEX staging account first.