Skip to main content
This page adds the GrainQL 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.
GrainQL also has a Shopify app. One install of the app creates a GrainQL workspace for the store, adds the tag through a theme app embed, records orders and checkouts, and imports the orders of the last 90 days. The app is in private distribution and is not listed in the Shopify App Store. GrainQL sends the install link on request. The app bills through Shopify. Read Plans and limits. This page is for a store that installs the tag by hand.

Before you start

You need three things:
  • Admin access to your Shopify store.
  • Your tenant alias from the dashboard. It is the Workspace ID in Settings, then General settings, 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

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

2. Edit theme.liquid

  1. In the file list, open the Layout folder.
  2. Click theme.liquid.
  3. Find the </head> tag. Use Ctrl+F or Cmd+F to search.
  4. Add this code directly before </head>:
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 GrainQL 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 GrainQL Tag queues the event and sends it later.

Add to cart

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

Checkout started

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

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:
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:

Searches

Add this code in theme.liquid. It runs on the search results page only:
Read Name events for the naming convention.

5. Test the installation

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

Troubleshooting

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 GrainQL stores, cookieless mode, and consent modes.