Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.grainql.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Step 1: Open Theme Code

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

​
Step 2: Edit theme.liquid

  1. In the file list, find Layout folder
  2. Click theme.liquid
  3. Find the </head> tag (use Ctrl+F / Cmd+F to search)
  4. 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 %}

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

​
Test Your Integration

  1. Open your store in an incognito/private window
  2. Browse a product, add to cart, go to checkout
  3. Open browser console (F12 → Console)
  4. Type window.grain — you should see the Grain object
  5. 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.