Skip to content
OpenPartner docs

Cookies + cref

OpenPartner attribution is a cross-domain problem. The click happens on the partner’s share URL (share.creator.com/r/foo or app.openpartner.dev/r/...). The conversion happens on the brand’s site (acme.com/signup). Different domains. The browser won’t share cookies between them. Referer headers get stripped by Safari ITP, by privacy-focused browsers, and by any HTTPS → HTTP transition.

So how does the conversion get attributed back to the right partner?

The trick: cref

Every click on a share link generates a unique clickId (a ULID). The router:

  1. Records the Click row server-side, keyed by the clickId
  2. Appends ?cref=<clickId> to the destination URL as a query param
  3. 302-redirects the user to that URL

The user lands on https://acme.com/signup?cref=01ARZ3NDEKTSV4RRFFQ69G5FAV.

The OpenPartner SDK on the brand’s site does one job at page-load:

// inside openpartner.init()
const cref = new URLSearchParams(location.search).get('cref');
if (cref) {
  // First-party cookie scoped to acme.com — survives Safari ITP,
  // doesn't depend on referer, no third-party cookie shenanigans.
  document.cookie = `_cref=${cref}; max-age=${60 * 60 * 24 * 90}; path=/; samesite=lax`;
}

Now the brand’s site has a first-party cookie holding the clickId. When the user signs up later (could be 5 seconds later, could be 60 days later), the SDK reports the conversion event with the cref:

window.openpartner.identify(user.id, { email: user.email });
window.openpartner.event('subscription_created', { amount: 4900, currency: 'USD' });

The SDK sends both events to the API with the _cref cookie value attached. Server-side:

  1. The event is recorded as an Event row, tagged with the userId
  2. The cref is matched back to the original Click row → we know the partner
  3. An Identity row links userId ↔ clickId so future events from this same userId attribute without needing the cref again
  4. The campaign’s attribution model decides who gets credit (last-click usually, but see Attribution models)
  5. A Commission row is created from the rule

Why first-party cookies work where third-party don’t

Third-party cookies (a cookie set on openpartner.dev while the user is on acme.com) are blocked by:

  • Safari ITP (default since 2020)
  • Firefox Total Cookie Protection (default since 2022)
  • Brave (default)
  • Soon Chrome (in slow rollout)

They were the standard before. They aren’t anymore. Any platform still relying on third-party cookies is silently losing 30–60% of conversions on Safari alone.

First-party cookies (set on acme.com itself, by acme.com’s own scripts) work in every browser without exception. The cref query-param-to-first-party-cookie hop is what makes attribution survive ITP / Privacy Sandbox / etc.

The _cref cookie has max-age=90*24*60*60 (90 days). That’s longer than most attribution windows (which default to 60 days), so the cookie outlives the window.

Why longer? Because the attribution window is the brand’s commission policy (“we’ll pay on conversions within 60 days”), but the user might still bounce around your site after that and we want the click record available for analytics even if the commission’s ineligible.

If a brand wants to enforce a strict cookie expiry too, they can set the cookie max-age via SDK config. Defaults are pragmatic.

What if the user clears cookies?

They lose the cref → the next conversion from them isn’t attributable to that click. Same fate as any cookie-based system.

What we can do (and openpartner does): if the same userId was identified earlier with a cref, we have an Identity row linking userId ↔ clickId. So if the user signs up on mobile (cookie present) and then converts on desktop after signing in (cookie absent but userId known), we still attribute via the Identity table.

This “logged-in stitching” is what lets attribution survive cross-device. See Identity stitching for the detail.

Why not UTMs?

UTMs (utm_source, utm_campaign, etc.) are display-layer marketing tags — they go in the URL, get logged in analytics, and disappear. They don’t track individual users; they track campaigns.

For partner attribution, you need a unique-per-click identifier that persists across the session and follows the user to conversion. That’s what cref is. UTMs and cref are complementary, not alternatives — many brands set both.

What if I see double-attribution?

A user clicks Partner A’s link, then Partner B’s link, then converts. Who gets credit? Depends on the campaign’s attribution model:

  • Last-click (default) — Partner B
  • First-click — Partner A
  • Linear — A and B split 50/50
  • Position 40/20/40 — A 40%, B 40% (since they’re first and last with no middle)

The cref cookie on the brand’s site holds the last click — but the server has all clicks in the window from the same user (via the Identity table) and computes the model server-side.

Full deep-dive: Attribution models.