Add a referral program to your Base44 app

Base44 apps use built-in Base44 authentication and run trusted code in backend functions on Deno. A backend function knows the signed-in user through createClientFromRequest, so it can send the signup with a key from the app's secrets.

01The stackBase44

What Base44 builds, and where the signup call goes

Frontend
React single-page app
Accounts
Built-in Base44 authentication
Server code
Backend functions (Deno), called with base44.functions.invoke
Secrets
App secrets, read by backend functions as environment variables

Signup boundary: A backend function, called once right after the first sign-in, reads the user with base44.auth.me() and sends the signup with the handle that the page passes.

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: App secrets in the dashboard, or base44 secrets set. Setting a secret redeploys the functions.

02PromptsPaste in order

1. Capture referral clicks

Paste into the Base44 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 REFREF_API_KEY, REFREF_PROJECT_ID, and REFREF_PROGRAM_ID as app secrets first.

2. Send each new account to RefRef
Connect each new account to the referral click. Create a backend function named refrefSignup. In it, call createClientFromRequest(req) and base44.auth.me() to get the signed-in user; never take the user ID from the request body. Send 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_date, identify: { handle } }, where handle is the refref_handle value that the page sends in the body; leave out identify without one. Send nothing when user.created_date is more than 10 minutes ago. Read REFREF_API_KEY, REFREF_PROJECT_ID, and REFREF_PROGRAM_ID from secrets, and REFREF_API_URL with the default https://api.refref.ai. In the app, right after a user signs in for the first time, read the refref_handle cookie and call base44.functions.invoke("refrefSignup", { handle }). A RefRef failure must never block the app.

3. Show each user their invite link

Optional.

3. Show each user their invite link
Add an "Invite friends" card to the account page. In a backend function named refrefInvite that reads the user with base44.auth.me(), 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 backend 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.

functions/refrefSignup.ts
functions/refrefSignup.ts
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me(); // the signed-in user, never the body
  if (!user) return Response.json({ error: "Unauthorized" }, { status: 401 });
  // Only a new account sends a signup: the page cannot attribute an old one later.
  if (Date.now() - new Date(user.created_date).getTime() > 10 * 60_000)
    return Response.json({ sent: false });
  const { handle } = await req.json().catch(() => ({}));
  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_date,
      ...(typeof handle === "string" && handle && { identify: { handle } }),
    }),
  });
  return Response.json({ sent: response.ok });
});

Watch for

  • Base44 keeps the session token in localStorage, not a cookie, so only the page can tell the function about the referral handle. Call the function right after the first sign-in.
  • The page decides when to call the function, so the function itself refuses accounts older than 10 minutes. RefRef also takes only the first signup of each user, and refuses an account created before the RefRef Project.
  • Use asServiceRole only where you need it: it bypasses the app's access rules.
04ResultRendered mock

What you get

For the program, start from the Double-sided referral program template. Base44 apps are often community and event apps, where both sides need a reason to act.

your-app.com/account · built with Base44

Event RSVP app

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 Base44
Not run: it needs a signed-in Base44 account on the Builder plan or higher for secrets and functions, 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 Base44 credits?

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

02

Why does the page send the referral handle to the function?

Base44 keeps the session in localStorage, so a backend function sees the user but not the browser's cookies. The page reads the refref_handle cookie and passes it once, right after the first sign-in.

Official references

Start with a Sandbox Project

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

Get Started