Referrals
A referral code rides on the tap, survives the install and comes back on the app's first open, so your server knows who invited whom. The Referrals table shows what each referrer brought.
On this page 8
What it does
- A code on the tap. Each tap can carry a referral code: either the link's own code, or a code added to the link's address for that one tap.
- The code survives the install. When the person installs your app and opens it, the deferred answer your app gets on first open includes
referralCode. On Android this comes through the Google Play install, so it's exact. On iPhone it comes through install matching, which is opt-in. - Your server hears about it. A
referral.convertedwebhook fires once for each referred install that opens and matches. It carries the code, the link and the tap it came from. - You see it per referrer. Dashboard → Referrals has one row per code: its taps, installs, revenue and app opens.
Strait doesn't grant rewards, hold credits or pay anyone out. That stays with your server, which decides from the webhook and your own records what each person gets.
Two ways to attach a code
One shared link, a code per tap. Add strait_ref to any of your links that has no code of its own. This is the simplest set-up: one invite link, and each user shares it with their own code.
https://hilltop.strait.link/invite?strait_ref=ASHA42One link per referrer. Your server creates a link for each user and sets referralCode:
curl https://strait.link/v1/links \
-H "Authorization: Bearer $SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "slug": "invite-asha", "longUrl": "https://shop.example.com/invite", "referralCode": "ASHA42" }'The answer echoes "referralCode": "ASHA42". If it doesn't, the code wasn't saved; create the link again.
A link's own code always wins: on a link with its own code, strait_ref is ignored, so nobody can take a referrer's credit by adding it to their link. A tap with two different strait_ref values counts as having no code.
A code is 1 to 64 letters, digits, - or _. Use your own user id or an invite code. Don't use an email address or a phone number: codes appear in links that people share.
What your app gets
The first-open answer (from /v1/referrer on Android, /v1/match or /v1/handoff/claim on iPhone) gains one field when the matched tap carried a code:
{
"matched": true,
"longUrl": "https://shop.example.com/invite",
"linkId": "lnk_…",
"clickId": "6f1c…",
"matchMethod": "install_referrer",
"referralCode": "ASHA42"
}If the tap had no code, or the install didn't match a tap, the answer has no referralCode. The SDKs pass it to your app as referralCode on the deferred link event (React Native, Flutter, Android, iOS). A website gets no deferred match, so no referralCode either. Grant rewards from your server, using the webhook below, not in the app.
The referral.converted webhook
Subscribe to referral.converted in Dashboard → Settings → Webhooks. Deliveries are signed like every other webhook:
{
"id": "…",
"event": "referral.converted",
"createdAt": "2026-11-11T10:40:00.000Z",
"data": {
"referralCode": "ASHA42",
"linkId": "lnk_…",
"clickId": "6f1c…",
"platform": "android",
"matchMethod": "install_referrer"
}
}It fires once per tap. If the app retries its first-open call, or the same tap leads to a reinstall, no second event is sent. A friend who already had your app opens it directly, so there is no install and no referral.converted event. Tell new users from existing ones with the app.opened event's isInstall field.
The Referrals table
Dashboard → Referrals shows one row per referral code for the period you pick:
| Column | What it counts |
|---|---|
| Referrer | The code the tap carried |
| Taps | Taps with that code in the period |
| Installs | New installs from those taps |
| Revenue | Purchases your app or server reported from those taps, in your main currency |
| Opened app | Those taps that opened your app: new installs plus people who already had it |
Every number counts from taps in the period, like the rest of the dashboard: a tap on 30 October that installs and buys on 2 November counts in October. Taps with no code are one line under the table. On Free, installs and revenue per referrer come with Starter; taps and app opens are on every plan.
GET /v1/referrals?from=2026-11-01&to=2026-12-01 (secret key) returns each code's taps and referred installs in that range, plus totals. There, a tap counts at the time of the tap and a referred install at the time of its first open.
Rewards, abuse and duplicate sales
Your server pays, so your server decides. These rules keep a referral program honest:
- Reward on a real event, not on the install. Grant the reward when the referred user signs up or makes their first purchase, from your server. Join them with
setUserId(your own user id) and theclickIdon the webhook. - Stop self-referral. Refuse a reward when the referred user is the referrer (same user id, same payment card or same phone on your side), and give one reward per referred user, not per install. A reinstall on the same phone makes a new install; your user table is what tells them apart.
- Count each sale once. Send your order id as
eventIdwith every purchase (events). A retry or a second report with the sameeventIdis stored once, so the Revenue column never counts one order twice. - Don't pay from app-reported revenue. Anyone with your app can send a purchase with the publishable key, including a referrer who wants a bigger reward. Pay commissions from your own order records, or from events your server sends with the secret key (
sentWith: "secret_key"on theapp.eventwebhook). - Existing users don't count. A tap that opens an app the person already had is no install, so it fires no
referral.converted.
Limits
- No rewards, credits, payouts, fraud scoring or per-referrer caps in Strait. These belong in your server.
- The link's own code is set when the link is created. It doesn't appear on the link list or edit endpoints, and the batch endpoint doesn't take it; use
?strait_ref=on a shared link for many referrers. - Direct opens (the app was already installed) don't carry the code.
Related
- Referral invite links: a full invite flow in 30 minutes
- Referral and invite links: what a referral program looks like with Strait
- Deferred deep linking: how the destination survives the install
- Webhooks: signatures, retries and test events
- Analytics: how we count: the counting rule behind every number