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

# Referral widget

> Embed the in-app referral widget to enroll users and surface their referral link automatically.

The referral widget is a small script that enrolls a signed-in user as a referrer and shows them
their referral link and share UI — the drop-in way to run [product-led
referrals](/affiliate/referral-widget) without building your own UI.

## Embed it

Add the script inside your authenticated app, with a **publishable** key:

```html theme={null}
<script
  src="https://app.trackrev.io/widget.js"
  data-key="pk_live_..."
  data-user-id="USER_ID"
  data-user-email="user@example.com"
  data-user-tier="paid"
></script>
```

## Attributes

<ParamField path="data-key" type="string" required>
  A publishable key (`pk_…`) from **Settings → Developers**. Safe to expose in the browser.
</ParamField>

<ParamField path="data-user-id" type="string" required>
  Your stable user id — becomes the referrer's `external_user_id`.
</ParamField>

<ParamField path="data-user-email" type="string" required>
  The user's email.
</ParamField>

<ParamField path="data-user-tier" type="string" required>
  `free` or `paid` — determines the reward amount the user earns for referrals.
</ParamField>

The widget calls [`/api/v1/referrals/enroll`](/developers/endpoints/referrals#enroll-a-referrer) on
load, so each signed-in user is enrolled and given their link automatically.

## Completing the loop

The widget handles enrollment and sharing. To **reward** the referrer, report the referred signup
from your backend when a new user registers — see
[`/api/v1/referrals/report-signup`](/developers/endpoints/referrals#report-a-signup). Pair this with
[credit fulfilment](/affiliate/credits-and-fulfilment) to deliver the reward automatically.

<Tip>
  Prefer full control over the UI? Skip the widget and call the
  [referral endpoints](/developers/endpoints/referrals) directly — the widget is just a convenient
  front end for the same API.
</Tip>