Add a referral program to your Lovable app

Lovable apps use Lovable Cloud for accounts and data. Lovable Cloud uses Supabase's open-source foundation, so your signup tracking is one change to the signup form and one Edge Function that reads its key from Secrets.

01The stackLovable

What Lovable builds, and where the signup call goes

Frontend
TanStack Start for new projects (since May 2026); React and Vite for older projects
Accounts
Lovable Cloud authentication (Supabase Auth underneath), or your own Supabase project
Server code
Edge Functions (Deno)
Secrets
Secrets: write-only, injected into Edge Functions, never sent to the browser

Signup boundary: The signup form stores the browser's referral handle in the new user's metadata. An Edge Function, called at sign-in, verifies the user and sends the signup.

Before you start, create a Project and a referral Program in RefRef, and keep the API key, Project ID, and Program ID ready. The integration reference has each step. Store them as server secrets: Cloud → Secrets. Lovable refuses VITE_ names there, which keeps the key out of the browser bundle.

02PromptsPaste in order

1. Capture referral clicks

Paste into the Lovable chat first.

1. Capture referral clicks
Add the RefRef landing script to the <head> of every page where a referral link can land, with the URLs from configuration: <script src="https://assets.refref.ai/attribution.v1.js" data-api-url="https://api.refref.ai" defer></script>. Before the signup form submits, wait for window.RefRefAttribution?.capture() for at most 3 seconds, then continue the signup even if capture fails. Do not create, change, or delete the refref_handle cookie. Do not store referral data in localStorage.

2. Send each new account to RefRef

Add the Secrets REFREF_API_KEY, REFREF_PROJECT_ID, and REFREF_PROGRAM_ID first, in Cloud → Secrets.

2. Send each new account to RefRef
Connect each new account to the referral click. In the signup form, read the refref_handle cookie with document.cookie and pass it in supabase.auth.signUp as options.data: { refref_signup: true, refref_handle: <cookie value, only if present> }. Supabase writes this metadata only when it creates the user. Then create a Supabase Edge Function named refref-signup that gets the user by passing the bearer token of the Authorization header to supabase.auth.getUser(token), and, only when user_metadata.refref_signup is true, sends POST {REFREF_API_URL}/v1/track/events with the X-Api-Key header and { projectId, type: "signup", participant: { kind: "individual", externalId: user.id }, occurredAt: user.created_at, identify: { handle: user_metadata.refref_handle } }. Leave out identify when there is no handle. Read REFREF_API_KEY, REFREF_PROJECT_ID, and REFREF_PROGRAM_ID from Secrets, and REFREF_API_URL with the default https://api.refref.ai. Call the function with supabase.functions.invoke("refref-signup") when onAuthStateChange reports SIGNED_IN. A RefRef failure must never block sign-in. Never put the API key in frontend code or a VITE_ variable.

3. Show each user their invite link

Optional. Use a second Edge Function for the RefRef calls.

3. Show each user their invite link
Add an "Invite friends" card to the account page. In a new Edge Function named refref-invite that verifies the user from the Authorization JWT, for the signed-in user only, call POST https://api.refref.ai/v1/enrollments and then POST https://api.refref.ai/v1/referral-codes, each with { projectId, programId: REFREF_PROGRAM_ID, participant: { kind: "individual", externalId: <user ID> } } and the X-Api-Key header. Show the link https://r.refref.ai/<code> with a Copy button that announces "Copied". Show three states: loading, ready, and "We could not load your invite link" with a Try again button. Never show a placeholder link, a made-up count, or made-up earnings.
03Backend codeReview

The Edge Function that prompt 2 should produce

Compare the generated code with this reference before you publish. The user must come from the verified session, the key from a secret, and a RefRef failure must not block the user.

supabase/functions/refref-signup/index.ts
supabase/functions/refref-signup/index.ts
// supabase/functions/refref-signup/index.ts
import { createClient } from "npm:@supabase/supabase-js@2";

