> ## Documentation Index
> Fetch the complete documentation index at: https://help.the-meridian.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Referral attribution

A [captured](/sdk-referrals) 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:

1. **`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.
2. **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.

```ts theme={null}
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`](/sdk-app#afterauth).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.