Add a referral program to your Replit app

Replit Agent builds apps with their own backend server, which runs in the published deployment. That server sees the browser's cookies, so the signup call goes in the place where the server first stores a new user.

01The stackReplit

What Replit builds, and where the signup call goes

Frontend
Usually React served by the app's own server
Accounts
Replit Auth (sign in with Replit) or Clerk Auth
Server code
The app's backend server (Autoscale or Reserved VM deployment)
Secrets
Secrets, as environment variables; the deployment has its own production secrets

Signup boundary: In the backend, where the login callback or the Clerk webhook stores a new user for the first time: send the signup there, never on later logins.

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: Secrets in the workspace, and again in the deployment: production uses its own secrets.

02PromptsPaste in order

1. Capture referral clicks

Paste into Replit Agent 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 Secrets, in the workspace and in the deployment.

2. Send each new account to RefRef
Connect each new account to the referral click. Find the backend code that stores a user for the first time (for Replit Auth, the login callback that inserts the user; for Clerk, the verified user.created webhook). Only when that code creates a new user, not when it updates one, send POST {REFREF_API_URL}/v1/track/events with the X-Api-Key header and { projectId, type: "signup", participant: { kind: "individual", externalId: <user ID> } }. For Replit Auth, add identify: { handle } from the refref_handle cookie of the callback request, if present. For Clerk, store the cookie value in unsafeMetadata.refref_handle at sign-up and read it back in the webhook. Read REFREF_API_KEY, REFREF_PROJECT_ID, and REFREF_PROGRAM_ID from Secrets, and REFREF_API_URL with the default https://api.refref.ai. A RefRef failure must never fail the login: log it and retry with the same body. Add tests for a new user with a cookie, a new user without one, and a returning user.

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 new authenticated backend route, 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 change that prompt 2 should produce (Replit Auth)

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.

server/auth.ts
server/auth.ts
// In the login callback, after the identity provider verified the user.
const existing = await storage.getUser(claims.sub);
const user = await storage.upsertUser(claims);
if (!existing) {
  const handle = req.cookies?.refref_handle;
  try {
    const response = await fetch(`${process.env.REFREF_API_URL ?? "https://api.refref.ai"}/v1/track/events`, {
      method: "POST",
      headers: { "Content-Type": "application/json", "X-Api-Key": process.env.REFREF_API_KEY! },
      body: JSON.stringify({
        projectId: process.env.REFREF_PROJECT_ID,
        type: "signup",
        participant: { kind: "individual", externalId: user.id },
        ...(handle && { identify: { handle } }),
      }),
    });
    if (!response.ok) console.error("RefRef signup failed", response.status);
  } catch (error) {
    console.error("RefRef signup failed", error); // never fail the login
  }
}

Watch for

  • The development URL (*.replit.dev) is a different origin from the published app. Test referrals on the published app.
  • After you link a custom domain, publish again so that REPLIT_DOMAINS and the auth callback include it.
  • Use the user's stable ID (the sub claim or the Clerk user ID), never the email, as the externalId.
04ResultRendered mock

What you get

For the program, start from the SaaS referral program template. Replit apps are often team tools with a subscription, where a reward after the first paid month protects your margin.

your-app.com/account · built with Replit

Team standup board

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 Replit
Not run: it needs a signed-in Replit 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 Replit credits?

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

02

Does Replit Auth tell me when an account is new?

Not directly. Check whether your database already has the user before the login callback stores it, and send the signup only when the callback creates the row.

Official references

Start with a Sandbox Project

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

Get Started