Reliable Attribution

How reliable attribution works

Every affiliate has a unique referral code. The goal is simple: when a merchant installs your app after following an affiliate's link, that code should reach PartnerDock so we credit the right affiliate — with certainty, not a guess.

The reliable way to do that is to carry the code through your install flow. An affiliate's getpartnerdock.com/r/CODE link routes the merchant through your install URL with ?ref=CODE, and your app forwards that code to PartnerDock along with the shop domain. We match it to the affiliate and create the referral instantly, exactly.

Exactly how you forward it depends on your app's install model — whether you run OAuth yourself (authorization code grant) or use Shopify-managed installation with token exchange. Both are fully supported; the chooser below points you to the right path.

The same endpoint also accepts mref (Mantle-style direct App Store links) and the pd_click cookie — all three (ref, mref, utm_source) resolve to the same affiliate code, so existing and migrated links keep working. See Mantle-style direct links.

What happens without it

If your app doesn't forward the code, PartnerDock can only fall back to a short last-click window: when an install appears (via Partner API sync), we look back a short window for any affiliate click for your app and credit the most recent one. But a click carries no shop identifier — it happens before the install — so this is a guess. It can credit the wrong affiliate (even a competitor's test click). For that reason these matches are never auto-approved — each one is held for you to confirm by hand in the Referrals queue.

Direct App Store links (?mref=CODE) attribute only if your app forwards the mref code — Shopify does not pass it to your OAuth callback on its own. Without forwarding, those installs get no credit at all.

In short: the fallback is a safety net, not a foundation. To run a payout program on accurate numbers, the code-carry setup below is required.

Step 1 — Get your webhook token

Your webhook token is a unique UUID that identifies your app to PartnerDock. You'll paste it directly into the snippet.

a1b2c3d4-e5f6-7890-abcd-ef1234567890

Step 2 — Set your install URL

In Settings → Tracking → Reliable attribution, enter your app's install URL — the URL that starts your install (where you build the Shopify OAuth request). Once it's set, affiliate getpartnerdock.com/r/CODE links route the merchant through that URL carrying ?ref=CODE, so the code is available to your install flow.

What exactly should the Install URL be? It's a URL you control — a different one depending on your install model:

Which installation model are you on?

How you carry ref through the install depends on how your app authenticates. There are two models — pick the one that matches your app, then follow that path. Steps 1–2 above (token + install URL) are the same for both.

Path A · App-managed install — carry the code through OAuth

Your OAuth state is a random CSRF nonce, and it must stay that way. Keep your random nonce and your CSRF check exactly as they are — nothing here weakens them. The referral code rides alongside the nonce; it never replaces it. Shopify returns state to your callback untouched, so the code survives even though Shopify strips other query params. There are two equally safe ways to do it:

Option A — keep state a pure random nonce (most conservative). Leave your authorize URL exactly as it is: state is just your random nonce. Store the ref server-side, keyed by that nonce (you already store the nonce in order to verify it on callback). On the callback you verify the nonce as usual, then look the ref back up. Your state never contains anything but a random value, so there is zero change to your CSRF posture.

// START of install
const ref = new URL(request.url).searchParams.get('ref');   // from /r/CODE → your install URL
const nonce = randomNonce();                                 // your existing random CSRF nonce
await store.put(nonce, { ref });                             // remember ref against the nonce (you already store the nonce)
// ...redirect to Shopify's authorize URL with state = nonce (unchanged, fully random)...

Option B — include ref in the signed state payload. If you prefer not to add a lookup, pack both into state and validate only the nonce portion on callback. The nonce is still random and still verified, so CSRF protection is unchanged. This is the approach Shopify's own support describes for carrying a referral through install.

// START of install
const ref = new URL(request.url).searchParams.get('ref');
const state = signState({ nonce, ref });                     // nonce stays random; ref rides alongside
// ...redirect to Shopify's authorize URL with this state...

Path A · App-managed install — forward the code on your callback

In your OAuth callback, verify the nonce as you always do, recover the ref (look it up by the nonce if you used Option A, or read it out of the verified state if you used Option B), and POST it to PartnerDock with the shop domain — from your backend, right there in the callback. You already have both shop and ref at this point, so no frontend script is involved. Replace YOUR_TOKEN with the token from Step 1.

// OAuth CALLBACK — after you verify the nonce and the exchange succeeds
// Option A: const { ref } = await store.get(nonceFromState);
// Option B: const { ref } = verifyState(request.query.state);

await fetch('https://getpartnerdock.com/api/install-report', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    token: 'YOUR_TOKEN',
    shop: shop,                                   // e.g. "acme-store.myshopify.com"
    ref: ref ?? null,                             // the deterministic affiliate code — exact attribution
    click_token: req.cookies['pd_click'] ?? null, // still honoured as a fallback
    mref: req.query.mref ?? null                  // Mantle-style direct links still honoured
  })
});

Path B · Shopify-managed install (token exchange)

Embedded apps that use Shopify managed installation (tokens via token exchange through App Bridge) don't run their own OAuth redirect, so there's no state to carry ref through. Shopify has confirmed there is no supported mechanism to pass a custom value through a managed install, so the exact, guaranteed carry of Path A is not available here. There is a best-effort workaround, and a fallback.

