feat(creators): added referrers, code redemption, campaign tracking, etc

apps/sim/app/(auth)/components/utm-cookie-setter.tsx

@@ -0,0 +1,33 @@
+'use client'
+
+import { useEffect } from 'react'
+import { useSearchParams } from 'next/navigation'
+
+const UTM_KEYS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content'] as const
+const COOKIE_NAME = 'sim_utm'
+const COOKIE_MAX_AGE = 3600 // 1 hour
+
+export function UtmCookieSetter() {
+  const searchParams = useSearchParams()
+
+  useEffect(() => {
+    const hasUtm = UTM_KEYS.some((key) => searchParams.get(key))
+    if (!hasUtm) return
+
+    const utmData: Record<string, string> = {}
+    for (const key of UTM_KEYS) {
+      const value = searchParams.get(key)
+      if (value) {
+        utmData[key] = value
+      }
+    }
+
+    utmData.referrer_url = document.referrer || ''
+    utmData.landing_page = window.location.pathname
+    utmData.created_at = Date.now().toString()
+
+    document.cookie = `${COOKIE_NAME}=${encodeURIComponent(JSON.stringify(utmData))}; path=/; max-age=${COOKIE_MAX_AGE}; SameSite=Lax`
+  }, [searchParams])
+
+  return null
+}

apps/sim/app/(auth)/layout.tsx

@@ -1,7 +1,8 @@
 'use client'
 
-import { useEffect } from 'react'
+import { Suspense, useEffect } from 'react'
 import AuthBackground from '@/app/(auth)/components/auth-background'
+import { UtmCookieSetter } from '@/app/(auth)/components/utm-cookie-setter'
 import Nav from '@/app/(landing)/components/nav/nav'
 
 // Helper to detect if a color is dark
