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
  1. What it does
  2. Two ways to attach a code
  3. What your app gets
  4. The referral.converted webhook
  5. The Referrals table
  6. Rewards, abuse and duplicate sales
  7. Limits
  8. Related

What it does

  1. 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.
  2. 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.
  3. Your server hears about it. A referral.converted webhook fires once for each referred install that opens and matches. It carries the code, the link and the tap it came from.
  4. 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.

Code
https://hilltop.strait.link/invite?strait_ref=ASHA42

One link per referrer. Your server creates a link for each user and sets referralCode:

Terminal
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:

JSON
{
  "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:

JSON
{
  "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 the clickId on 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 eventId with every purchase (events). A retry or a second report with the same eventId is 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 the app.event webhook).
  • 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.