Best-effort workaround: your affiliate getpartnerdock.com/r/CODE link routes the merchant to your install URL with ?ref=CODE. Capture ref there and persist it in a first-party cookie/session, then read it on your first authenticated load and POST it with the shop domain. This is not guaranteed, embedded apps load in an iframe where cookie access is restricted, and the merchant may install without passing through your URL first.

// First embedded load after install (App Bridge / token-exchange app)
const params = new URLSearchParams(window.location.search);
const ref = params.get('ref');           // from /r/CODE → your install URL
const shop = params.get('shop');         // provided by Shopify

if (ref && shop) {
  fetch('https://getpartnerdock.com/api/install-report', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token: 'YOUR_TOKEN', shop, ref }),
  }).catch(() => {});
}

Mantle-style direct links (mref)

mref is just another name for the referral code, ref, mref, and utm_source all resolve to the same affiliate. How reliably it attributes depends on how the merchant arrives:

• Through a tracked redirect (your /r/CODE link, which routes to your install URL carrying the code): you forward it to the endpoint above and it's credited exactly, same as ref.
• A raw App Store ?mref= link (apps.shopify.com/your-app?mref=CODE): Shopify strips the parameter before your callback, so it never reaches your server. It can only be recovered through GA4 (best-effort, see GA4 setup), not forwarded via the snippet.

So for exact credit, point affiliates at their tracked /r/ link. Raw App Store links still attribute, just through the best-effort GA4 path.

Signed requests (recommended, optional)

The examples above send your token in the request body. That works and stays supported. For stronger security, you can instead sign each request so your token never leaves your server. You send a signature and a timestamp header rather than the token itself. A stolen token cannot be replayed, and a request cannot be forged without the token.

Compute an HMAC-SHA256 of {timestamp}.{body} using your tracking token as the key, put your app ID (not secret, shown in Settings → Tracking) in the body, and send two headers:

import crypto from 'crypto';

// The exact body string you will send (do not re-stringify after signing).
const body = JSON.stringify({
  app_id: 'YOUR_APP_ID',        // from Settings > Tracking (not secret)
  shop,                          // the .myshopify.com domain
  ref: ref ?? null,             // forwarded affiliate code (or mref / utm_source)
});

const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto
  .createHmac('sha256', 'YOUR_TOKEN')   // your tracking token, kept server-side, never sent
  .update(`${timestamp}.${body}`)
  .digest('hex');

await fetch('https://getpartnerdock.com/api/install-report', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-PartnerDock-Timestamp': timestamp,
    'X-PartnerDock-Signature': signature,
  },
  body,   // send the SAME string you signed
});

Step 5 — Verify it works

Framework examples

Remix (Shopify CLI)

// app/routes/auth.callback.tsx
export async function loader({ request }: LoaderFunctionArgs) {
  const { session } = await shopify.authenticate.admin(request);
  const shop = session.shop;
  const cookieHeader = request.headers.get("Cookie") ?? "";
  const cookies = Object.fromEntries(cookieHeader.split(";").map(c => {
    const [k, ...v] = c.trim().split("=");
    return [k, v.join("=")];
  }));

  // ref rides the OAuth state you signed at install start; mref/utm_source also accepted
  const url = new URL(request.url);
  const ref = getRefFromState(url.searchParams.get("state")) ?? url.searchParams.get("ref");
  const mref = url.searchParams.get("mref");

  // Non-blocking — don't await
  fetch("https://getpartnerdock.com/api/install-report", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      token: "YOUR_TOKEN",
      shop,
      ref: ref ?? null,
      click_token: cookies["pd_click"] ?? null,
      mref: mref ?? null,
    }),
  }).catch(() => {});

  return redirect("/app");
}

Next.js (App Router)

// app/api/auth/callback/route.ts
export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const shop = searchParams.get("shop") ?? "";
  const cookieStore = cookies();
  const clickToken = cookieStore.get("pd_click")?.value ?? null;
  const ref = getRefFromState(searchParams.get("state")) ?? searchParams.get("ref");
  const mref = searchParams.get("mref");

  // Non-blocking
  fetch("https://getpartnerdock.com/api/install-report", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ token: "YOUR_TOKEN", shop, ref: ref ?? null, click_token: clickToken, mref: mref ?? null }),
  }).catch(() => {});

  // ... rest of your OAuth exchange
}

Express / Node.js

// routes/auth.js
app.get('/auth/callback', async (req, res) => {
  const shop = req.query.shop;
  // ref rides the OAuth state you signed at install start
  const ref = getRefFromState(req.query.state) ?? req.query.ref;

  // Non-blocking — fire and forget
  fetch('https://getpartnerdock.com/api/install-report', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      token: 'YOUR_TOKEN',
      shop,
      ref: ref ?? null,
      click_token: req.cookies['pd_click'] ?? null,
      mref: req.query.mref ?? null,
    }),
  }).catch(() => {});

  // ... rest of your OAuth exchange
});

Common questions