Referral Link + Web Pixel

This page explains what happens behind the scenes when an affiliate shares their referral link and a customer buys from your store. Understanding this helps you diagnose tracking issues and pick smart defaults.

The URL format

Every affiliate has a unique referral URL:

https://your-store.myshopify.com?affily_ref=AFF-ABC123

affily_ref — the query parameter the app looks for. Fixed, case-sensitive.
AFF-ABC123 — the affiliate's referral code. 6 alphanumeric chars assigned by the system. Custom codes are not editable from the merchant side today.

The URL can point to any page on your storefront: home, a product, a collection, a blog post. The parameter still works.

Step-by-step — what happens on click

Step 1: Visitor clicks the link

The browser navigates to your storefront with ?affily_ref=AFF-ABC123 in the URL.

Step 2: Web Pixel detects the param

The Web Pixel runs on every page load. It reads affily_ref from the URL query string.

Step 3: Cookie is dropped

The pixel creates a cookie named _affily_ref with:

Value = AFF-ABC123.
Expiry = now + Tracking Duration (default 30 days, configurable).

Step 4: Click event is recorded

A click event is logged in the app's analytics with:

Visitor ID (random, stored in cookie).
Referral code.
Page URL, referrer, user agent, screen size.
Timestamp.

Deduplication: if the same visitor ID + same referral code clicks again within 24 hours, it is counted as one click (not two). This prevents affiliates from inflating click counts by refreshing.

Step 5: Visitor browses

The customer explores the site. Every page load reads the cookie and refreshes its expiry to now + Tracking Duration. So a visitor who clicks on day 1 and returns on day 25 still has a valid cookie until day 55.

Step 6: Visitor checks out

When they go to checkout, the pixel captures the checkout token and sends it to the app with the referral code.

Step 7: Order is placed

Shopify sends us an orders/create webhook. The app:

Looks up the order by checkout token.
Finds the referral code from the stored click.
Matches the referral code to an affiliate.
Creates a Pending conversion.

Step 8: Fallback — email matching

If the checkout token didn't match (e.g., the visitor used a custom checkout flow), the app falls back to matching by customer email within the last 1 hour. So if a visitor was logged in when they clicked, email matching gives a second chance.

If neither checkout token nor email match, no conversion is created. The order is treated as direct.

What beats referral link?

Coupon code wins. If the order contains a coupon tied to a different affiliate, that affiliate is credited instead — even if the visitor clicked a referral link first. See Coupon Code Tracking.

Multiple affiliates, same visitor

Last-click wins. If Sarah's link was clicked on day 1 and Mike's link on day 5, Mike gets credit. The cookie holds only one code; new clicks overwrite.

Cross-device tracking

Does not work by default. The cookie is device-specific. A visitor who clicks on their phone but buys on their laptop is not tracked — unless they are logged in on both devices, in which case email fallback may catch it.

What breaks referral tracking

Browser blocks third-party cookies (Safari, Firefox with strict mode). Our cookie is first-party, but some aggressive anti-tracking extensions block it anyway.
Customer clears cookies between click and purchase.
Cookie expired — 30+ days since the last click.
Different device at purchase.
Web Pixel disabled — see Enable Web Pixel.

For these cases, rely on coupon codes as a backup — they work regardless of cookies.

Next step

Profile & Payment Method Coupon Code Tracking