Shopify

This page adds the Grain Tag to the theme.liquid file of your Shopify theme. Then it adds events for product views, cart additions, checkouts, purchases, and searches. It takes about 10 minutes.

Before you start

You need three things:

Admin access to your Shopify store.
Your tenant alias from the dashboard. It is the alias shown at the top of the dashboard, not the UUID.
10 minutes.

Duplicate your theme before you edit code. Go to Themes, then Actions, then Duplicate. If an edit breaks the theme, you can publish the copy.

1. Open the theme code

Log in to Shopify admin.
Click Online Store, then Themes.
Find your active theme. It has the “Current theme” badge.
Click Actions, then Edit code.

2. Edit theme.liquid

In the file list, open the Layout folder.
Click theme.liquid.
Find the </head> tag. Use Ctrl+F or Cmd+F to search.
Add this code directly before </head>:

<script src="https://tag.grainql.com/v4/your-tenant-id.js"></script>
<script>
  GrainTag.track('page_context', {
    page_type: '{{ template }}',
    shop: '{{ shop.name }}',
    currency: '{{ shop.currency }}'
  });
</script>

Replace your-tenant-id with your tenant alias. {{ template }}, {{ shop.name }}, and {{ shop.currency }} are Liquid variables. Shopify replaces them with the real values when it serves the page.

3. Save

Click Save (top right). Shopify shows a confirmation message. The Grain Tag now records page views, clicks, and scroll depth on every page of the store. Read Automatic tracking.

4. Track e-commerce events

Each snippet in this step sends one event with GrainTag.track. If a snippet runs before the script is ready, the Grain Tag queues the event and sends it later.

Add to cart

In theme.liquid, add this code directly before </body>:

<script>
  document.addEventListener('DOMContentLoaded', function() {
    const cartForms = document.querySelectorAll('form[action*="/cart/add"]');

    cartForms.forEach(function(form) {
      form.addEventListener('submit', function() {
        const variantId = form.querySelector('[name="id"]')?.value;
        const quantity = form.querySelector('[name="quantity"]')?.value || 1;

        GrainTag.track('product_added_to_cart', {
          variant_id: variantId,
          quantity: parseInt(quantity)
        });
      });
    });
  });
</script>

Checkout started

Add this code after the add-to-cart snippet:

<script>
  document.addEventListener('DOMContentLoaded', function() {
    const checkoutButtons = document.querySelectorAll('button[name="checkout"], a[href*="/checkout"]');

    checkoutButtons.forEach(function(button) {
      button.addEventListener('click', function() {
        GrainTag.track('checkout_started', {
          page: window.location.pathname
        });
      });
    });
  });
</script>

Purchases

The order status page is not part of the theme. Go to Settings, then Checkout, then Order status page, then Additional scripts, and add this code:

<script src="https://tag.grainql.com/v4/your-tenant-id.js"></script>
<script>
  GrainTag.track('purchase_completed', {
    order_id: '{{ checkout.order_id }}',
    total: {{ checkout.total_price | money_without_currency }},
    currency: '{{ checkout.currency }}',
    discount: {{ checkout.total_discounts | money_without_currency }},
    shipping: {{ checkout.shipping_price | money_without_currency }}
  });
</script>

Order status scripts are available in Settings, then Checkout, on Shopify Plus or certain themes.

Product views

Add this code in theme.liquid. The {% if %} tag limits it to product pages:

{% if template == 'product' %}
<script>
  GrainTag.track('product_viewed', {
    product_id: '{{ product.id }}',
    product_title: '{{ product.title }}',
    price: {{ product.price | money_without_currency }},
    vendor: '{{ product.vendor }}',
    available: {{ product.available }}
  });
</script>
{% endif %}

Searches

Add this code in theme.liquid. It runs on the search results page only:

{% if template == 'search' %}
<script>
  GrainTag.track('search_performed', {
    query: '{{ search.terms }}',
    results_count: {{ search.results.size }}
  });
</script>
{% endif %}

Read Name events for the naming convention.

5. Test the installation

Open your store in a private (incognito) window.
Open a product page, add the product to the cart, and go to checkout.
Open the browser console (F12, then Console).
Type window.GrainTag. The console shows the GrainTag object.
Open the dashboard and make sure that the events are there.

Troubleshooting

Symptom	Cause	What to do
The code does not run	The tenant alias in the script URL has a typo	Compare the alias with the one at the top of the dashboard.
The code does not run	The browser holds an old copy of the page	Reload without the cache: Ctrl+Shift+R or Cmd+Shift+R.
The code does not run	A script on the page fails	Open the console (F12) and read the errors.
The code does not run	The code is not before `</head>` or `</body>`	Move the code to the position that the step names.
Events are not in the dashboard	Events arrive after a delay of up to 30 seconds	Wait 30 seconds, then reload the dashboard.
Events are not in the dashboard	The theme file is not saved	Open `theme.liquid` and click Save.
Events are not in the dashboard	The script did not load	Type `window.GrainTag` in the console. The console must show the `GrainTag` object.
The theme is broken	A Liquid tag (`{{ }}` or `{% %}`) was deleted during the edit	Make sure that every Liquid tag is intact. To revert, go to Themes, then Actions, then Unpublish, and publish your backup.

Read Troubleshooting for cases that are not specific to Shopify.

Next steps

Trackers

Track clicks on specific elements from the dashboard, without code.

Heatmaps

See where visitors click and how far they scroll.

Tracks

Build funnels from landing page to purchase.

Privacy and consent

What Grain stores, cookieless mode, and consent modes.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

Before you start

1. Open the theme code

2. Edit theme.liquid

3. Save

4. Track e-commerce events

Add to cart

Checkout started

Purchases

Product views

Searches

5. Test the installation

Troubleshooting

Next steps

Trackers

Heatmaps

Tracks

Privacy and consent

​Before you start

​1. Open the theme code

​2. Edit theme.liquid

​3. Save

​4. Track e-commerce events

​Add to cart

​Checkout started

​Purchases

​Product views

​Searches

​5. Test the installation

​Troubleshooting

​Next steps

Trackers

Heatmaps

Tracks

Privacy and consent

Before you start

1. Open the theme code

2. Edit theme.liquid

3. Save

4. Track e-commerce events

Add to cart

Checkout started

Purchases

Product views

Searches

5. Test the installation

Troubleshooting

Next steps