@@ -28,6 +29,9 @@ export default function AuthLayout({ children }: { children: React.ReactNode })
   }, [])
   return (
     <AuthBackground>
+      <Suspense>
+        <UtmCookieSetter />
+      </Suspense>
       <main className='relative flex min-h-screen flex-col text-foreground'>
         {/* Header - Nav handles all conditional logic */}
         <Nav hideAuthButtons={true} variant='auth' />

apps/sim/app/api/attribution/route.ts

@@ -0,0 +1,201 @@
+import { db } from '@sim/db'
+import { DEFAULT_REFERRAL_BONUS_CREDITS } from '@sim/db/constants'
+import { referralAttribution, referralCampaigns, user, userStats } from '@sim/db/schema'
+import { createLogger } from '@sim/logger'
+import { eq } from 'drizzle-orm'
+import { nanoid } from 'nanoid'
+import { cookies } from 'next/headers'
+import { NextResponse } from 'next/server'
+import { getSession } from '@/lib/auth'
+import { applyBonusCredits } from '@/lib/billing/credits/bonus'
+
+const logger = createLogger('AttributionAPI')
+
+const COOKIE_NAME = 'sim_utm'
+
+/**
+ * Maximum allowed gap between when the UTM cookie was set and when the user
+ * account was created. Accounts for client/server clock skew. If the user's
+ * `createdAt` is more than this amount *before* the cookie timestamp, the
+ * attribution is rejected (the user already existed before visiting the link).
+ */
+const CLOCK_DRIFT_TOLERANCE_MS = 60 * 1000
+
+/**
+ * Finds the most specific active campaign matching the given UTM params.
+ * Specificity = number of non-null UTM fields that match. A null field on
+ * the campaign acts as a wildcard (matches anything).
+ */
+async function findMatchingCampaign(utmData: Record<string, string>) {
+  const campaigns = await db
+    .select()
+    .from(referralCampaigns)
+    .where(eq(referralCampaigns.isActive, true))
+
+  let bestMatch: (typeof campaigns)[number] | null = null
+  let bestScore = -1
+
+  for (const campaign of campaigns) {
+    let score = 0
+    let mismatch = false
+
+    const fields = [
+      { campaignVal: campaign.utmSource, utmVal: utmData.utm_source },
+      { campaignVal: campaign.utmMedium, utmVal: utmData.utm_medium },
+      { campaignVal: campaign.utmCampaign, utmVal: utmData.utm_campaign },
+      { campaignVal: campaign.utmContent, utmVal: utmData.utm_content },
+    ] as const
+
+    for (const { campaignVal, utmVal } of fields) {
+      if (campaignVal === null) continue
+      if (campaignVal === utmVal) {
+        score++
+      } else {
+        mismatch = true
+        break
+      }
+    }
+
+    if (!mismatch && score > 0) {
+      if (
+        score > bestScore ||
+        (score === bestScore &&
+          bestMatch &&
+          campaign.createdAt.getTime() > bestMatch.createdAt.getTime())
+      ) {
+        bestScore = score
+        bestMatch = campaign
+      }
+    }
+  }
+
+  return bestMatch
+}
+
+export async function POST() {
+  try {
+    const session = await getSession()
+    if (!session?.user?.id) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const cookieStore = await cookies()
+    const utmCookie = cookieStore.get(COOKIE_NAME)
+    if (!utmCookie?.value) {
+      return NextResponse.json({ attributed: false, reason: 'no_utm_cookie' })
+    }
+
+    let utmData: Record<string, string>
+    try {
+      utmData = JSON.parse(decodeURIComponent(utmCookie.value))
+    } catch {
+      logger.warn('Failed to parse UTM cookie', { userId: session.user.id })
+      cookieStore.delete(COOKIE_NAME)
+      return NextResponse.json({ attributed: false, reason: 'invalid_cookie' })
+    }
+
+    // Verify user was created AFTER visiting the UTM link.
+    // The cookie embeds a `created_at` timestamp from when the UTM link was
+    // visited. If `user.createdAt` predates that timestamp (minus a small
+    // clock-drift tolerance), the user already existed and is not eligible.
+    const cookieCreatedAt = Number(utmData.created_at)
+    if (!cookieCreatedAt || !Number.isFinite(cookieCreatedAt)) {
+      logger.warn('UTM cookie missing created_at timestamp', { userId: session.user.id })
+      cookieStore.delete(COOKIE_NAME)
+      return NextResponse.json({ attributed: false, reason: 'invalid_cookie' })
+    }
+
+    const userRows = await db
+      .select({ createdAt: user.createdAt })
+      .from(user)
+      .where(eq(user.id, session.user.id))
+      .limit(1)
+
+    if (userRows.length === 0) {
+      return NextResponse.json({ error: 'User not found' }, { status: 404 })
+    }
+
+    const userCreatedAt = userRows[0].createdAt.getTime()
+    if (userCreatedAt < cookieCreatedAt - CLOCK_DRIFT_TOLERANCE_MS) {
+      logger.info('User account predates UTM cookie, skipping attribution', {
+        userId: session.user.id,
+        userCreatedAt: new Date(userCreatedAt).toISOString(),
+        cookieCreatedAt: new Date(cookieCreatedAt).toISOString(),
+      })
+      cookieStore.delete(COOKIE_NAME)
+      return NextResponse.json({ attributed: false, reason: 'account_predates_cookie' })
+    }
+
+    // Ensure userStats record exists (may not yet for brand-new signups)
+    const [existingStats] = await db
+      .select({ id: userStats.id })
+      .from(userStats)
+      .where(eq(userStats.userId, session.user.id))
+      .limit(1)
+
+    if (!existingStats) {
+      await db.insert(userStats).values({
+        id: nanoid(),
+        userId: session.user.id,
+      })
+    }
+
+    // Look up the matching campaign to determine bonus amount
+    const matchedCampaign = await findMatchingCampaign(utmData)
+    const bonusAmount = matchedCampaign
+      ? Number(matchedCampaign.bonusCreditAmount)
+      : DEFAULT_REFERRAL_BONUS_CREDITS
+
+    // Attribution insert + credit application in a single transaction.
+    // If the credit update fails, the attribution record rolls back so
+    // the client can safely retry on next workspace load.
+    let attributed = false
+    await db.transaction(async (tx) => {
+      const result = await tx
+        .insert(referralAttribution)
+        .values({
+          id: nanoid(),
+          userId: session.user.id,
+          campaignId: matchedCampaign?.id ?? null,
+          utmSource: utmData.utm_source || null,
+          utmMedium: utmData.utm_medium || null,
+          utmCampaign: utmData.utm_campaign || null,
+          utmContent: utmData.utm_content || null,
+          referrerUrl: utmData.referrer_url || null,
+          landingPage: utmData.landing_page || null,
+          bonusCreditAmount: bonusAmount.toString(),
+        })
+        .onConflictDoNothing({ target: referralAttribution.userId })
+        .returning({ id: referralAttribution.id })
+
+      if (result.length > 0) {
+        await applyBonusCredits(session.user.id, bonusAmount, tx)
+        attributed = true
+      }
+    })
+
+    if (attributed) {
+      logger.info('Referral attribution created and bonus credits applied', {
+        userId: session.user.id,
+        campaignId: matchedCampaign?.id,
+        campaignName: matchedCampaign?.name,
+        utmSource: utmData.utm_source,
+        utmCampaign: utmData.utm_campaign,
+        utmContent: utmData.utm_content,
+        bonusAmount,
+      })
+    } else {
+      logger.info('User already attributed, skipping', { userId: session.user.id })
+    }
+
+    cookieStore.delete(COOKIE_NAME)
+
+    return NextResponse.json({
+      attributed,
+      bonusAmount: attributed ? bonusAmount : undefined,
+    })
+  } catch (error) {
+    logger.error('Attribution error', { error })
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+  }
+}

apps/sim/app/api/referral-code/redeem/route.ts

@@ -0,0 +1,157 @@
+import { db } from '@sim/db'
+import { referralAttribution, referralCampaigns, userStats } from '@sim/db/schema'
+import { createLogger } from '@sim/logger'
+import { and, eq } from 'drizzle-orm'
+import { nanoid } from 'nanoid'
+import { NextResponse } from 'next/server'
+import { getSession } from '@/lib/auth'
+import { getHighestPrioritySubscription } from '@/lib/billing/core/subscription'
+import { applyBonusCredits } from '@/lib/billing/credits/bonus'
+
+const logger = createLogger('ReferralCodeRedemption')
+
+export async function POST(request: Request) {
+  try {
+    const session = await getSession()
+    if (!session?.user?.id) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const body = await request.json()
+    const { code } = body
+
+    if (!code || typeof code !== 'string') {
+      return NextResponse.json({ error: 'Code is required' }, { status: 400 })
+    }
+
+    // Determine the user's plan — enterprise users cannot redeem codes
+    const subscription = await getHighestPrioritySubscription(session.user.id)
+
+    if (subscription?.plan === 'enterprise') {
+      return NextResponse.json({
+        redeemed: false,
+        error: 'Enterprise accounts cannot redeem referral codes',
+      })
+    }
+
+    const isTeam = subscription?.plan === 'team'
+    const orgId = isTeam ? subscription.referenceId : null
+
+    // Look up the campaign by code directly (codes are stored uppercased)
+    const normalizedCode = code.trim().toUpperCase()
+
+    const [campaign] = await db
+      .select()
+      .from(referralCampaigns)
+      .where(and(eq(referralCampaigns.code, normalizedCode), eq(referralCampaigns.isActive, true)))
+      .limit(1)
+
+    if (!campaign) {
+      logger.info('Invalid code redemption attempt', {
+        userId: session.user.id,
+        code: normalizedCode,
+      })
+      return NextResponse.json({ error: 'Invalid or expired code' }, { status: 404 })
+    }
+
+    // Check 1: Has this user already redeemed? (one per user, ever)
+    const [existingUserAttribution] = await db
+      .select({ id: referralAttribution.id })
+      .from(referralAttribution)
+      .where(eq(referralAttribution.userId, session.user.id))
+      .limit(1)
+
+    if (existingUserAttribution) {
+      return NextResponse.json({
+        redeemed: false,
+        error: 'You have already redeemed a code',
+      })
+    }
+
+    // Check 2: For team users, has any member of this org already redeemed?
+    // Credits pool to the org, so only one redemption per org is allowed.
+    if (orgId) {
+      const [existingOrgAttribution] = await db
+        .select({ id: referralAttribution.id })
+        .from(referralAttribution)
+        .where(eq(referralAttribution.organizationId, orgId))
+        .limit(1)
+
+      if (existingOrgAttribution) {
+        return NextResponse.json({
+          redeemed: false,
+          error: 'A code has already been redeemed for your organization',
+        })
+      }
+    }
+
+    // Ensure userStats record exists
+    const [existingStats] = await db
+      .select({ id: userStats.id })
+      .from(userStats)
+      .where(eq(userStats.userId, session.user.id))
+      .limit(1)
+
+    if (!existingStats) {
+      await db.insert(userStats).values({
+        id: nanoid(),
+        userId: session.user.id,
+      })
+    }
+
+    const bonusAmount = Number(campaign.bonusCreditAmount)
+
+    // Attribution insert + credit application in a single transaction
+    let redeemed = false
+    await db.transaction(async (tx) => {
+      const result = await tx
+        .insert(referralAttribution)
+        .values({
+          id: nanoid(),
+          userId: session.user.id,
+          organizationId: orgId,
+          campaignId: campaign.id,
+          utmSource: null,
+          utmMedium: null,
+          utmCampaign: null,
+          utmContent: null,
+          referrerUrl: null,
+          landingPage: null,
+          bonusCreditAmount: bonusAmount.toString(),
+        })
+        .onConflictDoNothing()
+        .returning({ id: referralAttribution.id })
+
+      if (result.length > 0) {
+        await applyBonusCredits(session.user.id, bonusAmount, tx)
+        redeemed = true
+      }
+    })
+
+    if (redeemed) {
+      logger.info('Referral code redeemed', {
+        userId: session.user.id,
+        organizationId: orgId,
+        code: normalizedCode,
+        campaignId: campaign.id,
+        campaignName: campaign.name,
+        bonusAmount,
+      })
+    }
+
+    if (!redeemed) {
+      return NextResponse.json({
+        redeemed: false,
+        error: 'You have already redeemed a code',
+      })
+    }
+
+    return NextResponse.json({
+      redeemed: true,
+      bonusAmount,
+    })
+  } catch (error) {
+    logger.error('Referral code redemption error', { error })
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+  }
+}

apps/sim/app/api/v1/admin/referral-campaigns/[id]/route.ts

@@ -0,0 +1,117 @@
+/**
+ * GET   /api/v1/admin/referral-campaigns/:id — Get a single campaign
+ * PATCH /api/v1/admin/referral-campaigns/:id — Update campaign fields
+ */
+
+import { db } from '@sim/db'
+import { referralCampaigns } from '@sim/db/schema'
+import { createLogger } from '@sim/logger'
+import { eq } from 'drizzle-orm'
+import { withAdminAuthParams } from '@/app/api/v1/admin/middleware'
+import {
+  badRequestResponse,
+  internalErrorResponse,
+  notFoundResponse,
+  singleResponse,
+} from '@/app/api/v1/admin/responses'
+
+const logger = createLogger('AdminReferralCampaign')
+
+interface RouteParams {
+  id: string
+}
+
+export const GET = withAdminAuthParams<RouteParams>(async (_request, context) => {
+  try {
+    const { id } = await context.params
+
+    const [campaign] = await db
+      .select()
+      .from(referralCampaigns)
+      .where(eq(referralCampaigns.id, id))
+      .limit(1)
+
+    if (!campaign) {
+      return notFoundResponse('Campaign')
+    }
+
+    return singleResponse(campaign)
+  } catch (error) {
+    logger.error('Failed to get referral campaign', { error })
+    return internalErrorResponse('Failed to get referral campaign')
+  }
+})
+
+export const PATCH = withAdminAuthParams<RouteParams>(async (request, context) => {
+  try {
+    const { id } = await context.params
+    const body = await request.json()
+
+    const [existing] = await db
+      .select()
+      .from(referralCampaigns)
+      .where(eq(referralCampaigns.id, id))
+      .limit(1)
+
+    if (!existing) {
+      return notFoundResponse('Campaign')
+    }
+
+    const updates: Record<string, unknown> = { updatedAt: new Date() }
+
+    if (body.name !== undefined) {
+      if (typeof body.name !== 'string' || !body.name) {
+        return badRequestResponse('name must be a non-empty string')
+      }
+      updates.name = body.name
+    }
+
+    if (body.bonusCreditAmount !== undefined) {
+      if (
+        typeof body.bonusCreditAmount !== 'number' ||
+        !Number.isFinite(body.bonusCreditAmount) ||
+        body.bonusCreditAmount <= 0
+      ) {
+        return badRequestResponse('bonusCreditAmount must be a positive number')
+      }
+      updates.bonusCreditAmount = body.bonusCreditAmount.toString()
+    }
+
+    if (body.isActive !== undefined) {
+      if (typeof body.isActive !== 'boolean') {
+        return badRequestResponse('isActive must be a boolean')
+      }
+      updates.isActive = body.isActive
+    }
+
+    if (body.code !== undefined) {
+      if (body.code !== null && typeof body.code !== 'string') {
+        return badRequestResponse('code must be a string or null')
+      }
+      updates.code = body.code ? body.code.trim().toUpperCase() : null
+    }
+
+    // UTM fields can be set to string or null (null = wildcard)
+    for (const field of ['utmSource', 'utmMedium', 'utmCampaign', 'utmContent'] as const) {
+      if (body[field] !== undefined) {
+        if (body[field] !== null && typeof body[field] !== 'string') {
+          return badRequestResponse(`${field} must be a string or null`)
+        }
+        updates[field] = body[field]
+      }
+    }
+
+    const [updated] = await db
+      .update(referralCampaigns)
+      .set(updates)
+      .where(eq(referralCampaigns.id, id))
+      .returning()
+
+    logger.info('Updated referral campaign', { id, updates })
+
+    return singleResponse(updated)
+  } catch (error) {
+    logger.error('Failed to update referral campaign', { error })
+    return internalErrorResponse('Failed to update referral campaign')
+  }
+})

apps/sim/app/api/v1/admin/referral-campaigns/route.ts

@@ -0,0 +1,108 @@
+/**
+ * GET  /api/v1/admin/referral-campaigns — List all campaigns (optional ?active=true filter)
+ * POST /api/v1/admin/referral-campaigns — Create a new campaign
+ */
+
+import { db } from '@sim/db'
+import { referralCampaigns } from '@sim/db/schema'
+import { createLogger } from '@sim/logger'
+import { eq } from 'drizzle-orm'
+import { nanoid } from 'nanoid'
+import { withAdminAuth } from '@/app/api/v1/admin/middleware'
+import {
+  badRequestResponse,
+  internalErrorResponse,
+  listResponse,
+  singleResponse,
+} from '@/app/api/v1/admin/responses'
+import { createPaginationMeta, parsePaginationParams } from '@/app/api/v1/admin/types'
+
+const logger = createLogger('AdminReferralCampaigns')
+
+export const GET = withAdminAuth(async (request) => {
+  try {
+    const url = new URL(request.url)
+    const { limit, offset } = parsePaginationParams(url)
+    const activeFilter = url.searchParams.get('active')
+
+    let query = db.select().from(referralCampaigns).$dynamic()
+
+    if (activeFilter === 'true') {
+      query = query.where(eq(referralCampaigns.isActive, true))
+    } else if (activeFilter === 'false') {
+      query = query.where(eq(referralCampaigns.isActive, false))
+    }
+
+    const rows = await query.limit(limit).offset(offset)
+
+    // Count total for pagination
+    let countQuery = db.select().from(referralCampaigns).$dynamic()
+    if (activeFilter === 'true') {
+      countQuery = countQuery.where(eq(referralCampaigns.isActive, true))
+    } else if (activeFilter === 'false') {
+      countQuery = countQuery.where(eq(referralCampaigns.isActive, false))
+    }
+    const allRows = await countQuery
+    const total = allRows.length
+
+    return listResponse(rows, createPaginationMeta(total, limit, offset))
+  } catch (error) {
+    logger.error('Failed to list referral campaigns', { error })
+    return internalErrorResponse('Failed to list referral campaigns')
+  }
+})
+
+export const POST = withAdminAuth(async (request) => {
+  try {
+    const body = await request.json()
+    const { name, code, utmSource, utmMedium, utmCampaign, utmContent, bonusCreditAmount } = body
+
+    if (!name || typeof name !== 'string') {
+      return badRequestResponse('name is required and must be a string')
+    }
+
+    if (
+      typeof bonusCreditAmount !== 'number' ||
+      !Number.isFinite(bonusCreditAmount) ||
+      bonusCreditAmount <= 0
+    ) {
+      return badRequestResponse('bonusCreditAmount must be a positive number')
+    }
+
+    if (code !== undefined && code !== null && typeof code !== 'string') {
+      return badRequestResponse('code must be a string or null')
+    }
+
+    const id = nanoid()
+
+    const [campaign] = await db
+      .insert(referralCampaigns)
+      .values({
+        id,
+        name,
+        code: code ? code.trim().toUpperCase() : null,
+        utmSource: utmSource || null,
+        utmMedium: utmMedium || null,
+        utmCampaign: utmCampaign || null,
+        utmContent: utmContent || null,
+        bonusCreditAmount: bonusCreditAmount.toString(),
+      })
+      .returning()
+
+    logger.info('Created referral campaign', {
+      id,
+      name,
+      code: campaign.code,
+      utmSource,
+      utmMedium,
+      utmCampaign,
+      utmContent,
+      bonusCreditAmount,
+    })
+
+    return singleResponse(campaign)
+  } catch (error) {
+    logger.error('Failed to create referral campaign', { error })
+    return internalErrorResponse('Failed to create referral campaign')
+  }
+})

apps/sim/app/workspace/[workspaceId]/w/components/sidebar/components/settings-modal/components/subscription/components/index.ts

@@ -1,3 +1,4 @@
 export { CancelSubscription } from './cancel-subscription'
 export { CreditBalance } from './credit-balance'
 export { PlanCard, type PlanCardProps, type PlanFeature } from './plan-card'
+export { ReferralCode } from './referral-code'

apps/sim/app/workspace/[workspaceId]/w/components/sidebar/components/settings-modal/components/subscription/components/referral-code/index.ts

@@ -0,0 +1 @@
+export { ReferralCode } from './referral-code'

apps/sim/app/workspace/[workspaceId]/w/components/sidebar/components/settings-modal/components/subscription/components/referral-code/referral-code.tsx

@@ -0,0 +1,101 @@
+'use client'
+
+import { useState } from 'react'
+import { createLogger } from '@sim/logger'
+import { Button, Input, Label } from '@/components/emcn'
+
+const logger = createLogger('ReferralCode')
+
+interface ReferralCodeProps {
+  onRedeemComplete?: () => void
+}
+
+/**
+ * Inline referral/promo code entry field with redeem button.
+ * One-time use per account — shows success or "already redeemed" state.
+ */
+export function ReferralCode({ onRedeemComplete }: ReferralCodeProps) {
+  const [code, setCode] = useState('')
+  const [isRedeeming, setIsRedeeming] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [success, setSuccess] = useState<{ bonusAmount: number } | null>(null)
+
+  const handleRedeem = async () => {
+    const trimmed = code.trim()
+    if (!trimmed || isRedeeming) return
+
+    setIsRedeeming(true)
+    setError(null)
+
+    try {
+      const response = await fetch('/api/referral-code/redeem', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ code: trimmed }),
+      })
+
+      const data = await response.json()
+
+      if (!response.ok) {
+        throw new Error(data.error || 'Failed to redeem code')
+      }
+
+      if (data.redeemed) {
+        setSuccess({ bonusAmount: data.bonusAmount })
+        setCode('')
+        onRedeemComplete?.()
+      } else {
+        setError(data.error || 'Code could not be redeemed')
+      }
+    } catch (err) {
+      logger.error('Referral code redemption failed', { error: err })
+      setError(err instanceof Error ? err.message : 'Failed to redeem code')
+    } finally {
+      setIsRedeeming(false)
+    }
+  }
+
+  if (success) {
+    return (
+      <div className='flex items-center justify-between'>
+        <Label>Referral Code</Label>
+        <span className='text-[12px] text-[var(--text-secondary)]'>
+          +${success.bonusAmount} credits applied
+        </span>
+      </div>
+    )
+  }
+
+  return (
+    <div className='flex items-center justify-between gap-[12px]'>
+      <Label className='shrink-0'>Referral Code</Label>
+      <div className='flex items-center gap-[8px]'>
+        <div className='flex flex-col'>
+          <Input
+            type='text'
+            value={code}
+            onChange={(e) => {
+              setCode(e.target.value)
+              setError(null)
+            }}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter') handleRedeem()
+            }}
+            placeholder='Enter code'
+            className='h-[32px] w-[140px] text-[12px]'
+            disabled={isRedeeming}
+          />
+          {error && <span className='mt-[4px] text-[11px] text-[var(--text-error)]'>{error}</span>}
+        </div>
+        <Button
+          variant='active'
+          className='h-[32px] shrink-0 rounded-[6px] text-[12px]'
+          onClick={handleRedeem}
+          disabled={isRedeeming || !code.trim()}
+        >
+          {isRedeeming ? 'Redeeming...' : 'Redeem'}
+        </Button>
+      </div>
+    </div>
+  )
+}

