How can I load Instant's pixels via Google Tag Manager for a Custom Store?

Instant supports integration with custom or headless storefronts — including sites built using frameworks like React, Next.js, or PWAs, and eCommerce platforms such as WooCommerce, Salesforce Commerce Cloud, or custom APIs.

If you’re using Google Tag Manager (GTM) to manage your tracking scripts, you can install Instant’s Pixels entirely through GTM, eliminating the need to directly modify your site’s source code.

Please note that incorrect GTM configuration may prevent Instant from identifying visitors or tracking key events.

Overview

Instant’s tracking for a Custom Store consists of two parts:

Part	Purpose	GTM Implementation
Theme Pixel	Identifies visitors and tracks on-site behaviour (page views, product views, cart adds).
Customer Events Tracking	Sends customer events (e.g. add to cart, checkout started) to Instant, which are then forwarded to your connected marketing platform (e.g. Klaviyo).	Configured via GTM event triggers.

Add the Theme Pixel via GTM

The Theme Pixel loads the Instant library (instant.js) onto your website, allowing Instant to identify anonymous shoppers.

Step 1: Inject the Theme Pixel via GTM (Custom HTML Tag)

Go to your Google Tag Manager Dashboard.
Click on Tags > New > Tag Configuration > Custom HTML.
Paste the following script and click Save.

<script>
!function(i,n,s,t,a,u,d){
    i.InstantConfig = i.InstantConfig || {};
    d = i.InstantJS = i.InstantJS || {};
    d.trackQueue = [];
    d.track = function() { d.trackQueue.push(arguments) };
    u = n.createElement(s);
    u.async = true;
    u.src = t;
    a = n.getElementsByTagName(s)[0];
    a.parentNode.insertBefore(u, a);
}(window, document, 'script', 'https://cdn.instant.one/instant.js?siteId={{SITE_ID}}');
</script>

Replace with your actual Instant Site ID.
Set the trigger to All Pages so the pixel loads on every page.
Click Save.

💡 This ensures InstantJS loads globally and initialises as soon as possible in the page load sequence.

Step 2: Create Data Layer Variables for Custom Events

To send events from your site through GTM to Instant, GTM needs to receive event payloads via the dataLayer.

If your site already pushes data to the dataLayer, you can reuse those. Otherwise, you’ll need to add new pushes for key eCommerce events.

Example: Pushing Events to the Data Layer

When a customer performs an action (e.g., adds an item to their cart), push an event into the dataLayer with its payload:


window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  event: "ITEM_ADDED_TO_CART",
  event_payload: {
    provider: "KLAVIYO",
    event: {
      CheckoutURL: "/checkout",
      Items: [
        {
          ProductName: "Wireless Blender",
          Quantity: "1",
          ItemPrice: "59.99",
          ImageURL: "https://example.com/blender.jpg"
        }
      ]
    }
  }
});

The event_payload object here corresponds to the same structure you would normally pass directly to Klaviyo.

Repeat this for all the events you want to track. At a minimum, Instant requires:

PAGE_VIEWED
COLLECTION_VIEWED
PRODUCT_VIEWED
ITEM_ADDED_TO_CART
CART_VIEWED
CHECKOUT_STARTED

Step 3: Create Data Layer Variable in GTM

In GTM:

Go to Variables → New → Variable Configuration → Data Layer Variable.
Set Variable Name to event_payload.
Click Save.

Step 4: Create Custom Event Triggers in GTM

Now, create one trigger per event type you plan to send to Instant.

For example:

Go to Triggers → New → Trigger Configuration → Custom Event.
Set the Event Name to match your dataLayer event (e.g., ITEM_ADDED_TO_CART).
Select All Custom Events.
Click Save.

Repeat for:

PAGE_VIEWED
COLLECTION_VIEWED
PRODUCT_VIEWED
ITEM_ADDED_TO_CART
CART_VIEWED
CHECKOUT_STARTED

Step 5: Create Instant Event Tags in GTM

For each event type, create a new tag that sends the dataLayer payload to Instant.

Go to Tags → New → Tag Configuration → Custom HTML.
Paste the following code:

<script>
InstantJS.track('SHOPIFY_EVENT', {{raw_event}});
</script>

Replace:

- → The event type, e.g. ITEM_ADDED_TO_CART
- → The GTM variable you created earlier (event_payload)

Assign the corresponding trigger (e.g. trigger for ITEM_ADDED_TO_CART). And click Save.

Repeat this for each of your tracked events.

Step 6: Updating Event Payloads for Klaviyo

Make sure the event properties you pass in the event_payload match the properties used in your email templates (e.g., event.product_name, event.image_url).

If your Klaviyo templates use different field names than shown in the example snippets, update your payloads accordingly.

We understand that there are many different ways to set up GTM, so our support team are always happy to help.

Please reach out to Instant support at help@instant.one, or your dedicated customer success manager for further assistance if needed.