In-app referral widget

The referral widget is a web component you put in your own app. It shows the signed-in customer, as a referrer, their referral link, their code, share buttons, how many people clicked, signed up and paid, what they've earned, and the reward their friends get. It's translated into the dashboard's 10 languages.

Your backend mints a short-lived token for the customer; the widget uses it to read that one customer's details. Your API key never reaches the browser, and a token can't read anyone else's data.

1. Add the widget

<script src="https://referally.15.204.158.166.sslip.io/t/tk_.../widget.js" async></script>
<referally-referral-widget token-url="/api/referally-widget-token"></referally-referral-widget>

Or mount it from JavaScript: Referally.mountReferralWidget(element, { tokenUrl, lang }). The element is also available as <referally-widget-referrer>.

2. Mint the token on your server

POST /v1/widget/tokens with an API key:

// GET /api/referally-widget-token, for the signed-in user
const res = await fetch(`${REFERALLY}/v1/widget/tokens`, {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.REFERALLY_API_KEY}`, 'content-type': 'application/json' },
  body: JSON.stringify({ programId: 'prg_...', customerRef: user.id, email: user.email }),
});
return Response.json(await res.json()); // { token, partnerId, expiresAt }

Responses: 404 when no approved partner in the program has that externalRef (and on-demand creation is off), 400 when on-demand creation needs an email, 404 for a banned or archived partner.

Create partners on demand

To give every customer a referral link the first time they open the widget, turn on settings.widget for the program (dashboard: program page → In-app referral widget):

curl -X PATCH $BASE/v1/programs/prg_... -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"widget": {"autoEnroll": true, "destinationUrl": "https://yourapp.com/signup"}}'

The partner is created with externalRef = the customer, enrolled, and given an 8-character code as a coupon and, with destinationUrl, a link.

What the widget reads

GET /t/{trackingToken}/widget/me with Authorization: Widget <token> (public, CORS-enabled):

{
  "program": { "id": "prg_...", "name": "Acme Friends" },
  "partner": { "displayName": "Dana" },
  "code": "dana",
  "coupon": "DANA10",
  "link": "https://go.acme.com/go/tk_.../dana",
  "share": { "x": "…", "facebook": "…", "linkedin": "…", "whatsapp": "…", "email": "mailto:…" },
  "progress": { "clicks": 12, "signups": 3, "payingCustomers": 1 },
  "earnings": [{ "currency": "usd", "pending": 1980, "approved": 0, "paid": 0 }],
  "refereeReward": { "kind": "store_credit", "bps": 200, "capMinor": 500, "currency": "usd", "on": "first_payment" }
}

No email address is ever returned. An expired, tampered or other-merchant token gets 401, and so does a token for a partner who was since banned or archived.

Theming

The widget renders in a shadow root. Style it with CSS variables on the element:

referally-referral-widget {
  --referally-accent: #4f46e5;
  --referally-bg: #ffffff;
  --referally-fg: #111827;
  --referally-muted: #6b7280;
  --referally-border: #e5e7eb;
  --referally-radius: 12px;
  --referally-font: Inter, system-ui, sans-serif;
}

The outer box is exposed as ::part(box).