Referral attribution

A captured referral code has to survive an OAuth round-trip that drops the query string, and then become a credit against the install. Both halves are server-side, and neither needs code from you beyond passing the callback request to afterAuth.

Resolution is automatic

You do not plumb the captured code into mintShopToken yourself. Two paths close the loop:

afterAuth(session, { request }) reads the cookies off the OAuth callback and forwards them. The callback runs top-level, where the cookies are still readable; inside the embedded admin iframe they may not be.
The server-side stash. When an identify arrives with no code, Meridian looks up what captureReferral stashed for that shop.

Which carrier wins

The two carriers resolve differently, which matters when a browser sees more than one tracked link:

Carrier	Scope	On a second capture	Authoritative?
`meridian_mref` cookie, plus `meridian_mref_at`	The browser	Last click wins	Yes, whenever it survives
Meridian’s server-side stash	The app and shop	First write wins	Fallback, read only when no code is supplied

So the most recent click wins if the cookie made it, and the stash covers browsers that refuse cookies at all. The stash can therefore hold an older code than the cookie: it is keyed per shop and never overwritten. Downstream of identify, attribution itself is first-write-wins per install. The first code Meridian records for a shop is the one that sticks, so the code is safe to re-send on every identify and a second affiliate link cannot re-attribute a merchant. An unknown or malformed code is discarded server-side rather than failing the handshake.

Why the click timestamp matters

Meridian bounds commission at the click, so an already-paying merchant who clicks a link today earns the affiliate nothing on billing that came before. captureReferral records the instant and afterAuth forwards it. Without it the server falls back to a flat 30-day window before the attribution, which can pay an affiliate for revenue predating their referral. An app capturing with an SDK older than 1.8.0 sends no timestamp and gets that fallback.

Clear the cookies once attribution is through

The cookies belong to the browser, not the shop. An agency, a freelancer, or your own developer installing your app for a second client from the same browser would attribute that install to the same affiliate for up to 30 days.

import { clearReferralCookies } from "@the-meridian/sdk/server"

const result = await meridian.afterAuth(session, { request })

const headers = new Headers()
if (result.referralForwarded) {
  for (const cookie of clearReferralCookies()) headers.append("Set-Cookie", cookie)
}

clearReferralCookies() clears the code and its timestamp. The older clearReferralCookie() clears the code only and is deprecated: a leftover timestamp dates the next capture from the previous click.

What afterAuth reports

referralCode is what was read off the callback, and referralForwarded is true once it reached Meridian. A failure lands in errors under the referral topic and never breaks the rest of the hook. See createMeridianApp.

Getting started

React

Entitlements

Server

Reference

Referral attribution

Resolution is automatic

Which carrier wins

Why the click timestamp matters

Clear the cookies once attribution is through

What afterAuth reports

​Resolution is automatic

​Which carrier wins

​Why the click timestamp matters

​Clear the cookies once attribution is through

​What afterAuth reports

Resolution is automatic

Which carrier wins

Why the click timestamp matters

Clear the cookies once attribution is through

What afterAuth reports