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 30-day last-click window: when an install appears (via Partner API sync), we look back 30 days 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

When your install starts, capture ref from the query string and put it in the Shopify OAuth state parameter. Shopify returns state to your callback untouched, so the code survives even though Shopify strips other query params. This is all backend — no JavaScript snippet needed.

// START of install — build the OAuth authorize request
const ref = new URL(request.url).searchParams.get('ref');   // from /r/CODE → your install URL
const state = signState({ nonce, ref });                    // your app already signs a state nonce
// ...redirect the merchant to Shopify's OAuth authorize URL with this state...

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

In your OAuth callback, read ref back out of state 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 the exchange succeeds and you have the shop domain
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 (and acquire tokens via token exchange through App Bridge) don't run their own OAuth redirect, so there's no state to carry ref through. The code is still available, just at a different moment: your app's first load.

Your affiliate getpartnerdock.com/r/CODE link routes the merchant to your install URL with ?ref=CODE. Read ref from the URL on that first load, and POST it to the same endpoint with the shop domain — no OAuth state needed.

// 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)

If your affiliates share the direct App Store link apps.shopify.com/your-app?mref=CODE (the Mantle-style format), forward the mref code to the snippet as shown above. PartnerDock resolves it to the affiliate whose referral code matches and attributes the install exactly — no cookie required.

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