How to Create a Referral Rewards System in FlutterFlow

Add three fields to the users collection: referralCode (String, unique 8-character alphanumeric), referredBy (String, the code used during signup, nullable), and referralCount (Integer, default 0). Create a Cloud Function triggered on user creation (auth.user().onCreate) that generates a unique 8-character code using a combination of the UID and random bytes, then updates the user document with the generated referralCode. Use a while loop to check for uniqueness by querying existing codes before writing.

1// Cloud Function: generateReferralCode on user creation
2const functions = require('firebase-functions');
3const admin = require('firebase-admin');
4const crypto = require('crypto');
5admin.initializeApp();
6
7exports.generateReferralCode = functions.auth.user().onCreate(async (user) => {
8  const db = admin.firestore();
9  let code;
10  let isUnique = false;
11  while (!isUnique) {
12    code = crypto.randomBytes(4).toString('hex').toUpperCase();
13    const existing = await db.collection('users')
14      .where('referralCode', '==', code).limit(1).get();
15    isUnique = existing.empty;
16  }
17  await db.collection('users').doc(user.uid).update({ referralCode: code, referralCount: 0 });
18});

On your signup page, add an optional TextField labeled 'Have a referral code?' below the password field. Style it with a smaller font and a collapsible Section or Expandable so it does not clutter the main signup form. Store the entered code in Page State referralCodeInput. After successful Firebase Authentication signup, pass the referralCodeInput to a Cloud Function called processReferral along with the new user's UID. If the field is empty, skip the referral processing entirely.

Create a Cloud Function called processReferral that receives referralCode and newUserId. The function validates: (1) the code exists by querying users where referralCode matches, (2) the referrer's UID is not the same as newUserId (preventing self-referral), (3) the new user has not already been referred (referredBy is null). If all checks pass, update the new user's referredBy field with the code, increment the referrer's referralCount, award the referrer (e.g., 500 points via FieldValue.increment on rewardPoints), apply the referee benefit (e.g., set a discount flag), and create a referral_events document logging the event.

1// Cloud Function: processReferral
2exports.processReferral = functions.https.onCall(async (data, context) => {
3  if (!context.auth) throw new functions.https.HttpsError('unauthenticated', 'Login required');
4  const { referralCode } = data;
5  if (!referralCode) return { success: false, reason: 'No code provided' };
6  const uid = context.auth.uid;
7  const db = admin.firestore();
8
9  const referrerSnap = await db.collection('users')
10    .where('referralCode', '==', referralCode).limit(1).get();
11  if (referrerSnap.empty) {
12    throw new functions.https.HttpsError('not-found', 'Invalid referral code');
13  }
14  const referrerDoc = referrerSnap.docs[0];
15  if (referrerDoc.id === uid) {
16    throw new functions.https.HttpsError('failed-precondition', 'Cannot refer yourself');
17  }
18  const newUserDoc = await db.collection('users').doc(uid).get();
19  if (newUserDoc.data().referredBy) {
20    throw new functions.https.HttpsError('already-exists', 'Already referred');
21  }
22
23  const batch = db.batch();
24  // Update new user
25  batch.update(db.collection('users').doc(uid), {
26    referredBy: referralCode,
27    signupDiscount: 0.10, // 10% first order discount
28  });
29  // Reward referrer
30  batch.update(referrerDoc.ref, {
31    referralCount: admin.firestore.FieldValue.increment(1),
32    rewardPoints: admin.firestore.FieldValue.increment(500),
33  });
34  // Log event
35  batch.create(db.collection('referral_events').doc(), {
36    referrerId: referrerDoc.id,
37    refereeId: uid,
38    referralCode: referralCode,
39    referrerReward: '500 points',
40    refereeReward: '10% discount',
41    timestamp: admin.firestore.FieldValue.serverTimestamp(),
42  });
43  await batch.commit();
44  return { success: true };
45});

Create a ReferralPage accessible from the user's profile or settings. Display the user's referral code in a large, copyable Text widget with a Copy IconButton that copies the code to the clipboard via a Copy to Clipboard action. Below, add a Share Button that uses a Custom Action with the share_plus package to open the native share sheet with a message like 'Join {AppName} and get 10% off your first order! Use my code: {referralCode}. Download here: {appLink}'. Also display the referralCount and a summary of rewards earned from referrals.

Below the share section on the ReferralPage, add a ListView with a Backend Query on referral_events where referrerId equals the current user, ordered by timestamp descending. Each list item shows the referee's display name (or 'New User'), the date, and the reward earned. At the top of the list, add summary cards: Total Referrals (referralCount), Total Points Earned (referralCount * 500), and Active Referral Code. Use Conditional Visibility to show a motivational message like 'Share your code to earn 500 points per referral!' when referralCount is 0.