Shopify

Understand how customers navigate your Shopify store. See what paths lead to purchases and where people drop off.

Back up your theme first! Go to Themes → Actions → Duplicate before editing code. This gives you an easy rollback.

What You’ll Need

Admin access to your Shopify store
Your Grain tenant ID from grainql.com/dashboard
10 minutes

Step 1: Open Theme Code

Log into Shopify admin
Click Online Store → Themes
Find your active theme (has “Current theme” badge)
Click Actions → Edit code

Step 2: Edit theme.liquid

In the file list, find Layout folder
Click theme.liquid
Find the </head> tag (use Ctrl+F / Cmd+F to search)
Add this code right before </head>:

<!-- Grain Analytics -->
<script src="https://tag.grainql.com/v4/your-tenant-id.js"></script>
<script>
  // SDK auto-initializes with page tracking
  // Track additional Shopify context
  const grain = GrainTag.getInstance();
  
  grain.track('page_context', {
    page_type: '{{ template }}',
    shop: '{{ shop.name }}',
    currency: '{{ shop.currency }}'
  });
</script>

Replace your-tenant-id with your tenant identifier (not UUID)!

Those {{ template }} and {{ shop.name }} things are Liquid variables—Shopify automatically fills them in with real values.

Step 3: Save

Click Save (top right). You’ll see a confirmation message. That’s it! Grain is now tracking your store. 🎉

Track E-commerce Events

Let’s track the important stuff: cart additions, checkouts, and purchases.

Track “Add to Cart”

Still in theme.liquid, add this just before </body>:

<script>
  document.addEventListener('DOMContentLoaded', function() {
    // Track add to cart clicks
    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;
        
        if (window.grain) {
          grain.track('product_added_to_cart', {
            variant_id: variantId,
            quantity: parseInt(quantity)
          });
        }
      });
    });
  });
</script>

Track Checkout Started

<script>
  document.addEventListener('DOMContentLoaded', function() {
    const checkoutButtons = document.querySelectorAll('button[name="checkout"], a[href*="/checkout"]');
    
    checkoutButtons.forEach(function(button) {
      button.addEventListener('click', function() {
        if (window.grain) {
          grain.track('checkout_started', {
            page: window.location.pathname
          });
        }
      });
    });
  });
</script>

Track Purchases

For completed orders, add this to Settings → Checkout → Order status page → Additional scripts:

<script src="https://tag.grainql.com/v4/your-tenant-id.js"></script>
<script>
  // SDK auto-initializes, get the instance
  const grain = GrainTag.getInstance();
  
  grain.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: Available in Settings → Checkout on Shopify Plus or certain themes.

Track Product Views

Add this in theme.liquid to track product page visits:

{% if template == 'product' %}
<script>
  if (window.grain) {
    grain.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 %}

Track Search

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

Test Your Integration

Open your store in an incognito/private window
Browse a product, add to cart, go to checkout
Open browser console (F12 → Console)
Type window.grain — you should see the Grain object
Check your Grain dashboard for events

Debug mode: Temporarily add debug: true to see console logs:

window.grain = Grain.createGrainAnalytics({
  tenantId: 'your-tenant-id',
  debug: true // Remove before going live!
});

Troubleshooting

Code Not Working

Check for typos in your tenant ID
Clear cache (Ctrl+Shift+R / Cmd+Shift+R)
Check browser console for errors (F12)
Verify code is before </head> or </body> tags

Events Not in Dashboard

Wait 1-2 minutes (slight delay is normal)
Check that window.grain exists in console
Verify tenant ID matches your dashboard
Make sure you saved the theme file

Theme Broke

Revert to backup: Themes → Actions → Unpublish, then publish your backup
Double-check you didn’t delete any Liquid tags ({{ }} or {% %})

What’s Next?

Tracks & Funnels

Analyze customer journeys from landing to purchase

E-commerce Guide

Best practices for e-commerce analytics

Remote Config

A/B test pricing, messaging, and layouts

Query API

Build custom reports

Need help? Chat with us at grainql.com or email support@grainql.com.

Getting Started

Integrations

Tracking & Events

Dashboard

MCP Server

Guides

React SDK

Advanced

What You’ll Need

Step 1: Open Theme Code

Step 2: Edit theme.liquid

Step 3: Save

Track E-commerce Events

Track “Add to Cart”

Track Checkout Started

Track Purchases

Track Product Views

Track Search

Test Your Integration

Troubleshooting

Code Not Working

Events Not in Dashboard

Theme Broke

What’s Next?

Tracks & Funnels

E-commerce Guide

Remote Config

Query API

​What You’ll Need

​Step 1: Open Theme Code

​Step 2: Edit theme.liquid

​Step 3: Save

​Track E-commerce Events

​Track “Add to Cart”

​Track Checkout Started

​Track Purchases

​Track Product Views

​Track Search

​Test Your Integration

​Troubleshooting

​Code Not Working

​Events Not in Dashboard

​Theme Broke

​What’s Next?

Tracks & Funnels

E-commerce Guide

Remote Config

Query API

What You’ll Need

Step 1: Open Theme Code

Step 2: Edit theme.liquid

Step 3: Save

Track E-commerce Events

Track “Add to Cart”

Track Checkout Started

Track Purchases

Track Product Views

Track Search

Test Your Integration

Troubleshooting

Code Not Working

Events Not in Dashboard

Theme Broke

What’s Next?