> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manalens.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Typed referral codes

> Codes that players type in game, on a signup form or at checkout. Each code is a referral, like a ?ref= link.

A [short link](https://docs.manalens.dev/features/short-links.md) or a `?ref=` link needs a click. Many viewers of a stream or a video never click. They type a creator code instead, in the game, on a signup form or at checkout. A **typed referral code** measures these people.

You do not create codes in the app. Send the code with an event, and it shows in your reports.

## Send the code

When a user types a code, send one `referral_code_redeemed` event with the code in `properties.code`. You can also send UTM keys in `properties`: `utm_source`, `utm_medium`, `utm_campaign`, `utm_content` and `utm_term`.

```js Web SDK theme={null}
analytics.track('referral_code_redeemed', { code: 'LUCA10', utm_campaign: 'steam-next-fest' });
```

```gdscript Godot theme={null}
UntitledAnalytics.track("referral_code_redeemed", {"code": "LUCA10", "utm_campaign": "steam-next-fest"})
```

```bash Server theme={null}
curl -sS https://api.example.com/v0/events \
  -H "Authorization: Bearer $ANALYTICS_SECRET_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"events": [{"channel": "server", "type": "track", "event": "referral_code_redeemed", "user_id": "player-42", "properties": {"code": "LUCA10", "utm_campaign": "steam-next-fest"}}]}'
```

A code has 2 to 64 letters, digits, `-` and `_`. Codes are not case sensitive: the collector changes `luca10` to `LUCA10`. The collector ignores an event with a code that is not valid.

## The code is the owner

There is no owner field. Give each creator a code. When a creator needs more than one code, use a prefix for all of them, for example `LUCA-10` and `LUCA-STEAM`. Then you can find the codes of one creator by their prefix.

Use `utm_campaign` to group codes by campaign, for example `launch` or `steam-next-fest`.

## How the collector records a code

The collector turns each `referral_code_redeemed` event into a referral touch:

* `ref` is the code, and the channel is **Referrals**.
* The UTM keys that you send in `properties` go into the event context, with the same checks as the UTM parameters of a link. They do not change the channel.
* The other acquisition fields of the session (UTMs from the landing page, click IDs, referrer) are removed from this one event only. Other events keep them.

Thus a code works like a visit from a `?ref=` link with UTM parameters:

* **First and last touch** on user profiles use the same rules as before. If the code is the latest touch, the user's last touch is the code.
* The **Referral** breakdown and filter (`ref`) include codes. The UTM breakdowns and filters include the UTM keys that you sent with the code.
* In attribution, each code is one touch. Pages after the code in the same session do not replace it.

## Read the results

Open **Overview** and find the acquisition card:

* The **Referrals** tab shows the visitors for each code, next to `?ref=` links.
* The **UTM** tab (for example **Campaign**) shows the UTM values that you sent with the codes.
* The **Channels** tab counts codes under **Referrals**.

A code counts a visitor once for each code in the date range. The **Sessions** metric counts only the landing touch of each session, so codes do not add sessions.

For conversions and revenue for each code, use an [attribution model](https://docs.manalens.dev/attribution/models.md) in [Ask AI](https://docs.manalens.dev/features/ask-ai.md) or with the `get_attribution` [MCP](https://docs.manalens.dev/mcp/overview.md) tool. Group by `ref` for each code, or by `campaign` for each `utm_campaign`.


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