const cors = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") return new Response("ok", { headers: cors });
  const supabase = createClient(Deno.env.get("SUPABASE_URL")!, Deno.env.get("SUPABASE_ANON_KEY")!);
  // The user comes from the verified JWT, never from the request body.
  const token = (req.headers.get("Authorization") ?? "").replace(/^Bearer /, "");
  const { data: { user } } = await supabase.auth.getUser(token);
  if (!user) return new Response("Unauthorized", { status: 401, headers: cors });
  const metadata = user.user_metadata ?? {};
  // Only accounts that this app's signup form created send a signup.
  if (metadata.refref_signup !== true) return Response.json({ sent: false }, { headers: cors });
  const handle = typeof metadata.refref_handle === "string" ? metadata.refref_handle : undefined;
  const response = await fetch(`${Deno.env.get("REFREF_API_URL") ?? "https://api.refref.ai"}/v1/track/events`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-Api-Key": Deno.env.get("REFREF_API_KEY")! },
    body: JSON.stringify({
      projectId: Deno.env.get("REFREF_PROJECT_ID"),
      type: "signup",
      participant: { kind: "individual", externalId: user.id },
      occurredAt: user.created_at,
      ...(handle && { identify: { handle } }),
    }),
  });
  // A repeated signup returns the first result, so the app can call this on every sign-in.
  if (!response.ok) console.error("RefRef signup failed", response.status, await response.text());
  return Response.json({ sent: response.ok }, { headers: cors });
});

Watch for

  • The preview has its own address but shares the published app's backend and data. Test referrals on the published app.
  • Supabase writes the refref_signup mark only when it creates the user, so an existing email never sends a new signup. A user can edit their own user_metadata later, but RefRef takes only the first signup of each user, which the function sends at the first sign-in.
  • MCP connectors in Lovable help the builder agent only. They are never part of the published app, so tracking must be app code.
04ResultRendered mock

What you get

For the program, start from the Double-sided referral program template. Consumer apps built with Lovable convert best when the invited friend gets something too.

your-app.com/account · built with Lovable

Habit tracker

Invite friends

Share your link. You both get a reward when your friend signs up.

https://r.refref.ai/k3x9m2p7qaCopy

RefRef Console · Referrals

Referrer
user-a (your user ID)
Referee
user-b (your user ID)
Touch
click → signup
Program
Invite friends
Reward
earned, waiting for delivery
Rendered mock with example values: the invite card that prompt 3 builds, and the referral that RefRef records when B signs up through A's link.
05Rehearsal recordChecks open

What we ran, and what happened

Some checks have not run yet. Treat the open steps as a guide to verify yourself, and record your own results.

pendingThe prompts produce the integration in Lovable
Not run: it needs a signed-in Lovable account, and generation uses builder credits. Paste prompts 1 and 2 into a test app, then compare the generated code with the reference code.
pendingTwo-user journey on the published app
Not run. On the published app at its final domain: follow A's link as B, sign up, and check the referral in the Console; sign in again as B and check that no second signup arrives; search the browser bundle for the API key.
passed · 2026-10-20The request of the reference code matches the RefRef API
The reference code sends the same signup body (projectId, type, participant, identify) that the rehearsal journey of the coding-agent guides sent to a disposable RefRef stack, where it created the referral. The function itself has not run on the builder.
06QuestionsFAQ
01

Does this give me Lovable credits?

No. It adds a referral program to the app that you build with Lovable, so that your users can invite their friends and you can reward them. Credits for inviting people to Lovable itself are a separate offer of Lovable.

02

Does this work on Lovable Cloud and on my own Supabase project?

Yes. Lovable Cloud uses Supabase Auth and Edge Functions underneath, so the same signup metadata and Edge Function work on both. Put the Secrets where your functions run.

Official references

Start with a Sandbox Project

Create a RefRef account, add a Project, and get the keys that the Lovable prompts need. Sandbox data never mixes with live data.

Get Started