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.
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.
1. Capture referral clicks
Paste into Replit Agent first.
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.
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.
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.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
// 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.
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.
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
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.
01Does 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.
02Does 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.