Add a referral program to your Bolt app
Bolt apps keep accounts in Bolt Cloud Database, which runs on Supabase technology, and run trusted code in server functions. The signup form keeps the referral handle with the new account, and a server function sends the signup with a key from Secrets.
What Bolt builds, and where the signup call goes
- Frontend
- Any JavaScript framework; most new web projects are React and Vite
- Accounts
- Bolt Cloud Database authentication (email and Google), or your own Supabase
- Server code
- Server functions (Supabase Edge Functions on a Supabase project)
- Secrets
- Database → Secrets, read by server functions
Signup boundary: The signup form stores the referral handle in the new user's metadata. A server 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: Database → Secrets. Server functions read them; the frontend never does.
1. Capture referral clicks
Paste into the Bolt chat 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 in Database → Secrets first.
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 server 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 Database → 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.
Add an "Invite friends" card to the account page. In a new server 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.The server 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
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 runs in a WebContainer inside your own browser, so referral cookies there do not match production. Test on the published app.
- Set the authentication Site URL to the published URL. It defaults to localhost:3000, which breaks confirmation links.
- Bolt's MCP connectors help the builder agent; they are not part of the published app.
What you get
For the program, start from the Double-sided referral program template. A reward for both sides suits the consumer and prosumer apps that people build with Bolt.
your-app.com/account · built with Bolt
Recipe planner
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 Bolt
- Not run: it needs a signed-in Bolt 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 Bolt credits?
No. It adds a referral program to the app that you build with Bolt, so that your users can invite their friends and you can reward them. Credits for inviting people to Bolt itself are a separate offer of Bolt.
02Can I test referrals in the Bolt preview?
Only partly. The preview runs in a WebContainer inside your own browser, so the referral cookie there is not the cookie of your published domain. Publish the app and test the referral link on its real address.
Official references
Start with a Sandbox Project
Create a RefRef account, add a Project, and get the keys that the Bolt prompts need. Sandbox data never mixes with live data.