Skip to main content
Shopify stores need the Web SDK installed in two places, because Shopify does not allow scripts on the checkout and thank-you pages. Your storefront gets a script tag; your checkout gets a custom pixel. Once both are in, every purchase is linked back to the ad, campaign, or link that brought the shopper in.
This takes about 30 minutes and needs no developer access to your servers. Everything is done from your Shopify admin.

Before you start

Go to Settings → Domains in your Shopify admin. Your checkout must run on your own domain (for example checkout pages under yourstore.com) for the purchase to be linked to the shopper’s browsing session.Most Shopify stores are already set up this way. If your checkout runs on yourstore.myshopify.com while your storefront is on yourstore.com, Step 3 below is required rather than optional.
Web attribution is in beta, so tokens are issued by us. Email support@linkrunner.io with your project name and store domain, and we’ll send you a Web SDK token.
Step 2 edits your theme’s code. In Online Store → Themes, use Actions → Duplicate on your live theme first, so you can roll back instantly.

Installation

1

Add the SDK to your theme

Go to Online Store → Themes → ⋯ → Edit code and open layout/theme.liquid.
Shopify Themes page with the more-actions menu open and Edit code highlighted

Open the ⋯ menu on your live theme (1), then choose Edit code (2)

Paste this immediately before the closing </head> tag, replacing YOUR_WEB_SDK_TOKEN:
Click Save. This tracks page views, traffic sources, campaigns, and ad clicks across your storefront.
2

Pass the visitor ID into the cart

In the same layout/theme.liquid file, paste this directly below the script you just added:
This attaches the visitor’s ID to their cart so the purchase can still be matched if checkout happens on a different domain, which is what Shop Pay does. Click Save.
Strictly optional if your checkout is on your own domain and you don’t use Shop Pay. We recommend adding it anyway: it costs nothing and removes a whole class of missing-attribution problems.
3

Add the checkout pixel

Go to Settings → Customer events → Add custom pixel. Name it Linkrunner.
This is a new, separate pixel. Do not paste this code into a pixel you already have. Each custom pixel runs in its own sandbox, so any existing pixels (Google Analytics, Meta, and so on) keep working and should be left untouched.
Shopify Customer events settings page with Add custom pixel highlighted

Settings → Customer events (1), then Add custom pixel (2)

The code box arrives pre-filled with Shopify’s commented placeholder starting // Step 1. Initialize the JavaScript pixel SDK. Select all of it and delete it, then paste the code below and replace YOUR_WEB_SDK_TOKEN with the token from Step 1.
Shopify custom pixel editor showing the empty code box and the Connect button

Replace the placeholder in the Code box (1). Connect (2) is the button you press after saving.

The empty catch at the end is deliberate. A custom pixel must never throw, because an error there can interrupt the checkout. Failures are swallowed silently, which is why you verify with the steps below rather than by watching for errors.
This sends your shoppers’ email and phone to Linkrunner. They are what link a purchase to an identifiable person, so audience exports and person-level reporting depend on them.Make sure your privacy notice covers sharing customer contact details with Linkrunner and your data processing agreement with us is in place. If you would rather not send them, comment out the email and phone lines in event_data. Attribution, campaign reporting, and revenue all work without them; you lose person-level audiences.
Above the code box, check the two Customer privacy settings. The defaults are already right for Linkrunner, so in most cases you are confirming rather than changing:
  • Permission: leave Required selected, with Marketing and Analytics ticked. Analytics covers page views and sessions; Marketing covers the ad click IDs and campaign data that attribution depends on. Preferences is unused, leave it unticked.
  • Data sale: leave Data collected qualifies as data sale selected. The pixel then stops collecting for shoppers who opt out of having their data sold.
Shopify custom pixel customer privacy settings showing Permission and Data sale options

Leave Required selected (1) with Marketing and Analytics ticked (2), and leave the default Data sale option (3)

Choosing Not required makes the pixel collect regardless of consent. That is a legal decision about the markets you sell in, not a technical one. Check with whoever handles privacy at your company before changing it.
Click Save, then click Connect.
Save and Connect are two separate actions. A saved but unconnected pixel looks installed and never runs. This is the single most common reason purchases don’t appear.
4

Verify it works

  1. Visit your store with test campaign parameters, for example https://yourstore.com/?utm_source=meta&utm_medium=cpc&utm_campaign=test
  2. Browse a product, add it to the cart, and complete a real order
  3. Open Web Events in your Linkrunner dashboard
You should see page views for the visit and a purchase event carrying the order value, all attributed to utm_campaign=test.
Refund the test order afterwards. Refunding does not remove the tracked event, which is what you want, because you are confirming tracking, not revenue.

Limitations and constraints

Please read these before going live. Most are Shopify platform behaviour, not Linkrunner settings, and cannot be worked around.
When a shopper checks out with Shop Pay, the checkout is served by shop.app, not your store. Browser security prevents the pixel from reading anything your storefront saved.The cart-attribute snippet in Step 2 is what keeps these purchases attributed. If you use Shop Pay, Step 2 is required.
Custom pixels do not run in theme preview links. Test on the published theme, or your purchase events will never fire.
If your store uses Shopify’s customer privacy controls, a custom pixel will not run until the visitor grants the consent category the pixel is assigned to.If you see page views but no purchases, check the pixel’s Permission setting under Settings → Customer events first.
Development stores and stores behind a password page keep the storefront gated. Enter the password first, then navigate to your campaign URL. Otherwise Shopify strips the campaign parameters during the redirect and the visit records with no campaign.
Safari deletes browser storage written by scripts after 7 days of inactivity. A Safari visitor who first arrives from an ad and returns more than a week later will be counted as a new visitor.This affects all web analytics tools equally and is not specific to Linkrunner.
Some browser extensions block analytics requests. Expect a small gap between Shopify’s own order count and the purchases recorded here. Shopify’s admin remains the source of truth for revenue.
The cdn.linkrunner.io URL in Step 1 always serves the current version, so there is nothing to install or keep updated. If you load the SDK from somewhere else, use v0.1.13 or later for full campaign attribution at checkout.

Troubleshooting

Open your storefront, press F12, and check the Network tab for requests to api.linkrunner.io.
  • No requests: the script tag is missing or the theme wasn’t saved
  • 401 responses: wrong token. Confirm you used the Web SDK token
In order of likelihood:
  1. The pixel was saved but never Connected
  2. Customer privacy settings are blocking it (see Limitations)
  3. You tested on a theme preview instead of the published theme
  4. The token in the pixel doesn’t match the one in the theme
Usually Shop Pay. Confirm the Step 2 cart snippet is installed and saved, then place a fresh test order, because existing carts won’t have the attribute attached.
Check that your products have prices set. The pixel reads the order total directly from Shopify’s checkout data, so a zero total means a zero-priced order.

What gets tracked

Need help? Contact support@linkrunner.io