Add a referral program to your v0 app
v0 builds Next.js apps that run on Vercel, with databases and auth from Vercel Marketplace integrations such as Supabase and Neon. Server actions and route handlers see the browser's cookies, so the RefRef recipes for Next.js apply as they are.
What v0 builds, and where the signup call goes
- Frontend
- Next.js App Router with shadcn/ui and Tailwind
- Accounts
- A Marketplace integration: Supabase Auth, or your own auth on Neon
- Server code
- Server actions and route handlers on Vercel
- Secrets
- Vercel environment variables; only NEXT_PUBLIC_ variables reach the browser
Signup boundary: In the server action that signs the user up, and in the route that confirms the email: the RefRef recipe for Supabase Auth, or the recipe for your auth library.
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: Project settings → Environment Variables. The v0 preview uses the Development values.
1. Capture referral clicks
Paste into the v0 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. Use next/script in the root layout.2. Send each new account to RefRef (Supabase Auth)
Add REFREF_API_KEY, REFREF_PROJECT_ID, and REFREF_PROGRAM_ID as environment variables in the project settings, without the NEXT_PUBLIC_ prefix.
Follow the RefRef recipe for Supabase Auth at https://refref.ai/docs/platform/installation/supabase. Create lib/refref.ts from its recipe file. In the sign-up server action, read the refref_handle cookie with cookies() and pass refrefSignupData(handle) as options.data to supabase.auth.signUp. In the route that confirms the email with verifyOtp, call trackSignup(data.user). Keep all RefRef code on the server and never use a NEXT_PUBLIC_ variable for the key. A RefRef failure must never fail the signup.3. Show each user their invite link
Optional.
Add an "Invite friends" card to the account page. In a server component or route handler of the account page, 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 sign-up action 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.
app/(auth)/actions.ts
"use server";
import { cookies } from "next/headers";
import { createClient } from "@/lib/supabase/server";
import { refrefSignupData } from "@/lib/refref";
export async function signUp(formData: FormData) {
const supabase = await createClient();
const data = refrefSignupData((await cookies()).get("refref_handle")?.value);
await supabase.auth.signUp({
email: String(formData.get("email")),
password: String(formData.get("password")),
options: { data, emailRedirectTo: `${process.env.SITE_URL}/auth/confirm` },
});
}Watch for
- Build emailRedirectTo from a configured site URL, never from the request's Host header.
- v0's MCP connections help generation only: the generated app cannot call MCP tools.
- For Clerk, Auth.js, or Better Auth, use the matching RefRef recipe instead of the Supabase one.
What you get
For the program, start from the SaaS referral program template. v0 apps are often SaaS products and client portals with a subscription.
your-app.com/account · built with v0
Client portal
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 v0
- Not run: it needs a signed-in v0 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 v0 credits?
No. It adds a referral program to the app that you build with v0, so that your users can invite their friends and you can reward them. Credits for inviting people to v0 itself are a separate offer of v0.
02Which RefRef recipe does a v0 app use?
The recipe of its auth library. With the Supabase Marketplace integration, use the Supabase Auth recipe; with Clerk, Auth.js, or Better Auth, use theirs. The landing script and the rules are the same.
Official references
Start with a Sandbox Project
Create a RefRef account, add a Project, and get the keys that the v0 prompts need. Sandbox data never mixes with live data.