How to Build an Affiliate Marketing Platform in FlutterFlow

In FlutterFlow's Firestore panel, create three collections. The affiliates collection stores one document per affiliate with: userId (String), code (String — unique 8-character code), commissionRate (Number — e.g., 0.10 for 10%), status (String — 'active' or 'suspended'), totalEarnings (Number), totalClicks (Integer), and totalConversions (Integer). The referral_clicks collection logs each link click with: refCode (String), sessionId (String), ipHash (String), userAgent (String), and created_at (Timestamp). The conversions collection records completed purchases with: affiliateId (String), orderId (String), orderAmount (Number), commissionAmount (Number), status (String — 'pending', 'approved', 'paid'), and created_at (Timestamp).

Create a Cloud Function named createAffiliateAccount that accepts a userId and an optional requested code. The function generates a random 8-character alphanumeric code (or validates the requested one for uniqueness), creates the affiliates document, and returns the code to the app. In FlutterFlow, add an 'Apply to Become Affiliate' button on your settings or profile page. When tapped, it calls a Custom Action that invokes the createAffiliateAccount Cloud Function and stores the returned code in the user's Firestore profile. Display the referral link as: https://yourapp.com?ref=YOURCODE in a copyable Text widget.

When a new user opens your app via a referral link, you must capture the ref parameter immediately and store it somewhere that survives navigation and page refreshes. In FlutterFlow, create a Custom Action named captureReferralCode. This action reads the current URL's query parameters using Uri.base.queryParameters['ref'] (web) or the initial route (mobile via uni_links package). If a ref code is found, write it to Secure Storage using flutter_secure_storage with the key 'pending_ref_code'. Also log a click event to the referral_clicks collection. Call this action from your app's first page On Page Load event — before any navigation logic runs.

1// Custom Action: captureReferralCode
2import 'package:flutter_secure_storage/flutter_secure_storage.dart';
3import 'package:cloud_firestore/cloud_firestore.dart';
4import 'dart:html' as html show window; // web only
5
6Future<String?> captureReferralCode() async {
7  final storage = const FlutterSecureStorage();
8
9  // Check if we already have a pending ref
10  final existing = await storage.read(key: 'pending_ref_code');
11  if (existing != null) return existing;
12
13  // Parse ref from URL (web)
14  String? refCode;
15  try {
16    final uri = Uri.parse(html.window.location.href);
17    refCode = uri.queryParameters['ref'];
18  } catch (_) {}
19
20  if (refCode == null || refCode.isEmpty) return null;
21
22  // Verify the code exists
23  final doc = await FirebaseFirestore.instance
24      .collection('affiliates')
25      .doc(refCode.toUpperCase())
26      .get();
27
28  if (!doc.exists) return null;
29
30  // Persist to survive navigation
31  await storage.write(key: 'pending_ref_code', value: refCode.toUpperCase());
32
33  // Log the click
34  await FirebaseFirestore.instance.collection('referral_clicks').add({
35    'refCode': refCode.toUpperCase(),
36    'created_at': FieldValue.serverTimestamp(),
37    'userAgent': html.window.navigator.userAgent,
38  });
39
40  // Increment click counter on affiliate doc
41  await FirebaseFirestore.instance
42      .collection('affiliates')
43      .doc(refCode.toUpperCase())
44      .update({'totalClicks': FieldValue.increment(1)});
45
46  return refCode.toUpperCase();
47}

When a user completes a purchase (or sign-up, depending on your model), trigger a Cloud Function named recordConversion. This function reads the pending_ref_code from the user's profile or the order document (set it when the order is created from the app state), calculates the commission as orderAmount * commissionRate from the affiliate document, writes a conversion document, increments the affiliate's totalConversions and totalEarnings, and clears the pending referral attribution from the user's profile. Using a Cloud Function here (rather than a direct Firestore write from the app) prevents clients from manually inflating their own commissions.

1// functions/index.js — recordConversion Cloud Function
2const functions = require('firebase-functions');
3const admin = require('firebase-admin');
4
5exports.recordConversion = functions.https.onCall(async (data, context) => {
6  if (!context.auth) {
7    throw new functions.https.HttpsError('unauthenticated', 'Login required');
8  }
9
10  const { orderId, orderAmount, refCode } = data;
11
12  if (!refCode) return { success: false, reason: 'no_referral' };
13
14  const db = admin.firestore();
15  const affiliateRef = db.collection('affiliates').doc(refCode);
16  const affiliateDoc = await affiliateRef.get();
17
18  if (!affiliateDoc.exists || affiliateDoc.data().status !== 'active') {
19    return { success: false, reason: 'invalid_affiliate' };
20  }
21
22  const rate = affiliateDoc.data().commissionRate || 0.10;
23  const commission = parseFloat((orderAmount * rate).toFixed(2));
24
25  const batch = db.batch();
26
27  batch.set(db.collection('conversions').doc(), {
28    affiliateId: affiliateDoc.id,
29    affiliateUserId: affiliateDoc.data().userId,
30    referredUserId: context.auth.uid,
31    orderId,
32    orderAmount,
33    commissionAmount: commission,
34    status: 'pending',
35    created_at: admin.firestore.FieldValue.serverTimestamp(),
36  });
37
38  batch.update(affiliateRef, {
39    totalConversions: admin.firestore.FieldValue.increment(1),
40    totalEarnings: admin.firestore.FieldValue.increment(commission),
41  });
42
43  await batch.commit();
44  return { success: true, commission };
45});

Create a new page in FlutterFlow named AffiliatesDashboard. Query the affiliates collection filtering by userId == currentUser.uid to fetch the current user's affiliate document. Display totalClicks, totalConversions, and totalEarnings as metric cards using Column and Container widgets with large number text. Add a second query on the conversions collection filtered by affiliateId == affiliateDoc.id and ordered by created_at descending. Show each conversion in a ListView with the order date, amount, commission earned, and status badge (Pending, Approved, or Paid). Add a Share button that copies the referral URL to the clipboard using the Clipboard action in FlutterFlow.