apps/sim/app/workspace/[workspaceId]/w/components/sidebar/components/settings-modal/components/subscription/subscription.tsx

@@ -17,6 +17,7 @@ import {
   CancelSubscription,
   CreditBalance,
   PlanCard,
+  ReferralCode,
 } from '@/app/workspace/[workspaceId]/w/components/sidebar/components/settings-modal/components/subscription/components'
 import {
   ENTERPRISE_PLAN_FEATURES,
@@ -549,6 +550,11 @@ export function Subscription() {
         />
       )}
 
+      {/* Referral Code — hidden from enterprise users */}
+      {!subscription.isEnterprise && (
+        <ReferralCode onRedeemComplete={() => refetchSubscription()} />
+      )}
+
       {/* Next Billing Date - hidden from team members */}
       {subscription.isPaid &&
         subscriptionData?.data?.periodEnd &&

apps/sim/app/workspace/page.tsx

@@ -4,12 +4,14 @@ import { useEffect } from 'react'
 import { createLogger } from '@sim/logger'
 import { useRouter } from 'next/navigation'
 import { useSession } from '@/lib/auth/auth-client'
+import { useReferralAttribution } from '@/hooks/use-referral-attribution'
 
 const logger = createLogger('WorkspacePage')
 
 export default function WorkspacePage() {
   const router = useRouter()
   const { data: session, isPending } = useSession()
+  useReferralAttribution()
 
   useEffect(() => {
     const redirectToFirstWorkspace = async () => {

apps/sim/hooks/use-referral-attribution.ts

@@ -0,0 +1,40 @@
+'use client'
+
+import { useEffect, useRef } from 'react'
+import { createLogger } from '@sim/logger'
+
+const logger = createLogger('ReferralAttribution')
+
+const COOKIE_NAME = 'sim_utm'
+
+/** Terminal reasons that should not be retried. */
+const TERMINAL_REASONS = new Set(['account_predates_cookie', 'invalid_cookie'])
+
+export function useReferralAttribution() {
+  const calledRef = useRef(false)
+
+  useEffect(() => {
+    if (calledRef.current) return
+    if (!document.cookie.includes(COOKIE_NAME)) return
+
+    calledRef.current = true
+
+    fetch('/api/attribution', { method: 'POST' })
+      .then((res) => res.json())
+      .then((data) => {
+        if (data.attributed) {
+          logger.info('Referral attribution successful', { bonusAmount: data.bonusAmount })
+        } else if (data.error || TERMINAL_REASONS.has(data.reason)) {
+          // Terminal — don't retry
+          logger.info('Referral attribution skipped', { reason: data.reason || data.error })
+        } else {
+          // Non-terminal (e.g. transient failure) — allow retry on next mount
+          calledRef.current = false
+        }
+      })
+      .catch((err) => {
+        logger.warn('Referral attribution failed, will retry', { error: err })
+        calledRef.current = false
+      })
+  }, [])
+}

apps/sim/lib/billing/credits/bonus.ts

@@ -0,0 +1,64 @@
+import { db } from '@sim/db'
+import { organization, userStats } from '@sim/db/schema'
+import { createLogger } from '@sim/logger'
+import { eq, sql } from 'drizzle-orm'
+import { getHighestPrioritySubscription } from '@/lib/billing/core/subscription'
+import type { DbOrTx } from '@/lib/db/types'
+
+const logger = createLogger('BonusCredits')
+
+/**
+ * Apply bonus credits to a user (e.g. referral bonuses, promotional codes).
+ *
+ * Detects the user's current plan and routes credits accordingly:
+ * - Free/Pro: adds to `userStats.creditBalance` and increments `currentUsageLimit`
+ * - Team/Enterprise: adds to `organization.creditBalance` and increments `orgUsageLimit`
+ *
+ * Uses direct increment (not recalculation) so it works correctly for free-tier
+ * users where `setUsageLimitForCredits` would compute planBase=0 and skip the update.
+ *
+ * @param tx - Optional Drizzle transaction context. When provided, all DB writes
+ *             participate in the caller's transaction for atomicity.
+ */
+export async function applyBonusCredits(
+  userId: string,
+  amount: number,
+  tx?: DbOrTx
+): Promise<void> {
+  const dbCtx = tx ?? db
+  const subscription = await getHighestPrioritySubscription(userId)
+  const isTeamOrEnterprise = subscription?.plan === 'team' || subscription?.plan === 'enterprise'
+
+  if (isTeamOrEnterprise && subscription?.referenceId) {
+    const orgId = subscription.referenceId
+
+    await dbCtx
+      .update(organization)
+      .set({
+        creditBalance: sql`${organization.creditBalance} + ${amount}`,
+        orgUsageLimit: sql`COALESCE(${organization.orgUsageLimit}, '0')::decimal + ${amount}`,
+      })
+      .where(eq(organization.id, orgId))
+
+    logger.info('Applied bonus credits to organization', {
+      userId,
+      organizationId: orgId,
+      plan: subscription.plan,
+      amount,
+    })
+  } else {
+    await dbCtx
+      .update(userStats)
+      .set({
+        creditBalance: sql`${userStats.creditBalance} + ${amount}`,
+        currentUsageLimit: sql`COALESCE(${userStats.currentUsageLimit}, '0')::decimal + ${amount}`,
+      })
+      .where(eq(userStats.userId, userId))
+
+    logger.info('Applied bonus credits to user', {
+      userId,
+      plan: subscription?.plan || 'free',
+      amount,
+    })
+  }
+}

packages/db/constants.ts

@@ -8,6 +8,11 @@
  */
 export const DEFAULT_FREE_CREDITS = 20
 
+/**
+ * Default bonus credits (in dollars) for referral signups
+ */
+export const DEFAULT_REFERRAL_BONUS_CREDITS = 10
+
 /**
  * Storage limit constants (in GB)
  * Can be overridden via environment variables

packages/db/migrations/0154_many_vindicator.sql

@@ -0,0 +1,42 @@
+CREATE TABLE "referral_attribution" (
+	"id" text PRIMARY KEY NOT NULL,
+	"user_id" text NOT NULL,
+	"organization_id" text,
+	"campaign_id" text,
+	"utm_source" text,
+	"utm_medium" text,
+	"utm_campaign" text,
+	"utm_content" text,
+	"referrer_url" text,
+	"landing_page" text,
+	"bonus_credit_amount" numeric DEFAULT '0' NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "referral_attribution_user_id_unique" UNIQUE("user_id")
+);
+--> statement-breakpoint
+CREATE TABLE "referral_campaigns" (
+	"id" text PRIMARY KEY NOT NULL,
+	"name" text NOT NULL,
+	"code" text,
+	"utm_source" text,
+	"utm_medium" text,
+	"utm_campaign" text,
+	"utm_content" text,
+	"bonus_credit_amount" numeric NOT NULL,
+	"is_active" boolean DEFAULT true NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "referral_campaigns_code_unique" UNIQUE("code")
+);
+--> statement-breakpoint
+ALTER TABLE "referral_attribution" ADD CONSTRAINT "referral_attribution_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "referral_attribution" ADD CONSTRAINT "referral_attribution_organization_id_organization_id_fk" FOREIGN KEY ("organization_id") REFERENCES "public"."organization"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "referral_attribution" ADD CONSTRAINT "referral_attribution_campaign_id_referral_campaigns_id_fk" FOREIGN KEY ("campaign_id") REFERENCES "public"."referral_campaigns"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "referral_attribution_user_id_idx" ON "referral_attribution" USING btree ("user_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "referral_attribution_org_unique_idx" ON "referral_attribution" USING btree ("organization_id") WHERE "referral_attribution"."organization_id" IS NOT NULL;--> statement-breakpoint
+CREATE INDEX "referral_attribution_campaign_id_idx" ON "referral_attribution" USING btree ("campaign_id");--> statement-breakpoint
+CREATE INDEX "referral_attribution_utm_campaign_idx" ON "referral_attribution" USING btree ("utm_campaign");--> statement-breakpoint
+CREATE INDEX "referral_attribution_utm_content_idx" ON "referral_attribution" USING btree ("utm_content");--> statement-breakpoint
+CREATE INDEX "referral_attribution_created_at_idx" ON "referral_attribution" USING btree ("created_at");--> statement-breakpoint
+CREATE INDEX "referral_campaigns_active_idx" ON "referral_campaigns" USING btree ("is_active");--> statement-breakpoint
+CREATE UNIQUE INDEX "referral_campaigns_code_idx" ON "referral_campaigns" USING btree ("code");

packages/db/migrations/meta/_journal.json

@@ -1072,6 +1072,13 @@
       "when": 1770410282842,
       "tag": "0153_complete_arclight",
       "breakpoints": true
+    },
+    {
+      "idx": 154,
+      "version": "7",
+      "when": 1770839615891,
+      "tag": "0154_many_vindicator",
+      "breakpoints": true
     }
   ]
 }

packages/db/schema.ts

@@ -726,6 +726,62 @@ export const userStats = pgTable('user_stats', {
   billingBlockedReason: billingBlockedReasonEnum('billing_blocked_reason'),
 })
 
+export const referralCampaigns = pgTable(
+  'referral_campaigns',
+  {
+    id: text('id').primaryKey(),
+    name: text('name').notNull(),
+    code: text('code').unique(),
+    utmSource: text('utm_source'),
+    utmMedium: text('utm_medium'),
+    utmCampaign: text('utm_campaign'),
+    utmContent: text('utm_content'),
+    bonusCreditAmount: decimal('bonus_credit_amount').notNull(),
+    isActive: boolean('is_active').notNull().default(true),
+    createdAt: timestamp('created_at').notNull().defaultNow(),
+    updatedAt: timestamp('updated_at').notNull().defaultNow(),
+  },
+  (table) => ({
+    activeIdx: index('referral_campaigns_active_idx').on(table.isActive),
+    codeIdx: uniqueIndex('referral_campaigns_code_idx').on(table.code),
+  })
+)
+
+export const referralAttribution = pgTable(
+  'referral_attribution',
+  {
+    id: text('id').primaryKey(),
+    userId: text('user_id')
+      .notNull()
+      .references(() => user.id, { onDelete: 'cascade' })
+      .unique(),
+    organizationId: text('organization_id').references(() => organization.id, {
+      onDelete: 'set null',
+    }),
+    campaignId: text('campaign_id').references(() => referralCampaigns.id, {
+      onDelete: 'set null',
+    }),
+    utmSource: text('utm_source'),
+    utmMedium: text('utm_medium'),
+    utmCampaign: text('utm_campaign'),
+    utmContent: text('utm_content'),
+    referrerUrl: text('referrer_url'),
+    landingPage: text('landing_page'),
+    bonusCreditAmount: decimal('bonus_credit_amount').notNull().default('0'),
+    createdAt: timestamp('created_at').notNull().defaultNow(),
+  },
+  (table) => ({
+    userIdIdx: index('referral_attribution_user_id_idx').on(table.userId),
+    orgUniqueIdx: uniqueIndex('referral_attribution_org_unique_idx')
+      .on(table.organizationId)
+      .where(sql`${table.organizationId} IS NOT NULL`),
+    campaignIdIdx: index('referral_attribution_campaign_id_idx').on(table.campaignId),
+    utmCampaignIdx: index('referral_attribution_utm_campaign_idx').on(table.utmCampaign),
+    utmContentIdx: index('referral_attribution_utm_content_idx').on(table.utmContent),
+    createdAtIdx: index('referral_attribution_created_at_idx').on(table.createdAt),
+  })
+)
+
 export const customTools = pgTable(
   'custom_tools',
   {