Concepts

The Referral Kit is built on a few small ideas. Understand these and the REST contract reads like common sense.

The conduit model — who owns what

MMOLove is the conduit. The split never moves:

We do the attribution; you own the payout. MMOLove never touches your economy and never hands out rewards.

The lifecycle

A referral moves through a small state machine. Two inbound events drive the forward path — registered and qualified — and a couple of states model reversal and expiry.

                    registered             qualified
   ┌─────────┐      (your kit)    ┌──────────────┐   (your kit)    ┌───────────┐
   │ clicked │ ───────────────▶   │  registered  │ ─────────────▶  │ qualified │
   └─────────┘                    └──────────────┘                 └───────────┘
        │                            │        │                        │
        │ /r link followed           │        │  reversed (owner)      │
        │ (mmref minted)             │        ▼                        │
        │                            │   ┌──────────┐                  │
        │                            └──▶│ reversed │◀─────────────────┘
        │                                └──────────┘
        │
        │  maturation window elapses
        ▼
   ┌─────────┐
   │ expired │     rejected (anti-abuse) is also terminal
   └─────────┘

Legal transitions

The state machine is strict, so out-of-order events fail loudly instead of corrupting attribution:

• registered from clicked → advance to registered (mints the anchor).
• registered when already registered / qualified → no-op (idempotent).
• qualified from registered → advance to qualified.
• qualified when already qualified → no-op.
• qualified from clicked (no anchor yet) → invalid → 422. You must send registered first.
• reversed from registered / qualified → advance to reversed.
• Anything into a terminal state → invalid (a repeat of the same terminal event is a no-op).

See Errors & troubleshooting for how each maps to a status code.

The durable anchor

When your registered event lands, MMOLove mints a long-lived referral_id — the anchor. Every later event (qualified, reversed) keys off it.

The anchor is deliberately decoupled from the click token's expiry. The mmref token in the link is signed and time-bounded; the anchor it mints is durable, so a referee who registers near the edge of the click window still qualifies weeks later without the original token being "live."

The anchor row carries the referrer, the referee identity, the originating token, the current state, and the registered_at / qualified_at timestamps.

First-touch — one referrer per referee

Attribution is first-touch: the first referrer to register a given referee wins, permanently. The anchor is unique per (server_id, referee_identity), so:

• The first registered for a referee mints the anchor and binds that referrer.
• A different referrer sending registered for the same referee collides on that uniqueness and is acknowledged with 200 and ignored ({ "ignored": "first_touch_conflict" }). The original anchor is never overwritten.

This is why referee_identity must be stable — the same player must always map to the same identity value, or first-touch can't hold.

The attribution window — maturation_days

Each server config carries a maturation_days window (the industry default is 90 days; configurable 1–730 on the Referrals tab). It's the period in which a registered referral can still mature to qualified and count. Once it elapses without qualification, the referral is considered expired.

Set it to match how long it realistically takes a new player to reach your milestone — generous enough that genuine referrals land, tight enough to keep the funnel honest.

Idempotency & dedup

Every event you send carries a server_event_id — your idempotency key. Dedup is on the tuple (token, type, server_event_id), never on token alone, so registered and qualified can both land for one referral. Resending the exact same event is absorbed and returns 200. This makes retries completely safe — see Signing & security.

Anti-abuse caps

The config also supports anti-abuse caps (per referrer, per IP, per month; 0 = unlimited) and a display-only reward_description. These are owner-set on the Referrals tab. As with everything else: MMOLove records and surfaces; you decide and grant.

Where to go next