DEV Community: sweet

SaaS Security Best Practices: Auth, Authorization, and Data Protection

sweet — Fri, 03 Jul 2026 00:35:00 +0000

Security is not a feature — it is a property of your entire architecture. This guide covers the security practices implemented in production SaaS applications like tanstackship.com: authentication with password hashing and session management, role-based and attribute-based authorization, data encryption at rest and in transit, API security with CSRF and rate limiting, and ongoing monitoring for vulnerabilities.

Authentication: The Identity Layer

Session vs Token-Based Auth

Aspect	Session Auth	JWT Auth	Hybrid (Recommended)
Storage	Server-side (D1/Redis)	Client-side (localStorage)	Server + client
Expiry	Server-managed	Self-contained	Dual expiry
Revocation	Immediate	Difficult (until expiry)	Session invalidation + JWT refresh
Scale	Database lookups per request	Stateless	Cached sessions
XSS risk	Lower (HTTP-only cookie)	Higher (JS-accessible)	HTTP-only cookie for session

Implementation with Better Auth

// src/lib/auth.ts — using Better Auth with Drizzle
import { betterAuth } from "better-auth"
import { drizzleAdapter } from "better-auth/adapters/drizzle"
import { createDb } from "../db"

export const auth = betterAuth({
  database: drizzleAdapter(createDb(env), {
    provider: "sqlite",
  }),
  emailAndPassword: {
    enabled: true,
    autoSignIn: true,
    passwordHash: {
      algorithm: "argon2", // Argon2id — OWASP recommended
      params: {
        memoryCost: 19456,
        timeCost: 2,
        parallelism: 1,
      },
    },
  },
  socialProviders: {
    google: { clientId: env.GOOGLE_CLIENT_ID, clientSecret: env.GOOGLE_CLIENT_SECRET },
    github: { clientId: env.GITHUB_CLIENT_ID, clientSecret: env.GITHUB_CLIENT_SECRET },
  },
  session: {
    expiresIn: 7 * 24 * 60 * 60, // 7 days
    updateAge: 24 * 60 * 60, // Refresh every 24 hours
  },
})

Password Security Checklist

[ ] Passwords hashed with Argon2id (not bcrypt, not scrypt)
[ ] Minimum 8 characters, no arbitrary complexity rules
[ ] Rate-limited login attempts (5 per minute per IP)
[ ] Email verification required before first login
[ ] Session tokens stored in HTTP-only, Secure, SameSite=Strict cookies
[ ] Session rotation on login and privilege escalation
[ ] MFA available (TOTP or WebAuthn)
[ ] Account lockout after 10 failed attempts

Authorization: Who Can Do What

Role-Based Access Control (RBAC)

// src/lib/auth.ts
export const roles = {
  admin: {
    permissions: [
      "user:*",
      "subscription:*",
      "billing:*",
      "settings:*",
      "analytics:*",
    ],
  },
  member: {
    permissions: [
      "user:read",
      "subscription:read",
      "settings:read",
      "settings:update",
    ],
  },
  viewer: {
    permissions: ["user:read", "subscription:read"],
  },
}

// Middleware guard
export function requirePermission(permission: string) {
  return createServerFn({ method: "GET" }).handler(
    async ({}, { context }) => {
      const userRole = context.user.role as keyof typeof roles
      const allowed = roles[userRole]?.permissions.some(
        (p) => p === permission || p.endsWith(":*")
      )

      if (!allowed) {
        throw new Error("Forbidden")
      }
    }
  )
}

Organization Scoping

Every SaaS with multiple users needs data isolation:

// Ensure all queries are scoped to the user's organization
export const getTeamSubscriptions = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    // context.user.orgId is set by auth middleware
    const subscriptions = await env.DB.prepare(`
      SELECT * FROM subscriptions
      WHERE organization_id = ?
      ORDER BY created_at DESC
    `).bind(context.user.orgId).all()

    return subscriptions.results
  }
)

Authorization Patterns

Pattern	Description	When to Use
RBAC	Role-based permissions	Simple apps, small teams
ABAC	Attribute-based (resource owner, department)	Multi-tenant, complex orgs
ReBAC	Relationship-based (Google Zanzibar model)	Large-scale, nested orgs
Permissions as Data	Permissions stored in database, checked at runtime	User-customizable roles

Data Protection

Encryption at Rest

Cloudflare D1 encrypts all data at rest by default. For additional protection, encrypt sensitive fields before storing:

// Encrypt PII before storing in D1
import { AesGcm } from "@cloudflare/workers-types"

export const encryptField = async (plaintext: string, key: CryptoKey) => {
  const iv = crypto.getRandomValues(new Uint8Array(12))
  const encoded = new TextEncoder().encode(plaintext)

  const ciphertext = await crypto.subtle.encrypt(
    { name: "AES-GCM", iv },
    key,
    encoded
  )

  return {
    ciphertext: arrayBufferToBase64(ciphertext),
    iv: arrayBufferToBase64(iv),
  }
}

export const decryptField = async (
  ciphertext: string,
  iv: string,
  key: CryptoKey
) => {
  const decrypted = await crypto.subtle.decrypt(
    { name: "AES-GCM", iv: base64ToArrayBuffer(iv) },
    key,
    base64ToArrayBuffer(ciphertext)
  )

  return new TextDecoder().decode(decrypted)
}

HTTPS and Headers

// middleware.ts — TanStack Router middleware
export const Route = createRootRouteWithContext()({
  beforeLoad: async ({ context }) => {
    // Security headers
    context.response.headers.set(
      "Content-Security-Policy",
      "default-src 'self'; script-src 'self' 'unsafe-inline' https://analytics.tanstackship.com; style-src 'self' 'unsafe-inline'"
    )
    context.response.headers.set("Strict-Transport-Security", "max-age=31536000; includeSubDomains")
    context.response.headers.set("X-Content-Type-Options", "nosniff")
    context.response.headers.set("X-Frame-Options", "DENY")
    context.response.headers.set("Referrer-Policy", "strict-origin-when-cross-origin")
  },
})

API Security

Rate Limiting

// server/middleware/rate-limit.ts
import { createServerFn } from "@tanstack/react-start"

const rateLimitStore = new Map<string, { count: number; resetAt: number }>()

export function rateLimit(limit: number, windowMs: number) {
  return async (request: Request): Promise<boolean> => {
    const ip = request.headers.get("CF-Connecting-IP") ?? "unknown"
    const key = `${ip}:${request.url}`
    const now = Date.now()

    const entry = rateLimitStore.get(key)

    if (!entry || entry.resetAt < now) {
      rateLimitStore.set(key, { count: 1, resetAt: now + windowMs })
      return true
    }

    if (entry.count >= limit) {
      return false // Rate limited
    }

    entry.count++
    return true
  }
}

// Usage in server function
export const login = createServerFn({ method: "POST" }).handler(
  async ({ request }) => {
    const allowed = await rateLimit(5, 60_000)(request) // 5 attempts per minute
    if (!allowed) {
      throw new Error("Too many requests. Try again later.")
    }
    // ... login logic
  }
)

CSRF Protection

// TanStack Start includes CSRF protection via server functions
// All POST/PUT/DELETE server functions include a CSRF token in the request

// The CSRF token is automatically attached by the client SDK:
createServerFn({ method: "POST" })
  .handler(async ({ request }) => {
    // request.headers includes X-CSRF-Token
    // Validated automatically by TanStack Start
  })

API Input Validation

import { z } from "zod"

const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2).max(100),
  role: z.enum(["admin", "member"]).optional(),
})

export const createUser = createServerFn({ method: "POST" })
  .validator((data: unknown) => createUserSchema.parse(data))
  .handler(async ({ data }) => {
    // data is validated and typed as { email: string; name: string; role?: string }
    // Never trust raw input from the client
  })

Security Monitoring

Incident Detection

// server/security/audit-log.ts
export const logSecurityEvent = createServerFn({ method: "POST" }).handler(
  async ({ data }: { data: SecurityEvent }) => {
    await env.DB.prepare(`
      INSERT INTO audit_log (id, user_id, event_type, ip_address, metadata, created_at)
      VALUES (?, ?, ?, ?, ?, ?)
    `).bind(
      crypto.randomUUID(),
      data.userId,
      data.eventType,
      data.ipAddress,
      JSON.stringify(data.metadata),
      Date.now()
    ).run()

    // Alert on suspicious events
    if (["failed_login", "password_change", "role_escalation"].includes(data.eventType)) {
      await sendAlert(data)
    }
  }
)

Logged Security Events

Event	Action	Severity
`login_success`	Log	Info
`login_failed`	Log + count	Medium (after 5: high)
`password_reset`	Log + notify user	Medium
`email_changed`	Log + notify old email	High
`role_changed`	Log + notify admin	High
`api_key_created`	Log	Medium
`suspicious_ip`	Log + block	High

Production Security Checklist

[ ] All passwords hashed with Argon2id
[ ] All authenticated routes require session validation
[ ] All data queries scoped to user's organization
[ ] Rate limiting on auth endpoints and public APIs
[ ] CSP headers configured (strict mode)
[ ] CORS restricted to known origins
[ ] SQL injection prevented (parameterized queries via Drizzle)
[ ] XSS prevented (React auto-escapes output)
[ ] CSRF protection enabled
[ ] Security audit log with retention policy
[ ] npm audit run weekly
[ ] Dependencies updated within 14 days of security patch
[ ] Secrets managed via environment variables (not committed)
[ ] D1 backup configured (automatic with Cloudflare)
[ ] Session expiry and rotation configured

Dependency Security

# Regular vulnerability scanning
npm audit
# Or use GitHub Dependabot for automated PRs

# Critical packages to keep updated:
# - better-auth (authentication)
# - @tanstack/react-router (routing middleware)
# - @tanstack/react-query (data fetching)
# - drizzle-orm (database)
# - zod (input validation)

Conclusion

Security in a SaaS application is a layered concern. You cannot solve it with a single library or configuration file — it requires attention at every layer of the stack:

Authentication: Strong password hashing, session management, MFA
Authorization: Role-based or attribute-based access control
Data protection: Encryption, secure headers, input validation
API security: Rate limiting, CSRF, CORS
Monitoring: Audit logging, anomaly detection, dependency scanning

The good news: most of these practices can be implemented once and applied universally. A well-configured auth library handles authentication. A middleware layer handles authorization. Security headers are set in a single configuration file.

For a SaaS starter that implements these security patterns out of the box, see tanstackship.com.

Related Resources

SaaS Pricing Strategy Playbook: From Free to Revenue

sweet — Thu, 02 Jul 2026 00:33:00 +0000

Pricing is the single most powerful lever you have for growing SaaS revenue — yet most founders treat it as an afterthought. A 1% price increase can yield an 8-12% increase in operating profit, far more than acquiring the same revenue through new customers. This playbook covers the five core decisions every SaaS company must make: monetization model, value metric, tier structure, psychological pricing tactics, and pricing page optimization.

Introduction: Why Pricing Is Your Most Important Growth Lever

When founders think about growth, they typically reach for familiar levers: more marketing spend, bigger sales teams, viral features. But pricing is the one lever that touches every single customer interaction — and it costs nothing to change.

Consider this: if you raise prices by 1% and lose 1% of customers, your net revenue still increases. The math works because the lost customers are often your least price-sensitive ones. In practice, companies that run pricing experiments typically find they can increase prices by 5-15% before seeing any meaningful impact on conversion.

Yet pricing is also where most SaaS companies are at their most irrational. We underprice out of fear, copy competitors without understanding why, and avoid changes because we're afraid of customer backlash.

Freemium vs Free Trial vs Paid-First

Freemium

Freemium offers a permanently free tier with limited features. It's a top-of-funnel machine — but it requires low marginal cost per user and a clear upgrade path.

Aspect	Freemium
Best for	Products with viral loops, network effects
Conversion rate	Typically 2-5% free-to-paid
Risk	High support cost for free users
Example	Slack, Notion, Canva

Free Trial (Time-Limited)

Time-limited trials give full access for 7-30 days, then require payment.

Aspect	Free Trial
Best for	Products with immediate value delivery
Conversion rate	Typically 10-25% trial-to-paid
Risk	Users forget to use the trial
Example	GitHub, Figma, Intercom

The biggest mistake teams make: treating trials as passive. A 14-day trial with zero onboarding emails will convert at half the rate of an active one.

Paid-First

Paid-first means requiring a credit card before any access. This is common in vertical SaaS where the buyer has clear intent.

Aspect	Paid-First
Best for	Niche tools, high-value B2B
Risk	Harder to build community
Example	JetBrains, Linear (early days), Superhuman

Recommendation: If you're early-stage, start with a 14-day free trial (no credit card required). It gives you the most data about usage patterns and willingness to pay.

Value Metrics: What Should You Charge For?

The value metric is the unit your price is based on — seats, API calls, storage, or outcomes. Choosing the wrong metric is one of the most expensive mistakes a SaaS company can make.

The Three Rules of Value Metrics

Align with customer value. Your metric should rise as the customer gets more value.
Predictable for the customer. Variable pricing is fine, but the customer should forecast their bill.
Scalable for you. The metric should naturally grow as the customer's business grows.

Common Value Metrics

Metric	Example	When It Works
Per seat/user	Slack, GitHub	Collaboration tools
Usage/consumption	AWS, Stripe	Value scales linearly with volume
Tiered feature access	Canva Pro	Different segments need different capabilities
Active users	Mixpanel, HubSpot	Better than total seats
Outcome-based	Shopify (per transaction)	Platform businesses

The Per-Seat Trap

Per-seat pricing is simple but dangerous. It penalizes collaboration — exactly what most SaaS tools encourage. A better approach for collaboration-centric products: use "active users" or "projects" instead of total seats.

Tier Design: The Art of the Three-Pack

The vast majority of successful SaaS companies use three pricing tiers. Why? Because three creates a contrast that drives decision-making.

The Three-Tier Framework

Starter / Free — Low or no cost. Captures budget-conscious buyers. Intentionally limited.
Pro / Growth — The sweet spot. Where the bulk of your revenue should come from.
Enterprise / Scale — High price, often custom. Serves the fully-baked customer with compliance, SSO, and SLAs.

Feature Differentiation Strategy

The goal is not to nickel-and-dime customers — it's to create a clear "good, better, best" story:

Feature Category	Starter	Pro	Enterprise
Core functionality	Limited	Full	Full + extras
Usage limits	Low cap	High cap	Custom
Support	Community	Email/chat	Dedicated + SLA
Advanced features	No	Yes	Yes
Enterprise security	No	No	SSO, SOC2

Golden Rule of Tiers

Never remove features from an existing tier when adding a higher one. Instead, add new capabilities to higher tiers. This prevents customer backlash and preserves upgrade paths.

Psychological Pricing: Small Changes, Big Impact

Pricing isn't a math problem — it's a psychology problem.

Charm Pricing

Prices ending in 9 (e.g., $29 vs $30) consistently outperform round numbers by 1-3%. However, for premium SaaS positioning, round numbers ($200/mo instead of $199/mo) signal quality and confidence.

The Decoy Effect

Adding a third option that makes one of the other two look dramatically better:

Pro: $29/mo (100 users)
Business: $59/mo (500 users)
Decoy: $49/mo (150 users)

The decoy exists to make Business look like an incredible deal. When used properly, decoy pricing can shift 15-25% of undecided buyers to the higher tier.

Price Anchoring

Show the most expensive option first on your pricing page. Research shows that when the enterprise tier is displayed first, average order value increases by 8-12%. The high price "anchors" the buyer's perception.

Annual vs Monthly

Most SaaS companies offer a 15-25% discount for annual prepayment. Companies with a well-designed annual vs monthly toggle see 30-60% of new customers choosing annual. Highlight the annual savings with a colored badge or "most popular" tag.

Pricing Page Best Practices

Your pricing page is the highest-leverage page on your website:

Feature comparison table. Use checkmarks for included features.
CTA per tier. "Start Free Trial," "Get Started," "Contact Sales."
Annual toggle. Prominently display the monthly/annual switch.
FAQ directly below. Answer common objections before they arise.
Social proof. Logo bars, testimonials near the pricing table.
Money-back guarantee. A 30-day risk reversal removes the final objection.

Data point: Companies that add a testimonial below their pricing table see an average 15-20% improvement in conversion rate.

When and How to Change Prices

You will need to raise prices. It's inevitable. The question is whether you do it well or poorly.

When to Raise Prices

After adding meaningful new features
When your current price is below competitor pricing
When unit economics show negative LTV/CAC
Annually, as standard practice

How to Raise Prices (The Right Way)

Grandfather existing customers. Never force existing customers onto a new price.
Communicate the "why." Send an email explaining what has improved.
Give advance notice. 30 days minimum.
Offer a loyalty discount. Lock in current rates for loyal customers.

Grandfathering creates incredible goodwill. Buffer famously grandfathers prices forever — customers who signed up in 2013 still pay the 2013 rate.

Real-World Data Points

Practice	Impact
Adding a free trial (vs paid-first)	2-4x more signups
Annual prepay discount (20%)	30-60% adoption rate
Three tiers vs two	10-20% higher ARPU
Charm pricing ($29 vs $30)	1-3% conversion lift
Price anchoring (high tier first)	8-12% higher AOV
Pricing page FAQ section	15-20% conversion improvement

Conclusion

Pricing is not a set-it-and-forget-it decision. It's a continuous practice of understanding your customers, testing assumptions, and aligning what you charge with the value you deliver.

The companies that get pricing right don't have magical insight — they simply treat pricing with the same rigor they apply to product development. They run experiments. They listen to churn signals. They iteratively optimize.

Start with the framework in this playbook, pick one area to improve this week (your value metric, your tier structure, or your pricing page), and ship it. The revenue will follow.

Related Resources

SaaS Pricing Psychology: Anchoring, Scarcity, and Reciprocity in Subscription Design

sweet — Wed, 01 Jul 2026 00:29:00 +0000

Pricing is not just economics — it is psychology. The way you present prices, structure plan tiers, frame discounts, and time your offers directly impacts conversion rates and customer perception. This guide explores the four most powerful psychological principles for SaaS pricing — anchoring (the decoy effect), scarcity (limited-time offers), reciprocity (free trials and value-first), and framing (relative vs. absolute pricing) — with production-ready implementation patterns for each. See these principles applied at tanstackship.com/pricing.

Why Pricing Psychology Matters

A 5% increase in pricing optimization can yield a 20-50% increase in profitability (McKinsey). Yet most SaaS founders set prices based on competitor benchmarks or gut feeling, ignoring the psychological mechanisms that determine whether a price feels "fair" or "expensive."

Consider this: Dropbox's $9.99/month plan is not priced at $10.00 because $9.99 triggers a "under $10" mental categorization. That single cent difference can improve conversion by 10-24%.

Psychological Principle	Impact on Conversion	Implementation Cost
Anchoring (decoy effect)	+20-40% on mid-tier	Low (UI change)
Scarcity (time-limited)	+30-60% on offer period	Low (timer logic)
Reciprocity (free trial)	+15-25% on paid conversion	Medium (trial system)
Framing (relative pricing)	+10-30% on annual plans	Low (display logic)
Charm pricing (.99 endings)	+10-24% on conversion	None (cosmetic)

Principle 1: Anchoring — The Decoy Effect

Anchoring is the cognitive bias where humans rely heavily on the first piece of information offered (the "anchor") when making decisions. In SaaS pricing, the anchor is typically your highest-priced plan.

How the Decoy Effect Works

Given three options, people tend to avoid extremes. The middle option becomes the "compromise" choice — but only if the pricing structure is designed correctly:

❌ Ineffective structure:
┌─────────┬─────────┬─────────┐
│  Basic   │  Pro    │  Enterprise │
│  $19/mo  │ $49/mo  │  $149/mo    │
│  ★★★     │ ★★★★★   │  ★★★★★★     │
└─────────┴─────────┴─────────┘
→ Users choose Basic (too many features in Pro, too expensive for Enterprise)

✅ Effective decoy structure:
┌─────────┬─────────┬─────────┬──────────┐
│  Basic   │  Pro     │  Pro+   │ Enterprise │
│  $19/mo  │ $49/mo   │ $59/mo  │  $149/mo   │
│  ★★      │ ★★★★    │ ★★★★   │  ★★★★★★    │
└─────────┴─────────┴─────────┴──────────┘
→ Users compare Pro vs Pro+, see Pro+ is only $10 more for nearly identical
  feature set, but actually choose Pro as the "smart value" option

The decoy (Pro+) makes the Pro plan look like a better deal by comparison.

Implementation: Dynamic Pricing Display

// src/components/pricing/PricingCard.tsx
interface PricingPlan {
  id: string
  name: string
  monthlyPrice: number // In cents
  annualPrice: number  // In cents
  features: string[]
  highlighted?: boolean
  isDecoy?: boolean
}

export function PricingCard({
  plan,
  isAnnual,
}: {
  plan: PricingPlan
  isAnnual: boolean
}) {
  const price = isAnnual ? plan.annualPrice : plan.monthlyPrice
  const monthlyEquivalent = isAnnual ? Math.round(plan.annualPrice / 12) : plan.monthlyPrice

  return (
    <div
      className={`relative p-6 border rounded-xl ${
        plan.highlighted ? "border-blue-500 ring-2 ring-blue-200" : ""
      } ${plan.isDecoy ? "opacity-70" : ""}`}
    >
      {plan.highlighted && (
        <div className="absolute -top-3 left-1/2 -translate-x-1/2 bg-blue-500 text-white px-4 py-1 rounded-full text-sm font-medium">
          Most Popular
        </div>
      )}

      <h3 className="text-xl font-bold mb-2">{plan.name}</h3>

      <div className="mb-4">
        <span className="text-4xl font-bold">${(price / 100).toFixed(0)}</span>
        <span className="text-gray-500">/{isAnnual ? "year" : "month"}</span>
      </div>

      {isAnnual && plan.annualPrice > 0 && (
        <p className="text-sm text-green-600 mb-4">
          ${(monthlyEquivalent / 100).toFixed(2)}/month — Save{" "}
          {Math.round((1 - plan.annualPrice / (plan.monthlyPrice * 12)) * 100)}%
        </p>
      )}

      {plan.isDecoy && (
        <p className="text-xs text-gray-400 mb-2 italic">
          Higher tier with similar features — scroll up for better value
        </p>
      )}

      <ul className="space-y-2 mb-6">
        {plan.features.map((feature, i) => (
          <li key={i} className="flex items-start gap-2 text-sm">
            <span className="text-green-500 mt-0.5">✓</span>
            {feature}
          </li>
        ))}
      </ul>

      <button
        className={`w-full py-3 rounded-lg font-semibold ${
          plan.highlighted
            ? "bg-blue-600 text-white hover:bg-blue-700"
            : "border border-gray-300 hover:bg-gray-50"
        }`}
      >
        {plan.isDecoy ? "View Enterprise" : "Get Started"}
      </button>
    </div>
  )
}

Real-World Anchoring Examples

Company	Anchor	Decoy	Target	Result
The Economist	Web-only ($59)	Print+Web ($125)	Print-only ($125 → $59)	43% chose web-only
Apple Music	Individual ($10.99)	—	Family ($16.99)	Family = 2.7x ARPU
Basecamp	Business ($299/mo)	—	Personal ($32/mo)	Personal feels affordable by comparison

For your SaaS, the principle is: make your highest-tier plan visible first (or most prominent) so it anchors the user's price expectations downward for lower tiers.

Principle 2: Scarcity — The Fear of Missing Out

Scarcity leverages loss aversion — humans feel the pain of losing something 2x more intensely than the pleasure of gaining the same thing (Kahneman & Tversky).

Scarcity Types for SaaS

Type	Example	Effectiveness	Risk
Time-limited	"40% off — ends in 48 hours"	High	Can train users to wait for discounts
Quantity-limited	"Only 50 lifetime licenses left"	High	Must be truthful
Access-limited	"Beta: first 100 users get grandfathered pricing"	Very High	Creates loyal early adopters
Feature-limited	"This price includes all future updates"	Medium	Dilutes future monetization

Implementation: Time-Limited Offer with Server-Side Timer

// src/lib/pricing/offers.ts
import { createServerFn } from "@tanstack/react-start"

// Create a limited-time offer
export const createFlashOffer = createServerFn({ method: "POST" }).handler(
  async ({ planId, discountPercent, durationHours }: {
    planId: string
    discountPercent: number
    durationHours: number
  }) => {
    const offer = {
      id: crypto.randomUUID(),
      planId,
      discountPercent,
      startsAt: Math.floor(Date.now() / 1000),
      expiresAt: Math.floor(Date.now() / 1000) + durationHours * 3600,
      maxRedemptions: 100,
      currentRedemptions: 0,
    }

    await env.DB.prepare(
      `INSERT INTO time_limited_offers (id, plan_id, discount_pct, expires_at, max_redemptions)
       VALUES (?, ?, ?, ?, ?)`
    ).bind(offer.id, offer.planId, discountPercent, offer.expiresAt, offer.maxRedemptions).run()

    return offer
  }
)

// Check if an active offer exists for a user
export const getActiveOffer = createServerFn({ method: "GET" }).handler(
  async ({ planId }: { planId: string }) => {
    const now = Math.floor(Date.now() / 1000)

    const offer = await env.DB.prepare(
      `SELECT * FROM time_limited_offers
       WHERE plan_id = ? AND expires_at > ?
       AND current_redemptions < max_redemptions
       ORDER BY expires_at ASC
       LIMIT 1`
    ).bind(planId, now).first()

    if (!offer) return null

    const timeRemaining = offer.expires_at - now
    return {
      ...offer,
      timeRemaining, // seconds
      timeRemainingFormatted: formatDuration(timeRemaining),
    }
  }
)

// src/components/pricing/CountdownTimer.tsx
export function CountdownTimer({ expiresAt }: { expiresAt: number }) {
  const [timeLeft, setTimeLeft] = useState(expiresAt - Math.floor(Date.now() / 1000))

  useEffect(() => {
    const timer = setInterval(() => {
      setTimeLeft((prev) => Math.max(0, prev - 1))
    }, 1000)
    return () => clearInterval(timer)
  }, [])

  const hours = Math.floor(timeLeft / 3600)
  const minutes = Math.floor((timeLeft % 3600) / 60)
  const seconds = timeLeft % 60

  if (timeLeft <= 0) return null // Offer expired

  return (
    <div className="bg-red-50 border border-red-200 rounded-lg p-4 text-center">
      <p className="text-red-800 font-semibold">Limited Time Offer</p>
      <p className="text-2xl font-mono text-red-600">
        {String(hours).padStart(2, "0")}:
        {String(minutes).padStart(2, "0")}:
        {String(seconds).padStart(2, "0")}
      </p>
      <p className="text-sm text-red-500">Discount expires when timer hits zero</p>
    </div>
  )
}

Ethical Scarcity Guidelines

Never use fake scarcity — users who discover a "limited time" offer that never ends will distrust all your marketing
Use time-limited offers for specific events — product launches, conferences, holidays
Grandfather early users — "locked-in pricing" creates strong retention and positive word-of-mouth

Principle 3: Reciprocity — Give First, Ask Later

Reciprocity is the social norm that when someone gives us something, we feel obligated to give something back. For SaaS, this translates to free trials, freemium tiers, and value-first content.

The Free Trial Timing Debate

Model	Conversion Rate	Avg. Time to Paid	Best For
7-day trial	15-20%	5-8 days	Simple tools, low complexity
14-day trial	20-25%	10-14 days	Mid-complexity SaaS
30-day trial	25-35%	20-28 days	Enterprise, complex products
Freemium (free forever)	2-5%	30-90 days	Network-effect products

Implementation: Trial with Progressive Feature Unlock

// src/lib/pricing/trial.ts
import { createServerFn } from "@tanstack/react-start"

// Determine what features a user has access to
export const getUserAccess = createServerFn({ method: "GET" }).handler(
  async (_, { request }) => {
    const userId = await getUserId(request)
    const user = await env.DB.prepare(
      `SELECT u.created_at, s.status as subscription_status
       FROM users u
       LEFT JOIN subscriptions s ON s.user_id = u.id AND s.status = 'active'
       WHERE u.id = ?`
    ).bind(userId).first() as { created_at: number; subscription_status: string | null }

    const daysSinceSignup = Math.floor(
      (Date.now() / 1000 - user.created_at) / 86400
    )

    if (user.subscription_status === "active") {
      return { tier: "paid", features: ALL_FEATURES }
    }

    if (daysSinceSignup <= 14) {
      return {
        tier: "trial",
        daysLeft: 14 - daysSinceSignup,
        features: TRIAL_FEATURES, // Full access during trial
      }
    }

    // Trial expired — show upgrade prompt with locked features
    return {
      tier: "expired_trial",
      features: RESTRICTED_FEATURES,
      upgradePrompt: {
        message: "Your free trial has ended",
        cta: "Choose a Plan",
        discount: daysSinceSignup <= 30 ? "20% off first 3 months" : null,
      },
    }
  }
)

The Reciprocity Stack

Build a sequence of value-first touches that trigger reciprocity before asking for payment:

Week 1: Free trial with full features (no credit card required)
Week 2: Onboarding emails with templates and best practices
Week 3: Free migration assistance (for data import)
Week 4: "You have been using X hours — here is what you built"
Week 5: Community access (Discord, user group)
Month 2: Pricing page access with "founder's discount"

Each value touch increases the reciprocity pressure — and the likelihood of conversion.

Principle 4: Framing — How You Present the Price

Framing changes how users perceive the same numeric value. Here are the most effective framing techniques for SaaS:

Annual vs. Monthly Framing

// src/components/pricing/PriceDisplay.tsx
interface PriceDisplayProps {
  monthlyCents: number
  annualCents: number
}

export function PriceDisplay({ monthlyCents, annualCents }: PriceDisplayProps) {
  const monthlyPrice = monthlyCents / 100
  const annualPrice = annualCents / 100
  const monthlyEquivalent = annualCents / 12 / 100
  const savingsPercent = Math.round(
    (1 - annualCents / (monthlyCents * 12)) * 100
  )

  return (
    <div>
      {/* Monthly display */}
      <div className="mb-4 p-4 border rounded-lg">
        <div className="text-3xl font-bold">${monthlyPrice.toFixed(0)}<span className="text-base text-gray-500">/month</span></div>
        <p className="text-sm text-gray-500">Billed monthly, cancel anytime</p>
      </div>

      {/* Annual display — framed as savings */}
      <div className="p-4 border-2 border-green-200 rounded-lg bg-green-50">
        <div className="text-3xl font-bold">
          ${monthlyEquivalent.toFixed(0)}
          <span className="text-base text-gray-500">/month</span>
        </div>
        <p className="text-sm text-green-700 font-semibold">
          ${annualPrice.toFixed(0)} billed annually — Save {savingsPercent}%
        </p>
        <p className="text-xs text-green-600 mt-1">
          That is like getting {Math.round(12 * savingsPercent / 100)} months free
        </p>
      </div>
    </div>
  )
}

Per-Day Reframing

For yearly plans, reframe the annual cost into a per-day cost:

Enterprise: $1,788/year
→ "Less than $4.90/day — less than your morning coffee"
→ "For the cost of one lunch per month, you get enterprise-grade infrastructure"

The "Middle Option" Default

Always pre-select the middle tier (or your target tier) on the pricing page:

// Default to the "Pro" plan when loading the pricing page
const [selectedPlan, setSelectedPlan] = useState("pro")

This leverages both anchoring (the high price above it) and the default effect (most users stick with the pre-selected option).

A/B Testing Your Pricing

// src/lib/pricing/ab-testing.ts
import { createServerFn } from "@tanstack/react-start"

export const trackPricingInteraction = createServerFn({ method: "POST" }).handler(
  async ({ plan, action, testGroup }: {
    plan: string
    action: "viewed" | "clicked" | "started_checkout" | "purchased"
    testGroup: "control" | "variant_a" | "variant_b"
  }) => {
    await env.DB.prepare(
      `INSERT INTO pricing_ab_tests
        (plan, action, test_group, timestamp)
       VALUES (?, ?, ?, unixepoch())`
    ).bind(plan, action, testGroup).run()
  }
)

// Query: Compare conversion rates across test groups
export const getPricingTestResults = createServerFn({ method: "GET" }).handler(
  async () => {
    const results = await env.DB.prepare(`
      SELECT
        test_group,
        COUNT(DISTINCT session_id) as sessions,
        SUM(CASE WHEN action = 'purchased' THEN 1 ELSE 0 END) as purchases,
        ROUND(100.0 * SUM(CASE WHEN action = 'purchased' THEN 1 ELSE 0 END) /
          COUNT(DISTINCT session_id), 2) as conversion_rate
      FROM pricing_ab_tests
      GROUP BY test_group
      ORDER BY conversion_rate DESC
    `).all()

    return results
  }
)

What to A/B Test in Pricing

Element	Expected Impact	Test Duration	Sample Size
Plan names (Basic/Pro vs. Starter/Growth)	Low-Med	2 weeks	1,000 visitors
Price points ($49 vs $39)	High	4 weeks	5,000 visitors
Feature placement	Medium	2 weeks	2,000 visitors
Annual discount percentage	High	4 weeks	3,000 visitors
Trial duration (14 vs 30 days)	High	8 weeks	5,000 visitors
Decoy plan presence	Medium	3 weeks	2,000 visitors

Pricing Psychology Mistakes to Avoid

Mistake	Why It Hurts	Fix
Too many plans (5+)	Choice paralysis reduces conversion	Limit to 3-4 plans
Removing the cheapest plan	Loses the anchor that makes mid-tier look good	Keep basic, even if few users buy it
Annual-only pricing	Blocks low-commitment buyers	Offer both, frame annual as savings
Hidden pricing	Destroys trust	Be transparent on pricing page
Discounting without urgency	Trains users to wait for sales	Use limited-time, not always-on discounts
Ignoring competitor framing	Users compare your prices to competitors	Show value comparison (not just price)

Conclusion

Pricing psychology is not about manipulation — it is about presenting your value in a way that helps users make confident decisions. The four principles work together:

Anchoring sets the reference point — make sure your high-tier plan is the first thing users see
Scarcity creates urgency — use time-limited offers for launches and events, not as a permanent tactic
Reciprocity builds goodwill — give genuine value before asking for money
Framing changes perception — annual pricing reframed as "per day" feels dramatically cheaper

Test one change at a time, measure everything, and remember: the goal is not to trick users into paying more — it is to price your product in a way that reflects its true value while making it easy for the right customers to say yes.

Related Resources

SaaS Monitoring and Observability: Logs, Metrics, and Traces

sweet — Tue, 30 Jun 2026 00:49:00 +0000

Observability is the foundation of operational confidence in a SaaS application. Without it, you are debugging in the dark. This guide covers the three pillars of observability — logs, metrics, and traces — implemented for SaaS applications on Cloudflare Workers and TanStack Start, with practical patterns used at tanstackship.com for production monitoring, alerting, and root cause analysis.

The Three Pillars of Observability

Pillar	What It Answers	Storage	Retention	Cost
Logs	"What happened?"	Workers Analytics Engine	7-30 days	Low
Metrics	"What is the trend?"	Analytics Engine + Grafana	3-12 months	Medium
Traces	"Why did it happen?"	Workers Trace (Tail Worker)	1-7 days	Low (sampled)

Logging: Structured Logging on the Edge

Log Format

// src/lib/logger.ts
type LogLevel = "debug" | "info" | "warn" | "error"

interface LogEntry {
  timestamp: string
  level: LogLevel
  message: string
  requestId: string
  userId?: string
  duration?: number
  error?: string
  metadata?: Record<string, unknown>
}

function createLogger(request: Request) {
  const requestId = request.headers.get("cf-ray") ?? crypto.randomUUID()

  return {
    info: (msg: string, meta?: Record<string, unknown>) =>
      log({ level: "info", message: msg, requestId, metadata: meta }),
    warn: (msg: string, meta?: Record<string, unknown>) =>
      log({ level: "warn", message: msg, requestId, metadata: meta }),
    error: (msg: string, error?: Error, meta?: Record<string, unknown>) =>
      log({
        level: "error",
        message: msg,
        requestId,
        error: error?.message,
        stack: error?.stack,
        metadata: meta,
      }),
    getRequestId: () => requestId,
  }
}

Sending Logs to Analytics Engine

// src/lib/logger.ts — writing to Workers Analytics Engine
function log(entry: LogEntry) {
  // Write to Analytics Engine for queryable storage
  context.env.ANALYTICS.writeDataPoint({
    blobs: [
      entry.level,
      entry.message,
      entry.requestId,
      entry.userId ?? "",
      entry.error ?? "",
      JSON.stringify(entry.metadata ?? {}),
    ],
    doubles: [entry.duration ?? 0],
    indexes: [entry.requestId],
  })

  // Also output to Workers console for wrangler tail
  console.log(JSON.stringify(entry))
}

Metrics: What to Measure

SaaS Metrics Taxonomy

Category	Metrics	How to Measure
Performance	Request latency (p50/p95/p99), response size, cache hit rate	Analytics Engine
Business	Signups, MRR, churn rate, conversion rate	Database queries
Infrastructure	Worker CPU time, memory, subrequest count	Workers Runtime API
User experience	LCP, CLS, INP, TTFB	Web Vitals API + Analytics

Collecting Performance Metrics

// server/middleware/metrics.ts
export const metricsMiddleware = createServerFn({ method: "GET" }).handler(
  async ({ request, context }) => {
    const startTime = Date.now()

    // After the request completes, record metrics
    context.waitUntil(
      context.env.ANALYTICS.writeDataPoint({
        blobs: [
          request.url,
          request.method,
          String(context.response?.status ?? 500),
        ],
        doubles: [
          Date.now() - startTime, // duration
          request.cf?.colo ?? 0, // edge location
        ],
        indexes: [request.url.split("?")[0]], // path
      })
    )
  }
)

Querying Metrics

// Query Analytics Engine for dashboard data
export const getApiLatency = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const result = await context.env.ANALYTICS.query({
      sql: `
        SELECT
          blob3 as path,
          quantile(0.50)(double1) as p50,
          quantile(0.95)(double1) as p95,
          quantile(0.99)(double1) as p99,
          count() as requests
        FROM analytics_engine_table
        WHERE timestamp > now() - INTERVAL '1' DAY
        GROUP BY blob3
        ORDER BY p99 DESC
        LIMIT 20
      `,
    })

    return result.rows
  }
)

Tracing: Distributed Request Tracing

Setting Up a Tail Worker

// tail-worker.ts — deployed as a separate Worker
export default {
  async tail(events: TraceEvent[]) {
    for (const event of events) {
      if (event.duration && event.event.request) {
        await ANALYTICS.writeDataPoint({
          blobs: [
            event.event.request.method,
            event.event.request.url,
            String(event.exceptions?.[0]?.message ?? ""),
          ],
          doubles: [
            event.duration ?? 0,
            event.event.request.cf?.botManagement?.score ?? 0,
          ],
          indexes: [event.event.request.url.split("?")[0]],
        })

        // Alert on exceptions
        if (event.exceptions?.length > 0 || event.crons?.length > 0) {
          await sendIncidentAlert(event)
        }
      }
    }
  },
}

Injecting Trace Context

// Pass trace context from server function to downstream services
export const handleWebhook = createServerFn({ method: "POST" }).handler(
  async ({ request, context }) => {
    const traceId = crypto.randomUUID()

    // Pass trace ID to downstream calls
    await fetch("https://api.stripe.com/v1/events", {
      headers: {
        "X-Trace-Id": traceId,
      },
    })

    // Log with trace context
    context.logger.info("Webhook received", { traceId, eventType: event.type })
  }
)

Alerting: When to Wake Someone Up

Alert Severity Levels

Level	Response Time	Example
Critical	15 minutes	p99 latency > 5s for 5 minutes
High	1 hour	Error rate > 1% for 10 minutes
Medium	24 hours	Disk usage > 80%
Low	7 days	Deprecated API calls detected

Alert Configuration

// server/monitoring/alerts.ts
import { createServerFn } from "@tanstack/react-start"

export const checkAlerts = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const alerts = []

    // 1. Check error rate
    const errorRate = await context.env.ANALYTICS.query({
      sql: `
        SELECT count() as total,
               countIf(blob0 = 'error') as errors
        FROM analytics_engine_table
        WHERE timestamp > now() - INTERVAL '5' MINUTE
      `,
    })

    const rate = Number(errorRate.rows[0]?.errors ?? 0) /
                 Math.max(Number(errorRate.rows[0]?.total ?? 1), 1)

    if (rate > 0.01) {
      alerts.push({
        severity: "high",
        message: `Error rate ${(rate * 100).toFixed(1)}% > 1%`,
      })
    }

    // 2. Check latency
    const latency = await context.env.ANALYTICS.query({
      sql: `
        SELECT quantile(0.99)(double1) as p99
        FROM analytics_engine_table
        WHERE timestamp > now() - INTERVAL '5' MINUTE
      `,
    })

    const p99 = Number(latency.rows[0]?.p99 ?? 0)
    if (p99 > 5000) {
      alerts.push({
        severity: "critical",
        message: `p99 latency ${p99}ms > 5000ms`,
      })
    }

    return alerts
  }
)

Dashboard: Visualizing Your Observability Data

The ideal SaaS observability dashboard has three views:

Operational View (Real-Time)

┌──────────────┬──────────────┬──────────────┬──────────────┐
│ Request Rate │ Error Rate   │ p50 Latency  │ p99 Latency  │
│   1,234/min  │   0.02%      │    45ms      │    210ms     │
├──────────────┼──────────────┼──────────────┼──────────────┤
│ Active Users │ Signups (24h)│ Churn (30d)  │ MRR          │
│   847        │   23         │    3.2%      │  $12,450     │
└──────────────┴──────────────┴──────────────┴──────────────┘

Business View (Weekly)

Cohort Retention Table
Signup Funnel (Visit → Signup → Subscribe → Active)
Feature Adoption Heatmap
Top User Actions

Debug View (On-Demand)

Request Trace Explorer
Error Log Stream
Worker CPU Profile
Database Query Performance

Automating Incident Response

// server/monitoring/incident.ts
export const handleIncident = createServerFn({ method: "POST" }).handler(
  async ({ data }: { data: { severity: string; message: string } }) => {
    // 1. Log the incident
    await logIncident(data)

    // 2. Notify (only for high+ criticality)
    if (["high", "critical"].includes(data.severity)) {
      await sendSlackNotification(
        `[${data.severity.toUpperCase()}] ${data.message}`
      )
      await sendEmail({
        to: "ops@tanstackship.com",
        subject: `[${data.severity}] ${data.message}`,
      })
    }

    // 3. Auto-remediate where possible
    if (data.message.includes("rate limit")) {
      // Scale up rate limit window
      console.log("Auto-remediation: rate limit exceeded")
    }
  }
)

Observability Budget

Allocate your observability resources wisely:

Component	% of Observability Budget	Why
Request logging (sampled)	20%	Core operational data
Error/exception logging	30%	Highest debugging value
Business metrics	25%	Revenue and growth
Performance metrics	15%	User experience
Distributed traces	10%	Debugging complex issues

Production Observability Checklist

[ ] All requests produce structured JSON logs
[ ] Logs include request ID, user ID, and duration
[ ] Error logs include stack traces
[ ] All critical business events are tracked as metrics
[ ] Worker performance metrics collected (CPU, memory, subrequests)
[ ] Alerts configured for p99 latency > 5s and error rate > 1%
[ ] Tail worker captures trace data for sampled requests
[ ] Dashboard covers operational, business, and debug views
[ ] Logs have automated retention and archival policy
[ ] Access to logs is audited and role-restricted

Conclusion

Observability is not optional for a production SaaS application. The three pillars — logs, metrics, and traces — each serve a different purpose, and a mature observability practice needs all three.

For TanStack Start on Cloudflare Workers, the native observability tooling (Workers Analytics Engine, Tail Workers, Trace Workers) provides a solid foundation without requiring third-party services. You can collect, query, and alert on operational data entirely within the Cloudflare ecosystem.

The key is to start simple: structured logs first, then metrics for the most critical business and performance indicators, then traces for debugging complex issues. Add alerting only when you have enough data to set meaningful thresholds.

For a production SaaS with built-in observability infrastructure, see tanstackship.com.

Related Resources

SaaS Growth Framework: How to Get Your First 100 Paying Customers Without Burning Cash

sweet — Mon, 29 Jun 2026 08:48:59 +0000

The first 100 paying customers determine whether your SaaS survives. This framework breaks down the acquisition process into four stages — Define, Reach, Convert, Retain — with specific tactics for each. You will learn how to build a customer acquisition pipeline using content marketing, community engagement, and product-led growth — all without paid ads. Includes a complete UTM tracking setup, landing page conversion optimization patterns, and a referral system architecture that turns customers into your sales force. See the complete growth toolkit in action at tanstackship.com.

The First 100 Problem

Every SaaS founder faces the same chicken-and-egg problem: you need customers to validate your product, but you need a validated product to get customers. The statistics are sobering:

Metric	Value	Source
SaaS startups that fail before 100 customers	~60%	CB Insights
Average time to first 100 customers (bootstrapped)	6-12 months	Baremetrics
	Cost per acquisition (first 100, bootstrapped)	$50-500
Primary channel for first 100 customers	Founder-led sales & content	SaaS Labs
Startups that use paid ads before product-market fit	70% burn out	Lenny Rachitsky

The framework that follows assumes zero marketing budget. Every tactic here costs time, not money — because until you have 100 paying customers, your only scalable resource is your own effort.

Stage 1: Define — Who Are Your First 100?

Most founders cast too wide a net. The first 100 customers share specific characteristics:

Ideal Customer Profile (ICP) Worksheet

// src/lib/marketing/icp.ts
interface ICP {
  role: string
  companySize: string
  techStack: string[]
  painPoint: string
  budget: string
  whereTheyHangOut: string[]
}

// Example ICP for TanStack Ship:
const icpTanStackShip: ICP = {
  role: "Indie founder / Full-stack developer",
  companySize: "1-10 employees",
  techStack: ["React", "TypeScript", "Cloudflare", "Node.js"],
  painPoint: "Building SaaS boilerplate from scratch takes 4-8 weeks",
  budget: "$200-500 for tools per month",
  whereTheyHangOut: [
    "r/reactjs", "r/webdev", "r/SaaS",
    "Hacker News", "X/Twitter #buildinpublic",
    "Indie Hackers", "React Discord",
  ],
}

Exercise: Write down the names of 10 real people who would pay for your product. If you cannot name 10, your ICP is not specific enough. These people become your first outreach targets.

The 100-Person Pipeline

Target 500 → Reach 200 → Demo 50 → Paying 100
(Outreach)  (Respond)   (Convert)  (Activated)

Each stage requires a specific conversion tactic:

Pipeline Stage	Target	Conversion Tactic	Tool
Outreach	500 identified prospects	Personalized cold email/DM	Clay + Apollo
Response	200 replies	Value-first messaging	Your inbox
Demo	50 demo calls	Problem-aware pitch	Calendly
Paying	100 customers	Limited-time founder offer	Stripe

Stage 2: Reach — Getting in Front of the Right People

Tactic 1: Community-First Content (Highest ROI for Technical SaaS)

Instead of broadcasting "buy my product," provide genuine value in communities your ICP already inhabits:

// src/lib/marketing/content-strategy.ts
const contentPlan = [
  {
    platform: "r/reactjs",
    format: "Tutorial",
    topic: "How to implement file-based routing with TanStack Router",
    callToAction: "Mention TanStack Ship as a complete starter",
    frequency: "1x per week",
  },
  {
    platform: "Hacker News",
    format: "Show HN",
    topic: "Show HN: I built a SaaS starter with TanStack Start + Cloudflare Workers",
    callToAction: "Direct link to landing page",
    frequency: "At launch + major updates",
  },
  {
    platform: "X/Twitter",
    format: "Build in public",
    topic: "Daily progress on SaaS features, revenue, users",
    callToAction: "Link in bio + profile",
    frequency: "Daily",
  },
  {
    platform: "Indie Hackers",
    format: "Interview / Milestone",
    topic: "How I reached $1k MRR with TanStack Ship",
    callToAction: "Link to product",
    frequency: "Monthly",
  },
]

Tactic 2: Founder-Led Cold Outreach

Personalized cold emails still work when done correctly:

// Template: High-value cold email
const coldEmailTemplate = `Subject: Quick question about ${prospect.tool}

Hey ${prospect.firstName},

I noticed you built ${prospect.project} with ${prospect.techStack}.

I am working on [Your Product] — a [one-line value prop]. Since you are already using ${sharedInterest}, I would love your feedback.

No pitch, just 10 minutes to show you what I am building and get your honest thoughts.

Are you open to a quick call this week?

Best,
${yourName}`

Metrics from 500 cold emails (industry benchmarks):

Open rate: 45-60%
Reply rate: 10-20%
Demo booked: 3-5%
Customer converted: 1-2%

Tactic 3: Content Marketing with SEO Moats

Create content that ranks for long-tail keywords your ICP searches for. For a TanStack-based SaaS, those are:

Keyword	Search Volume	Competition	Content Type
"TanStack Start tutorial"	2.4K/month	Low	Tutorial
"Cloudflare Workers SSR"	1.8K/month	Low-Med	Guide
"how to build a SaaS solo"	3.2K/month	Medium	Framework post
"SaaS boilerplate comparison"	1.2K/month	Medium	Comparison

Stage 3: Convert — Turning Interest into Revenue

Landing Page Conversion Architecture

// src/components/marketing/HeroSection.tsx
export function HeroSection() {
  return (
    <section className="max-w-4xl mx-auto text-center py-20">
      {/* 1. Problem-aware headline */}
      <h1 className="text-5xl font-bold mb-4">
        Ship Your SaaS in Weeks, Not Months
      </h1>

      {/* 2. Specific value proposition */}
      <p className="text-xl text-gray-600 mb-8">
        TanStack Ship gives you a production-ready SaaS starter with
        authentication, billing, UTM tracking, and email campaigns —
        so you can focus on your unique product logic.
      </p>

      {/* 3. Social proof */}
      <div className="flex justify-center gap-8 mb-12">
        <div className="text-center">
          <div className="text-3xl font-bold">50+</div>
          <div className="text-sm text-gray-500">Early adopters</div>
        </div>
        <div className="text-center">
          <div className="text-3xl font-bold">4+</div>
          <div className="text-sm text-gray-500">Weeks saved</div>
        </div>
        <div className="text-center">
          <div className="text-3xl font-bold">100%</div>
          <div className="text-sm text-gray-500">TypeScript</div>
        </div>
      </div>

      {/* 4. Primary CTA */}
      <div className="flex justify-center gap-4">
        <Link
          to="/pricing"
          className="bg-blue-600 text-white px-8 py-3 rounded-lg text-lg font-semibold hover:bg-blue-700"
        >
          Start Building →
        </Link>
        <Link
          to="/blog/tanstack-start-end-to-end-tutorial"
          className="border border-gray-300 px-8 py-3 rounded-lg text-lg font-semibold hover:bg-gray-50"
        >
          Read the Tutorial
        </Link>
      </div>
    </section>
  )
}

Conversion-Optimized Pricing Page

// UTM-aware pricing that tracks where customers come from
export const trackPricingView = createServerFn({ method: "POST" }).handler(
  async ({ plan, utmSource }: { plan: string; utmSource?: string }) => {
    await env.DB.prepare(
      `INSERT INTO conversion_events
        (event_type, plan, utm_source, page_url, timestamp)
       VALUES ('pricing_view', ?, ?, ?, unixepoch())`
    ).bind(plan, utmSource ?? "direct", getCurrentUrl())
      .run()
  }
)

Founder Discount Strategy

For the first 100 customers, use a graduated discount that creates urgency without devaluing your product:

Customers Acquired	Discount	Rationale
1-25	40% off lifetime	Maximum incentive for early feedback
26-50	30% off annual	Still generous, building momentum
51-75	20% off annual	Growing validation, less discount needed
76-100	10% off annual	Almost at full price
100+	Full price	Market validation established

Stage 4: Retain — Keeping and Expanding the First 100

Churn in the first 100 customers is fatal — if 20% churn, you need 20 new customers just to stay flat. Focus on activation, not just acquisition.

Activation Metrics Dashboard

-- Track activation events per user
CREATE TABLE activation_events (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  event_type TEXT NOT NULL CHECK (
    event_type IN (
      'signed_up', 'completed_onboarding',
      'created_first_project', 'invited_team_member',
      'connected_payment', 'deployed_to_production'
    )
  ),
  occurred_at INTEGER NOT NULL DEFAULT (unixepoch()),
  FOREIGN KEY (user_id) REFERENCES users(id)
);

-- Activation health view
CREATE VIEW user_activation_status AS
SELECT
  u.id,
  u.email,
  u.created_at,
  MAX(CASE WHEN ae.event_type = 'completed_onboarding' THEN 1 ELSE 0 END) as onboarded,
  MAX(CASE WHEN ae.event_type = 'created_first_project' THEN 1 ELSE 0 END) as created_project,
  MAX(CASE WHEN ae.event_type = 'deployed_to_production' THEN 1 ELSE 0 END) as deployed,
  CASE
    WHEN MAX(ae.event_type = 'deployed_to_production') THEN 'Fully Activated'
    WHEN MAX(ae.event_type = 'created_first_project') THEN 'Exploring'
    WHEN MAX(ae.event_type = 'completed_onboarding') THEN 'Onboarded'
    ELSE 'Stuck'
  END as activation_stage
FROM users u
LEFT JOIN activation_events ae ON ae.user_id = u.id
GROUP BY u.id;

Weekly Retention Email Sequence

// src/lib/email/retention.ts
const retentionSequence = [
  {
    day: 1,
    subject: "Welcome to TanStack Ship — Your First Project",
    content: "Step-by-step guide to deploying your first app",
    cta: "Deploy Now",
  },
  {
    day: 3,
    subject: "Tip: Authentication is Already Set Up",
    content: "How to customize the auth flow for your brand",
    cta: "View Auth Docs",
  },
  {
    day: 7,
    subject: "35% of Users Miss This Feature (UTM Tracking)",
    content: "How to track every customer acquisition channel",
    cta: "Set Up UTM",
  },
  {
    day: 14,
    subject: "You Have Been Using TanStack Ship for 2 Weeks",
    content: "Here is what you have built so far + what you might have missed",
    cta: "See Progress",
  },
  {
    day: 30,
    subject: "One Month In — How Can We Help?",
    content: "Personal check-in from the founder",
    cta: "Book a Call",
  },
]

The NPS + Churn Prevention Loop

// Score-based intervention
export async function handleNpsResponse(
  userId: string,
  score: number,
  feedback: string
) {
  if (score >= 9) {
    // Promoter → Ask for referral
    await triggerReferralPrompt(userId)
  } else if (score <= 6) {
    // Detractor → Immediate founder outreach
    await notifyFounder(userId, feedback)
    await scheduleRecoveryCall(userId)
  }

  await env.DB.prepare(
    `INSERT INTO nps_responses (user_id, score, feedback, responded_at)
     VALUES (?, ?, ?, unixepoch())`
  ).bind(userId, score, feedback).run()
}

Tracking Everything with UTM Attribution

You cannot optimize what you do not measure. Set up UTM tracking from day one:

// src/lib/marketing/utm.ts
import { useSearchParams } from "@tanstack/react-router"

export function useUtmCapture() {
  const [searchParams] = useSearchParams()

  const utmData = {
    source: searchParams.get("utm_source") ?? "direct",
    medium: searchParams.get("utm_medium") ?? "none",
    campaign: searchParams.get("utm_campaign") ?? "none",
    term: searchParams.get("utm_term") ?? "none",
    content: searchParams.get("utm_content") ?? "none",
  }

  // Persist UTM parameters across the session
  useEffect(() => {
    if (utmData.source !== "direct") {
      localStorage.setItem("utm_data", JSON.stringify(utmData))
      trackUtmVisit(utmData) // Server-side tracking
    }
  }, [searchParams])

  return utmData
}

Attribution table showing which channels drive your first 100 customers:

Channel	% of First 100	Cost	Conversion Rate	Time to First Paid
Content marketing (blog)	30%	Time only	2-5%	14-30 days
Community (Reddit/HN)	25%	Time only	3-8%	7-21 days
Founder cold outreach	20%	Time only	1-3%	3-14 days
Product-led (viral/referral)	15%	Built-in	5-15%	1-7 days
Partnerships	10%	Revenue share	10-25%	30-90 days

First 100 Customer Dashboard

Build a simple dashboard to track your progress in real time:

CREATE VIEW first_100_dashboard AS
SELECT
  COUNT(DISTINCT u.id) as total_users,
  COUNT(DISTINCT CASE WHEN s.status = 'active' THEN u.id END) as paying_customers,
  COUNT(DISTINCT CASE WHEN ae.event_type = 'deployed_to_production' THEN u.id END) as activated_users,
  ROUND(AVG(CASE WHEN s.status = 'active' THEN s.mrr END), 2) as avg_mrr,
  ROUND(SUM(CASE WHEN s.status = 'active' THEN s.mrr END), 2) as total_mrr,
  ROUND(
    100.0 * COUNT(DISTINCT CASE WHEN s.status = 'active' THEN u.id END) /
    NULLIF(COUNT(DISTINCT u.id), 0), 1
  ) as conversion_rate,
  ROUND(
    100.0 - 100.0 * COUNT(DISTINCT CASE WHEN s.status = 'canceled' THEN u.id END) /
    NULLIF(COUNT(DISTINCT CASE WHEN s.status IN ('active', 'canceled') THEN u.id END), 0), 1
  ) as retention_rate
FROM users u
LEFT JOIN subscriptions s ON s.user_id = u.id
LEFT JOIN activation_events ae ON ae.user_id = u.id;

Execution Timeline: 90 Days to 100 Customers

Week	Focus	Key Activities	Target Customers
1-2	Define & Build	Finalize ICP, prepare outreach list of 500, publish 2 SEO articles	0
3-4	Reach (Cold)	Send 250 personalized cold emails, post in 5 communities	5-10
5-6	Reach (Content)	Publish 2 more articles, 15 social posts, 5 forum answers	15-25
7-8	Convert	20-30 demos, launch founder discount, optimize pricing page	30-45
9-10	Referral	Activate referral system, ask promoters for introductions	50-70
11-12	Scale	Double down on best channels, iterate based on feedback	80-100

Conclusion

Getting your first 100 paying customers is not about a silver bullet — it is about systematic execution across the four stages of the growth framework:

Define: Know exactly who your first 100 customers are before you build anything
Reach: Use community content, personalized outreach, and SEO to get in front of them without paid ads
Convert: Build a conversion-optimized landing page, use founder discounts strategically, and track every touchpoint with UTM
Retain: Measure activation (not just signups), automate retention emails, and turn promoters into your referral engine

The startups that succeed are not the ones with the best product or the most funding. They are the ones that talk to their users every day, iterate obsessively, and track every metric from day one.

Your first 100 customers are out there. They are searching for a solution to the exact problem you are solving. Go find them.

Related Resources

SaaS Globalization Strategy: Technical Preparation for Chinese, European, and US Markets

sweet — Wed, 24 Jun 2026 00:45:00 +0000

Expanding a SaaS product into global markets requires more than translation — it demands infrastructure changes (edge deployment for low latency), compliance adaptation (GDPR, PIPL, CCPA), payment localization (Alipay, SEPA, Stripe), and cultural UX adjustments. This guide breaks down the technical and business preparation needed for the three largest SaaS markets: the US, Europe, and China. Each section includes actionable code examples, configuration snippets, and deployment patterns you can implement immediately. See the architecture in action at tanstackship.com, a production SaaS shipping globally on Cloudflare Workers.

Why Globalization Must Be Built, Not Bolted On

The biggest mistake SaaS founders make with globalization is treating it as a phase-two feature. Retrofitting i18n, multi-currency pricing, and regional compliance onto a monolithic codebase typically costs 3-5x more than building it in from the start — and often requires a full rewrite of the database schema, routing layer, and deployment pipeline.

The three largest SaaS markets have fundamentally different requirements:

Requirement	US Market	European Market	Chinese Market
Language	English	Multi (DE, FR, ES, etc.)	Chinese (Simplified)
Data regulation	CCPA/State laws	GDPR (strictest)	PIPL + CSL
Payment methods	Credit cards, Stripe	SEPA, PayPal, credit cards	Alipay, WeChat Pay, UnionPay
Infrastructure	AWS/US-East	GDPR-compliant hosting	ICP license, China-hosted
Authentication	Google, GitHub	EU-specific (eIDAS)	WeChat, Alipay, phone SMS
Pricing display	$ (tax excl.)	€ (VAT incl.)	¥ (tax incl.)
Content delivery	Global CDN	Edge (300ms latency target)	China CDN (ICP + DDoS shield)
Social login	Google, Apple, GitHub	Google, Apple, LinkedIn	WeChat, Alipay, phone OTP
Email deliverability	SendGrid, AWS SES	SendGrid (DPA signed)	QQ Mail, Alibaba Direct Mail

Market 1: European Market Preparation

GDPR Compliance Checklist

GDPR applies to any SaaS processing data of EU residents — regardless of where your company is incorporated. Here is the technical implementation:

// src/lib/gdpr.ts
// GDPR-compliant data handling utilities

// 1. Explicit consent tracking
interface ConsentRecord {
  userId: string
  consentType: "analytics" | "marketing" | "functional" | "third_party"
  granted: boolean
  timestamp: number
  ipAddress: string // Anonymized
}

export async function recordConsent(
  userId: string,
  consentType: ConsentRecord["consentType"],
  granted: boolean
) {
  await env.DB.prepare(
    `INSERT INTO consent_records (user_id, consent_type, granted, timestamp, ip_address)
     VALUES (?, ?, ?, unixepoch(), ?)`
  ).bind(
    userId,
    consentType,
    granted ? 1 : 0,
    anonymizeIp(getClientIp())
  ).run()
}

// 2. Data portability export
export const exportUserData = createServerFn({ method: "GET" }).handler(
  async (_, { request }) => {
    const userId = await getUserId(request)

    const [profile, subscriptions, invoices, events] = await Promise.all([
      env.DB.prepare("SELECT * FROM users WHERE id = ?").bind(userId).first(),
      env.DB.prepare("SELECT * FROM subscriptions WHERE user_id = ?").bind(userId).all(),
      env.DB.prepare("SELECT * FROM invoices WHERE user_id = ?").bind(userId).all(),
      env.DB.prepare("SELECT * FROM analytics_events WHERE user_id = ?").bind(userId).all(),
    ])

    return Response.json({
      exportedAt: new Date().toISOString(),
      data: { profile, subscriptions, invoices, events },
    })
  }
)

// 3. Right to erasure (GDPR Article 17)
export const deleteUserData = createServerFn({ method: "POST" }).handler(
  async (_, { request }) => {
    const userId = await getUserId(request)

    // Anonymize personal data (keep transactional records for legal retention)
    await env.DB.batch([
      env.DB.prepare(`UPDATE users SET
        email = 'deleted-' || id || '@redacted.com',
        name = 'Deleted User',
        avatar_url = NULL,
        deleted_at = unixepoch()
        WHERE id = ?`).bind(userId),
      env.DB.prepare("DELETE FROM analytics_events WHERE user_id = ?").bind(userId),
      env.DB.prepare("DELETE FROM session_tokens WHERE user_id = ?").bind(userId),
    ])

    return { success: true }
  }
)

EU Data Residency

GDPR requires that EU user data stays within the EU or in countries with adequate protection. With Cloudflare Workers, use data localization:

# wrangler.jsonc
{
  "name": "tanstack-ship",
  "compatibility_date": "2026-06-01",
  "workers_dev": false,
  "routes": [
    { "pattern": "tanstackship.com", "zone_id": "YOUR_ZONE_ID" },
    { "pattern": "eu.tanstackship.com", "zone_id": "YOUR_ZONE_ID", "custom_domain": true }
  ],
  "d1_databases": [
    { "binding": "DB", "database_id": "GLOBAL_DB", "database_name": "tanstack-ship" },
    { "binding": "EU_DB", "database_id": "EU_DB", "database_name": "tanstack-ship-eu" }
  ]
}

// Route EU users to EU D1 instance
async function getDb(request: Request) {
  const country = request.cf?.country
  if (country && EU_COUNTRIES.has(country)) {
    return env.EU_DB // GDPR-compliant D1 instance
  }
  return env.DB
}

EU Payment: SEPA Direct Debit

// With Stripe, SEPA is handled via Payment Methods
const paymentIntent = await stripe.paymentIntents.create({
  amount: 2999, // €29.99
  currency: "eur",
  payment_method_types: ["sepa_debit", "card"],
  customer: customerId,
})

Key EU-specific pricing considerations:

Display prices including VAT (unlike the US)
Register for VAT MOSS to handle cross-border EU sales
Issue VAT-compliant invoices (required by law for B2B)
SEPA transfers can take 1-3 business days — do not grant access until payment clears

Market 2: Chinese Market Preparation

Entering China is the most technically demanding market expansion. Here is what you need:

ICP License (Required for Any Hosted Service)

Any website or app hosted on servers in mainland China or using a Chinese CDN must have an ICP (Internet Content Provider) license. The process takes 4-8 weeks and requires:

Registered Chinese company (WFOE or joint venture) or partnership with a Chinese ICP-licensed entity
ICP filing submission through your cloud provider (Alibaba Cloud, Tencent Cloud, AWS China)
Domain name already ICP-filed

Without an ICP license, your site will be blocked by the Great Firewall of China (GFW).

Infrastructure: Bypassing the Great Firewall

// src/lib/geo-routing.ts
// Route Chinese users to China-hosted instances

const CHINA_REGIONS = new Set(["CN", "HK", "MO"])

export async function getRegionalEndpoint(request: Request): Promise<string> {
  const country = request.cf?.country

  if (CHINA_REGIONS.has(country ?? "")) {
    // Route to China-hosted instance via Cloudflare China Network
    return "https://tanstack-ship.cn"
  }

  // Global instance
  return "https://tanstackship.com"
}

Cloudflare China Network provides a GFW-compliant CDN layer without requiring your own Chinese servers. All major Chinese cloud providers also offer GPU/CPU instances:

Alibaba Cloud (aliyun.com) — largest market share
Tencent Cloud — second largest, WeChat integration
AWS China (Beijing/Ningxia) — requires separate account

Chinese Payment Integration

// src/lib/payment/china.ts
// Alipay integration via Stripe or direct API

// Option 1: Stripe (simplest, higher fees)
const paymentIntent = await stripe.paymentIntents.create({
  amount: 19900, // ¥199.00
  currency: "cny",
  payment_method_types: ["alipay", "card"],
  payment_method_options: {
    alipay: {},
  },
})

// Option 2: Direct Alipay API (lower fees, more setup)
import AlipaySdk from "alipay-sdk"

const alipaySdk = new AlipaySdk({
  appId: process.env.ALIPAY_APP_ID,
  privateKey: process.env.ALIPAY_PRIVATE_KEY,
})

const result = await alipaySdk.exec("alipay.trade.create", {
  bizContent: {
    out_trade_no: orderId,
    total_amount: "199.00",
    subject: "TanStack Ship - Pro Plan",
    product_code: "FAST_INSTANT_TRADE_PAY",
  },
})

Chinese Social Login

// src/lib/auth/china.ts
// WeChat OAuth

// Step 1: Redirect user to WeChat authorization
export function getWeChatAuthUrl(redirectUri: string): string {
  const params = new URLSearchParams({
    appid: process.env.WECHAT_APP_ID,
    redirect_uri: redirectUri,
    response_type: "code",
    scope: "snsapi_login",
    state: crypto.randomUUID(),
  })
  return `https://open.weixin.qq.com/connect/qrconnect?${params}`
}

// Step 2: Exchange code for access token
export async function getWeChatToken(code: string) {
  const response = await fetch(
    `https://api.weixin.qq.com/sns/oauth2/access_token?` +
    new URLSearchParams({
      appid: process.env.WECHAT_APP_ID,
      secret: process.env.WECHAT_APP_SECRET,
      code,
      grant_type: "authorization_code",
    })
  )
  return response.json() as Promise<{
    access_token: string
    openid: string
    unionid: string
  }>
}

Chinese Content Delivery Considerations

Censored keywords: Your content will be scanned. Common SaaS-blocked terms include sensitive political topics, VPN references, and cryptocurrency mentions
WeChat ecosystem: WeChat Mini Programs, WeChat Pay, and WeChat Official Accounts are essential for B2C SaaS
Email deliverability: QQ Mail and 163.com are the dominant email providers — ensure your SPF, DKIM, and DMARC are configured for Chinese domains
Domain blocking: Some domains are blocked without clear reason. Register a .cn domain as backup

Market 3: US Market Preparation

The US market is the most straightforward but still requires specific attention:

Tax Compliance: Sales Tax by State

// src/lib/tax/us-sales-tax.ts
// Simplified sales tax calculation (use a service like TaxJar for production)

const STATE_TAX_RATES: Record<string, number> = {
  "CA": 0.0725,  // California base rate
  "NY": 0.04,    // New York state (county/city adds more)
  "TX": 0.0625,  // Texas
  "WA": 0.065,   // Washington
  // ... 45+ more states
}

export function calculateSalesTax(
  amount: number,
  state: string
): { taxRate: number; taxAmount: number; total: number } {
  const taxRate = STATE_TAX_RATES[state.toUpperCase()] ?? 0
  const taxAmount = Math.round(amount * taxRate * 100) / 100
  return { taxRate, taxAmount, total: amount + taxAmount }
}

Key considerations:

Economic nexus: If you sell >$100K or 200+ transactions in a state, you must collect sales tax
Use a service like TaxJar, Stripe Tax, or Anrok for automated calculation
Display prices excluding tax (unlike Europe)

US Privacy Compliance (CCPA)

// src/lib/ccpa.ts
// CCPA opt-out mechanism
export async function handleCcpOptOut(userId: string) {
  await env.DB.prepare(
    `INSERT INTO privacy_opt_outs (user_id, regulation, opted_out_at)
     VALUES (?, 'CCPA', unixepoch())`
  ).bind(userId).run()
}

// Do not sell my personal information endpoint
export const optOutOfSale = createServerFn({ method: "POST" }).handler(
  async (_, { request }) => {
    const userId = await getUserId(request)
    await handleCcpOptOut(userId)
    return { success: true }
  }
)

Architectural Pattern: Regional Deployment with Edge Workers

For SaaS products targeting all three markets simultaneously, use a regional deployment architecture:

┌─────────────────────────────────────────────────┐
│                  Cloudflare                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────┐ │
│  │  US Worker   │  │  EU Worker   │  │ CN Edge  │ │
│  │  us-east     │  │  eu-west     │  │ (CF CN)  │ │
│  └──────┬───────┘  └──────┬───────┘  └────┬─────┘ │
│         │                 │               │        │
│  ┌──────▼───────┐  ┌──────▼───────┐  ┌────▼─────┐ │
│  │  US D1 DB    │  │  EU D1 DB    │  │ CN D1 DB │ │
│  │  (Virginia)  │  │ (Frankfurt)  │  │ (Beijing) │ │
│  └──────────────┘  └──────────────┘  └──────────┘ │
│         │                 │               │        │
│  ┌──────▼───────┐  ┌──────▼───────┐              │
│  │  US R2       │  │  EU R2       │              │
│  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────┘

// src/middleware/geo-router.ts
// Edge middleware that routes to the correct regional deployment

export const geoRouter = createServerFn({ method: "GET" }).handler(
  async (_, { request }) => {
    const country = request.cf?.country ?? "US"

    if (["CN", "HK", "MO"].includes(country)) {
      return env.CN_DB
    }

    if (EU_COUNTRIES.has(country)) {
      return env.EU_DB
    }

    return env.US_DB
  }
)

Multi-Currency Pricing Database Schema

CREATE TABLE price_tiers (
  id TEXT PRIMARY KEY,
  product_id TEXT NOT NULL REFERENCES products(id),
  region TEXT NOT NULL CHECK (region IN ('US', 'EU', 'CN', 'ROW', 'GLOBAL')),
  currency TEXT NOT NULL,
  unit_amount INTEGER NOT NULL,  -- In smallest currency unit (cents, fen, etc.)
  interval TEXT NOT NULL CHECK (interval IN ('month', 'year')),
  tax_behavior TEXT NOT NULL DEFAULT 'exclusive' CHECK (tax_behavior IN ('inclusive', 'exclusive')),
  is_active INTEGER NOT NULL DEFAULT 1,
  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
  updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
  UNIQUE(product_id, region, interval)
);

CREATE INDEX idx_price_tiers_region ON price_tiers(region);

// src/lib/pricing/regional.ts
export async function getRegionalPrice(
  productId: string,
  region: "US" | "EU" | "CN" | "ROW",
  interval: "month" | "year"
) {
  const price = await env.DB.prepare(
    `SELECT unit_amount, currency, tax_behavior
     FROM price_tiers
     WHERE product_id = ? AND region = ? AND interval = ? AND is_active = 1
     ORDER BY created_at DESC
     LIMIT 1`
  )
    .bind(productId, region, interval)
    .first()
  return price
}

Globalization Readiness Checklist

Before launching in a new market, verify each item:

[ ] Content is fully translated (not just UI, but transactional emails, docs, error pages)
[ ] Date/time/number formatting uses Intl.* APIs (never hardcoded)
[ ] Currency symbols and formats match local expectations (€29,99 vs ¥199 vs $29.99)
[ ] Regional payment methods are integrated and tested with sandbox credentials
[ ] Tax calculation is automated per region (VAT, sales tax, consumption tax)
[ ] Data residency requirements are met (GDPR EU, PIPL China, CCPA California)
[ ] Privacy policy covers all applicable regulations (separate versions per region)
[ ] CDN/edge routing directs users to the nearest regional deployment
[ ] Email deliverability is configured for regional providers (QQ, 163, GMX, Gmail)
[ ] Social login options include region-specific providers (WeChat, LINE, LinkedIn)
[ ] Terms of Service are localized and legally reviewed per jurisdiction
[ ] Customer support channels cover regional time zones (email, chat, phone)
[ ] Pricing is localized to market expectations (not just currency conversion)
[ ] ICP license is obtained for China (allow 4-8 weeks processing time)
[ ] Cookie consent mechanism is GDPR-compliant (granular, documented)

Conclusion

Globalizing a SaaS product is a multi-dimensional challenge that touches every part of your stack — from database sharding and edge deployment to payment processing and legal compliance. The key takeaways:

Build globalization into your architecture from day one — retrofitting regional routing, multi-currency pricing, and data residency onto a monolithic system is prohibitively expensive
Each market has a dominant constraint: GDPR (data privacy) in Europe, ICP/GFW (infrastructure) in China, and sales tax nexus (tax complexity) in the US
Payments are the hardest part — you need at least 3 payment providers (Stripe, Alipay/WeChat, SEPA) to cover all three markets
Edge deployment is your friend — Cloudflare Workers' regional routing makes data residency compliance much simpler than traditional VPS-based architectures
Test with real users in each market — localization bugs (wrong date formats, truncated text in Chinese characters, missing RTL support) only surface with native users

The companies that win at globalization are not the ones with the most features — they are the ones that make every user feel like the product was built for their market.

Related Resources

Designing SaaS Database Architecture: Users, Organizations, Subscriptions, and Billing

sweet — Tue, 23 Jun 2026 01:04:00 +0000

SaaS database architecture decisions made in the first week will haunt you for years. This guide walks through a battle-tested multi-tenant schema design covering users, organizations, role-based memberships, subscription state machines, and billing records. Each section includes production-ready SQL, indexing strategies, and migration patterns you can adapt directly to PostgreSQL, D1, or any relational database.

Introduction

Every SaaS founder starts with a simple vision: sign up, pay, use the product. But under the hood, that "simple" flow requires a database schema that balances multi-tenancy isolation, billing accuracy, and future flexibility. Get it wrong, and you'll be rewriting migrations six months in — while your customers are waiting for invoices.

The schema you design today determines how easily you can:

Add organization-level billing without breaking per-user features
Implement role-based access control (RBAC) across teams
Run trial-to-paid conversions without manual data fixes
Generate accurate invoices and revenue reports

Multi-Tenancy Strategy

Before we write a single CREATE TABLE, we need to decide how to isolate data between tenants:

Strategy	Isolation	Complexity	Best For
Row-level (shared DB)	Low	Low	Early-stage, B2C
Schema-level (separate schemas)	Medium	Medium	Mid-stage, regulatory needs
Database-level (separate DBs)	High	High	Enterprise, PCI/HIPAA

For 90% of SaaS products starting today, row-level multi-tenancy with a shared database is the correct choice. It keeps operational complexity low and allows cross-tenant analytics with a simple WHERE organization_id = ?.

The key is to enforce tenant isolation at the application layer — every query must filter by organization_id. Never trust client-provided IDs.

Core Entities and Relationships

User ── MemberOf ── Organization
                         │
                    Subscription
                         │
                    Invoice
                         │
                   InvoiceLineItem

1. Users

Users are individuals who authenticate. Keep this table lean — identity data only.

CREATE TABLE users (
    id            TEXT PRIMARY KEY,
    email         TEXT NOT NULL UNIQUE,
    name          TEXT NOT NULL,
    avatar_url    TEXT,
    created_at    INTEGER NOT NULL DEFAULT (unixepoch()),
    updated_at    INTEGER NOT NULL DEFAULT (unixepoch())
);

CREATE INDEX idx_users_email ON users(email);

Design notes: Use TEXT IDs (UUIDs) to avoid enumeration attacks. Store timestamps as Unix integers for timezone-agnostic comparisons.

2. Organizations

Organizations are the tenant boundary. Every subscription belongs to an org, not a user.

CREATE TABLE organizations (
    id          TEXT PRIMARY KEY,
    name        TEXT NOT NULL,
    slug        TEXT NOT NULL UNIQUE,
    logo_url    TEXT,
    created_at  INTEGER NOT NULL DEFAULT (unixepoch()),
    updated_at  INTEGER NOT NULL DEFAULT (unixepoch())
);

CREATE UNIQUE INDEX idx_orgs_slug ON organizations(slug);

Why orgs matter: Billing to users directly breaks when a team of five wants one shared subscription. Always bill to organizations. Users come and go; organizations persist.

3. Memberships (Users ↔ Organizations)

The join table with roles. Never store the role directly on the users table.

CREATE TABLE memberships (
    id              TEXT PRIMARY KEY,
    user_id         TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    organization_id TEXT NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
    role            TEXT NOT NULL DEFAULT 'member' CHECK (role IN ('owner', 'admin', 'member', 'billing')),
    joined_at       INTEGER NOT NULL DEFAULT (unixepoch()),
    UNIQUE (user_id, organization_id)
);

CREATE INDEX idx_memberships_user ON memberships(user_id);
CREATE INDEX idx_memberships_org  ON memberships(organization_id);

Role hierarchy: owner (full control) -> admin (manage members) -> member (standard access) -> billing (view invoices only).

4. Subscriptions

This is the heart of your billing system. A subscription links an organization to a plan and tracks its lifecycle through a state machine.

CREATE TABLE subscriptions (
    id                TEXT PRIMARY KEY,
    organization_id   TEXT NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
    plan_id           TEXT NOT NULL,
    status            TEXT NOT NULL DEFAULT 'trialing'
                      CHECK (status IN ('trialing', 'active', 'past_due', 'canceled', 'expired', 'incomplete')),
    current_period_start INTEGER NOT NULL,
    current_period_end   INTEGER NOT NULL,
    trial_start       INTEGER,
    trial_end         INTEGER,
    canceled_at       INTEGER,
    ended_at          INTEGER,
    created_at        INTEGER NOT NULL DEFAULT (unixepoch()),
    updated_at        INTEGER NOT NULL DEFAULT (unixepoch())
);

CREATE INDEX idx_subs_org    ON subscriptions(organization_id);
CREATE INDEX idx_subs_status ON subscriptions(status);
CREATE INDEX idx_subs_period ON subscriptions(current_period_end);

Subscription State Machine

  trialing ──→ active ──→ past_due ──→ canceled/expired
                  ↑
                  └─── (renewal fails)

trialing → automatically converts to active when trial ends and payment succeeds
active → happy path. Dunning starts if payment fails
past_due → payment failed. Grace period (3-14 days), then canceled or expired
canceled → user or system canceled. Access until period end
expired → final state. No access
incomplete → initial payment failed (card declined on first attempt)

Never use a boolean is_active column. A state machine with explicit transitions prevents ambiguous states.

5. Invoices

CREATE TABLE invoices (
    id                TEXT PRIMARY KEY,
    organization_id   TEXT NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
    subscription_id   TEXT REFERENCES subscriptions(id),
    stripe_invoice_id TEXT,
    status            TEXT NOT NULL DEFAULT 'draft'
                      CHECK (status IN ('draft', 'open', 'paid', 'void', 'uncollectible')),
    amount_due        INTEGER NOT NULL,  -- in cents
    amount_paid       INTEGER NOT NULL DEFAULT 0,
    currency          TEXT NOT NULL DEFAULT 'usd',
    due_date          INTEGER,
    paid_at           INTEGER,
    created_at        INTEGER NOT NULL DEFAULT (unixepoch())
);

CREATE INDEX idx_invoices_org  ON invoices(organization_id);
CREATE INDEX idx_invoices_sub  ON invoices(subscription_id);

6. Invoice Line Items

CREATE TABLE invoice_line_items (
    id           TEXT PRIMARY KEY,
    invoice_id   TEXT NOT NULL REFERENCES invoices(id) ON DELETE CASCADE,
    description  TEXT NOT NULL,
    quantity     INTEGER NOT NULL DEFAULT 1,
    unit_amount  INTEGER NOT NULL,  -- in cents
    total_amount INTEGER NOT NULL,
    type         TEXT NOT NULL CHECK (type IN ('subscription', 'addon', 'credit', 'tax', 'adjustment')),
    created_at   INTEGER NOT NULL DEFAULT (unixepoch())
);

CREATE INDEX idx_ili_invoice ON invoice_line_items(invoice_id);

Storing individual line items is critical for prorated refunds, tax reporting, and usage-based billing breakdowns.

Billing and Invoicing Design

Flat-Rate Subscription

Charge a fixed amount per period. Simple, predictable.

Per-Seat (Per-User)

Multiply the unit price by the number of active members:

SELECT m.organization_id, COUNT(*) AS member_count
FROM memberships m
WHERE m.organization_id = ?
  AND m.role != 'billing'
GROUP BY m.organization_id;

Usage-Based

Store usage events in a separate table:

CREATE TABLE usage_events (
    id              TEXT PRIMARY KEY,
    organization_id TEXT NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
    metric_name     TEXT NOT NULL,
    quantity        INTEGER NOT NULL,
    recorded_at     INTEGER NOT NULL DEFAULT (unixepoch())
);

CREATE INDEX idx_usage_event ON usage_events(organization_id, metric_name, recorded_at);

Common Pitfalls

N+1 Queries in Billing

-- BAD: N+1 — one query for the org, then N per subscription
SELECT * FROM organizations;

-- GOOD: single join
SELECT o.name, s.status, s.current_period_end
FROM organizations o
LEFT JOIN subscriptions s ON s.organization_id = o.id;

Missing Index on `current_period_end`

If you run a daily cron to expire subscriptions, this query runs a full table scan without an index:

SELECT id FROM subscriptions
WHERE status = 'active' AND current_period_end < unixepoch();

Cascading Deletes That Destroy Billing Records

If you accidentally delete an org, all invoices vanish. Consider ON DELETE RESTRICT or a soft-delete (deleted_at column) for financial records.

Storing Monetary Values as Floats

Never use FLOAT or REAL for money. Always use integer cents:

amount_due INTEGER NOT NULL  -- $29.99 -> 2999

Conclusion

A well-designed SaaS database schema is invisible when it works and catastrophic when it doesn't. The entities and patterns in this guide — users, organizations, memberships, subscriptions with state machines, and normalized invoicing — have been refined across production systems handling thousands of tenants.

Start with row-level multi-tenancy. Bill organizations, not users. Model subscription status as an explicit state machine. Store money as integers. Add indexes for your query patterns. And always, always write reversible migrations.

Related Resources

SaaS Customer Onboarding: Turning Signups into Active, Paid Users

sweet — Mon, 22 Jun 2026 01:01:00 +0000

Onboarding is the most important funnel in your SaaS. If users do not reach the "aha moment" within their first session, they will not return. This guide covers a systematic approach to onboarding design — activation milestones, progressive disclosure, guided tours, empty states, and the metrics that separate effective onboarding from ineffective onboarding. The patterns described here power the onboarding flow at tanstackship.com.

The Onboarding Funnel

A typical SaaS signup funnel looks like this:

1,000 website visitors
   → 50 signups (5% conversion)
     → 25 complete setup (50% activation)
       → 10 reach "aha moment" (40% of activated)
         → 5 convert to paid (50% conversion)
           → 3 remain active after 90 days (60% retention)

The biggest drop-off is between signup and activation. Most SaaS products lose 60-80% of signups in the first session. Fixing this drop-off has the highest ROI of any optimization.

The Activation Milestone

Every SaaS has an "aha moment" — the point where users experience the core value. Define yours:

Activation Milestone Examples

SaaS Type	Aha Moment	Metrics to Track
Project management	First project created with 3+ tasks	Projects created, tasks added
Analytics	First dashboard with live data	Data sources connected, first report viewed
CRM	First contact imported and organized	Contacts imported, lists created
Design tool	First design export	Assets created, exports completed
Developer tool	First successful deployment	Deployments, API calls

For a SaaS starter like tanstackship.com, the activation milestone might be: "User configures their first subscription plan and sees the billing preview."

The First Session

Minute 1: Value Preview

Show the "end state" immediately. Do not make users configure before they can see value:

// components/onboarding/ValuePreview.tsx
function ValuePreview() {
  return (
    <div className="onboarding-step">
      <h2>See what your dashboard will look like</h2>
      <div className="mockup-container">
        <DashboardMockup /> {/* Pre-rendered example */}
      </div>
      <p className="hint">
        Your actual data will appear here once configured.
        This is what it will look like.
      </p>
      <button onClick={() => startSetup()}>
        Start Setup (2 minutes)
      </button>
    </div>
  )
}

Minutes 2-5: Progressive Setup

Ask for the minimum information needed to show value:

// server/onboarding.ts
export const completeQuickStart = createServerFn({ method: "POST" }).handler(
  async ({ data, context }: {
    data: {
      companyName: string
      productType: string
    }
  }) => {
    // Only ask for essential info in the first session
    await context.env.DB.prepare(`
      UPDATE users SET
        company_name = ?,
        product_type = ?,
        onboarding_step = 'first_dashboard'
      WHERE id = ?
    `).bind(data.companyName, data.productType, context.user.id).run()

    // Generate initial data based on product type
    await generateSampleData(context.user.id, data.productType)

    return { redirectTo: "/dashboard" }
  }
)

Onboarding Flow Patterns

Pattern 1: Guided Checklist

// components/onboarding/Checklist.tsx
type OnboardingStep = {
  id: string
  title: string
  description: string
  isComplete: boolean
  link: string
}

function OnboardingChecklist({ steps }: { steps: OnboardingStep[] }) {
  const completed = steps.filter((s) => s.isComplete).length

  return (
    <div className="onboarding-checklist">
      <div className="progress-bar">
        <div
          className="progress-fill"
          style={{ width: `${(completed / steps.length) * 100}%` }}
        />
      </div>
      <p className="progress-text">
        {completed} of {steps.length} steps complete
      </p>
      <ul>
        {steps.map((step) => (
          <li key={step.id} className={step.isComplete ? "done" : "pending"}>
            {step.isComplete ? (
              <CheckIcon />
            ) : (
              <Link to={step.link}>
                <span>{step.title}</span>
                <span className="description">{step.description}</span>
              </Link>
            )}
          </li>
        ))}
      </ul>
    </div>
  )
}

Pattern 2: Progressive Disclosure

Show advanced features only after the user has completed basics:

// Fetch user's current capability level
const capabilityLevel = await context.env.DB.prepare(`
  SELECT onboarding_step, features_unlocked
  FROM users WHERE id = ?
`).bind(userId).first()

// Only show advanced features if the basics are done
const features = capabilityLevel.features_unlocked
  ? allFeatures
  : allFeatures.filter((f) => !f.requiresSetup)

Pattern 3: Empty States That Guide

Every empty page is an onboarding opportunity:

// components/EmptyState.tsx
function EmptySubscriptionList() {
  return (
    <div className="empty-state">
      <Icon name="subscriptions" />
      <h3>No subscriptions yet</h3>
      <p>Your first subscription is a few clicks away.</p>
      <Button onClick={() => navigate("/settings/stripe")}>
        Connect Stripe → See subscriptions in seconds
      </Button>
    </div>
  )
}

Measuring Onboarding Effectiveness

Key Metrics

Metric	Definition	Good	Needs Work
Time to Activation	Time from signup to first aha moment	< 5 min	> 15 min
Activation Rate	% of signups who reach activation	> 50%	< 30%
Setup Completion	% who complete onboarding checklist	> 70%	< 40%
Day 1 Retention	% who return within 24 hours	> 60%	< 30%
Day 7 Retention	% who return within 7 days	> 40%	< 20%

Tracking in D1

// server/onboarding/tracking.ts
export const trackOnboardingStep = createServerFn({ method: "POST" }).handler(
  async ({ data, context }: {
    data: { step: string; duration: number; error?: string }
  }) => {
    await context.env.DB.prepare(`
      INSERT INTO onboarding_events
        (id, user_id, step, duration_ms, error, created_at)
      VALUES (?, ?, ?, ?, ?, ?)
    `).bind(
      crypto.randomUUID(),
      context.user.id,
      data.step,
      data.duration,
      data.error ?? null,
      Date.now()
    ).run()
  }
)

A/B Testing Onboarding Flows

// Assign user to a variant
export const getOnboardingVariant = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const variants = ["guided_checklist", "progressive_disclosure", "video_tour"]
    const index = Math.abs(hashString(context.user.id)) % variants.length
    const variant = variants[index]

    // Track assignment
    await context.env.DB.prepare(`
      INSERT INTO ab_tests
        (id, user_id, test_name, variant, created_at)
      VALUES (?, ?, 'onboarding_flow', ?, ?)
    `).bind(crypto.randomUUID(), context.user.id, variant, Date.now()).run()

    return { variant }
  }
)

The Onboarding-to-Paid Transition

The moment between activation and first payment is delicate. The user has seen value but has not yet committed:

// Trigger when user completes activation milestone
export const checkActivation = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const user = await context.env.DB.prepare(`
      SELECT onboarding_step, subscription_status
      FROM users WHERE id = ?
    `).bind(context.user.id).first()

    if (user.onboarding_step === 'complete' && !user.subscription_status) {
      // User is activated but not subscribed → show upgrade prompt
      return {
        showUpgrade: true,
        timing: 'post_activation',
      }
    }
  }
)

Onboarding Anti-Patterns

Anti-Pattern	Why It Fails	Better Approach
Ask for everything upfront	Overwhelms users	Progressive disclosure
No guided tour	Users get lost	Contextual tooltips
Perfect data required	Users cannot start	Sample data pre-populated
All features shown at once	Cognitive overload	Feature gating by progress
No progress indication	Users do not know how far they are	Visual progress bar
Email-only onboarding	Low engagement	In-app guidance
No value preview	Users must build before they see	Pre-rendered examples

Advanced: Using UTM Data to Personalize Onboarding

If the user arrived from a specific campaign, customize their onboarding:

export const getPersonalizedOnboarding = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const utmData = await context.env.DB.prepare(`
      SELECT utm_source, utm_campaign, utm_content
      FROM utm_clicks
      WHERE user_id = ?
      ORDER BY created_at DESC
      LIMIT 1
    `).bind(context.user.id).first()

    // Different onboarding for different sources
    if (utmData?.utm_campaign === "feature_stripe") {
      return { template: "stripe_focused_onboarding" }
    }

    return { template: "default_onboarding" }
  }
)

Onboarding Flow Checklist

[ ] Define the activation milestone (what is the "aha moment"?)
[ ] Track every onboarding step with timing data
[ ] Empty states guide users toward the next action
[ ] Progress indicator visible throughout onboarding
[ ] Sample data available for immediate value
[ ] Advanced features gated behind basic setup
[ ] Upgrade prompt shown after activation, not before
[ ] A/B testing infrastructure for onboarding variants
[ ] Email follow-up for users who do not complete setup
[ ] Onboarding analytics dashboard to monitor drop-offs

Conclusion

Onboarding is not a tutorial — it is the bridge between a curious signup and an active user. The best onboarding flows are invisible: users experience the value of the product before they realize they are being guided.

The principles are universal:

Show value immediately (preview, mockup, sample data)
Ask for the minimum information needed to progress
Guide through empty states (not modals or overlays)
Measure every step with timing data
Personalize based on acquisition source

For a SaaS starter with built-in onboarding infrastructure — progress tracking, A/B testing, UTM-based personalization — see tanstackship.com.

Related Resources

Conversion Rate Optimization for SaaS: A/B Testing, Psychology, and Data

sweet — Sun, 21 Jun 2026 00:57:00 +0000

CRO is the systematic process of increasing the percentage of visitors who take a desired action — signing up, starting a trial, or upgrading to a paid plan. It combines rigorous A/B testing methodology with psychology principles and data analysis. This guide covers the CRO framework used at tanstackship.com, including landing page optimization, pricing page design, trial conversion flows, and the infrastructure needed to run continuous experiments.

The CRO Funnel for SaaS


Traffic (100%)
  │
  ▼
Landing Page (5-15% → signup)
  │
  ▼
Signup → Activation (30-60%)
  │
  ▼
Free/Active User (20-40% → paid)
  │
  ▼
Paying Customer
  │
  ▼
Retained Customer

Improving each step by 10% compounds:
100 visitors → 10 signups → 5 paid → 3 retained
100 visitors → 11 signups → 6 paid → 4 retained
= 33% more retained customers from the same traffic

A/B Testing Methodology

Statistical Foundation

// A/B test calculator
export const calculateABTest = createServerFn({ method: "POST" }).handler(
  async ({ data }: { data: {
    controlVisitors: number
    controlConversions: number
    variantVisitors: number
    variantConversions: number
  }}) => {
    const controlRate = data.controlConversions / data.controlVisitors
    const variantRate = data.variantConversions / data.variantVisitors

    // Calculate statistical significance (chi-squared)
    const improvement = ((variantRate - controlRate) / controlRate) * 100

    // Sample size needed for 80% power at 95% significance
    const baseline = controlRate
    const minimumDetectableEffect = 0.1 // 10% relative improvement
    const zAlpha = 1.96 // 95% confidence
    const zBeta = 0.84 // 80% power
    const sampleSize =
      ((zAlpha + zBeta) ** 2 * 2 * baseline * (1 - baseline)) /
      (minimumDetectableEffect ** 2)

    return {
      controlRate,
      variantRate,
      improvement,
      sampleSizeNeeded: Math.ceil(sampleSize),
      currentSampleSize: data.controlVisitors + data.variantVisitors,
      sufficientData: (data.controlVisitors + data.variantVisitors) >= sampleSize,
    }
  }
)

Test Requirements

Requirement	Minimum	Recommended
Sample size per variant	1,000	5,000+
Test duration	7 days	14 days (full business cycle)
Statistical significance	90%	95%
Minimum detectable effect	20%	10%

Psychology Principles for SaaS

Principle	Application	Example
Anchoring	Show higher price first	Enterprise plan before Starter
Social proof	Show user counts, testimonials	"Join 1,200+ SaaS teams"
Scarcity	Limited-time offers	"Early adopter pricing ends soon"
Loss aversion	Emphasize what they lose	"You're missing out on..."
Commitment	Start small, build up	Free tier → paid upgrade
Reciprocity	Give value before asking	Free guides, templates, tools
Decoy effect	Third option makes one clearly best	Three pricing tiers
Authority	Expert endorsements	"Recommended by [expert name]"

The Decoy Effect on Pricing Pages

Tier A: $19/mo (Starter)    ← You want this to sell
Tier B: $39/mo (Pro)        ← Decoy — slightly worse value than C
Tier C: $49/mo (Enterprise) ← High-end anchor

Without decoy: A and C are compared directly
With decoy: B makes A look like a great deal
             (or C makes B look reasonable)

Landing Page Optimization

Above the Fold

// A/B test: headline variants
const headlineVariants = {
  control: {
    headline: "Build Your SaaS Faster",
    subheadline: "A production-ready starter with auth, billing, and more.",
    cta: "Get Started",
  },
  variantA: {
    headline: "Ship Your SaaS in Days, Not Months",
    subheadline: "Pre-built auth, billing, marketing, and multi-language support.",
    cta: "Start Building Free →",
  },
  variantB: {
    headline: "The SaaS Starter That Saves You 200 Hours",
    subheadline: "Everything you need to launch — without rebuilding the boring parts.",
    cta: "See What's Included",
  },
}

Hero Section Testing

Element	Test	Typical Win
Headline	Benefit vs feature	Benefit wins 80%
CTA button	Color, size, text	High contrast, action-oriented
Hero image	Screenshot vs illustration	Product screenshot wins
Social proof	Count vs testimonial	Count for awareness, testimonial for conversion
Form placement	Above fold vs scroll	Above fold wins for B2B SaaS

Pricing Page Optimization

Pricing Page Structure

Best practices for SaaS pricing pages:

1. Anchor with highest price first (for annual/monthly toggle)
2. Highlight "Most Popular" or "Recommended" badge
3. Include a comparison table for features
4. Show annual savings prominently ("Save 20%")
5. Offer a free trial or money-back guarantee
6. Use social proof near the CTA
7. Remove navigation links (reduce distraction)

A/B Testing Pricing

// Dynamic pricing based on A/B test assignment
export const getPricingVariant = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const variants = [
      { id: "control", starter: 29, pro: 79, enterprise: 199 },
      { id: "lower_prices", starter: 19, pro: 59, enterprise: 149 },
      { id: "higher_prices", starter: 39, pro: 99, enterprise: 249 },
      { id: "different_tiers", starter: 29, growth: 69, scale: 149 },
    ]

    const index = Math.abs(hashString(context.user.id ?? "anon")) % variants.length
    const variant = variants[index]

    // Track assignment
    await context.env.DB.prepare(`
      INSERT INTO ab_assignments
        (user_id, test_name, variant, assigned_at)
      VALUES (?, 'pricing_page', ?, ?)
    `).bind(context.user.id ?? "anon", variant.id, Date.now()).run()

    return variant
  }
)

Trial-to-Paid Conversion

Trial Funnel Metrics

Metric	Definition	Good	Needs Work
Trial start rate	% of signups who start trial	> 60%	< 40%
Activation rate	% who reach aha moment during trial	> 50%	< 30%
Day 3 active	% returning within 3 days	> 40%	< 20%
Conversion rate	% who convert before trial ends	> 20%	< 10%
Conversion timing	Average day of conversion	Day 10-14	Day 28+

Trial Emails Sequence

const trialEmailSequence = [
  { day: 0, type: "welcome", subject: "Welcome! Here's your first step" },
  { day: 1, type: "activation", subject: "Set up your project in 2 minutes" },
  { day: 3, type: "tip", subject: "Most users love this feature" },
  { day: 5, type: "case_study", subject: "How [customer] saved 20 hours/week" },
  { day: 7, type: "mid_trial", subject: "Halfway through your trial" },
  { day: 10, type: "offer", subject: "Convert now and save 20% on annual" },
  { day: 12, type: "urgent", subject: "Your trial ends in 2 days" },
  { day: 14, type: "expired", subject: "Your trial has ended" },
]

CRO Infrastructure

// Database schema for experiments
export const experiments = sqliteTable("experiments", {
  id: text("id").primaryKey(),
  name: text("name").notNull(),
  slug: text("slug").notNull().unique(),
  status: text("status", {
    enum: ["draft", "running", "paused", "concluded"],
  }).notNull().default("draft"),
  controlVariant: text("control_variant").notNull(),
  variants: text("variants").notNull(), // JSON array
  hypothesis: text("hypothesis"),
  targetMetric: text("target_metric").notNull(),
  minimumSampleSize: integer("minimum_sample_size"),
  startedAt: integer("started_at", { mode: "timestamp" }),
  concludedAt: integer("concluded_at", { mode: "timestamp" }),
  winnerVariant: text("winner_variant"),
})

// Track event for experiment
export const trackExperimentEvent = createServerFn({ method: "POST" }).handler(
  async ({ data, context }: { data: {
    experimentId: string
    variant: string
    event: string
    value?: number
  }}) => {
    await context.env.DB.prepare(`
      INSERT INTO experiment_events
        (id, experiment_id, variant, event, value, user_id, created_at)
      VALUES (?, ?, ?, ?, ?, ?, ?)
    `).bind(
      crypto.randomUUID(),
      data.experimentId,
      data.variant,
      data.event,
      data.value ?? null,
      context.user.id ?? null,
      Date.now()
    ).run()
  }
)

CRO Wins for SaaS

Optimization	Typical Lift	Difficulty	Implementation
Add social proof to landing page	+15-30%	Low	Add testimonial section
Simplify signup form (3 fields → 1)	+20-40%	Low	OAuth-only signup option
Add guarantee to pricing	+10-25%	Low	"14-day money back" badge
Highlight "Most Popular" plan	+15-20%	Low	CSS badge on pricing card
Annual pricing discount	+20-30% trial conversion	Medium	Toggle on pricing page
Email sequence during trial	+30-50% trial conversion	Medium	Automated email campaign
Personalized onboarding	+20-35% activation	High	UTM-based customization
In-app upgrade prompt	+15-25%	Medium	Contextual upsell

CRO Process Checklist

[ ] Conversion funnel defined and tracked (visit → signup → activate → pay → retain)
[ ] Baseline conversion rates established for each funnel stage
[ ] Hypothesis documented before every test (why this change should work)
[ ] A/B test statistical requirements met (sample size, duration, significance)
[ ] Only one variable changed per test
[ ] Results analyzed before implementing changes
[ ] Winning variants implemented permanently
[ ] Losing variants analyzed for insights
[ ] CRO results documented and shared with team
[ ] Continuous testing pipeline established (one test always running)

Conclusion

CRO is not about tricking users into converting — it is about removing friction and building trust at every stage of the funnel. Every element of your landing page, signup flow, pricing page, and trial experience either builds confidence or creates doubt.

The methodology is scientific: form a hypothesis, run a controlled experiment, analyze the data, implement the winner. Small improvements compound: a 10% improvement at each of the four funnel stages (visit → signup → activate → pay) results in a 46% overall improvement in paid conversions.

For a SaaS with built-in A/B testing infrastructure, conversion tracking, and analytics, see tanstackship.com.

Related Resources

How to Design an Effective Referral Reward System: A Complete Technical Guide for SaaS

sweet — Sat, 20 Jun 2026 00:54:00 +0000

A well-designed referral program can be the highest-ROI customer acquisition channel for SaaS products, with referred customers typically having 25-30% higher retention and 16% higher lifetime value. This guide covers the complete implementation — from reward structure psychology and invite code generation to credit engine architecture, fraud prevention, and analytics. Includes production-ready database schemas and server-side code for TanStack Start with Cloudflare D1. See the referral system live at tanstackship.com.

Why Referral Programs Work (The Data)

Referral marketing is not just a growth tactic — it is a trust mechanic. People trust recommendations from peers more than any other form of marketing:

Channel	Trust Rate	Conversion Rate	Avg. LTV	Source
Friend referral	92%	10-30%	+16% higher	Nielsen
Online review	70%	3-10%	Baseline	BrightLocal
Paid ad	25%	0.5-2%	-20% lower	Meta Ads

For SaaS specifically, referred customers have 25-30% lower churn and a 16% higher lifetime value compared to organically acquired customers (Deloitte). This is because:

Pre-qualified leads: The referrer only invites people who would genuinely benefit
Social onboarding: New users have a built-in "buddy" who helps them get started
Network effects: As more people in a team/organization join, stickiness increases

Reward Structure: What Works and What Does Not

The Two-Sided Reward Model

The most effective SaaS referral programs reward both the referrer and the referred user:

Model	Referrer Gets	Referee Gets	Example Companies
Two-sided discount	1 month free	20% off first 3 months	Dropbox, Airbnb
Two-sided credit	$50 account credit	$25 account credit	Uber, Robinhood
One-sided reward	1 month free	Nothing	(Less effective)
Donation-based	$5 to charity	$5 to charity	TOMS, Warby Parker (B2C)

Determining the Reward Value

The golden rule: Your reward should offset 25-50% of one month's subscription value.

For a $29/month SaaS:
  - Referrer reward: $7.25 - $14.50 in credit (1-2 weeks free)
  - Referee reward: $7.25 - $14.50 in credit

For a $99/month SaaS:
  - Referrer reward: $25 - $50 in credit
  - Referee reward: $25 - $50 in credit

Credit vs. Discount vs. Cash

Reward Type	Pros	Cons	Best For
Service credit	Low cost (zero marginal cost), encourages continued use	User may not need more credit	SaaS with usage-based billing
Subscription discount	Directly reduces churn barrier	Complex to implement with billing intervals	Monthly subscription SaaS
Cash/ PayPal	Highest motivation	Expensive, feels transactional	Enterprise SaaS
Gift cards	Simple to administer	Lower perceived value than cash	B2C/B2B hybrid
Feature unlocks	Zero cost, high perceived value	Only works with freemium model	Freemium products

Database Schema for Referral System

-- Table 1: Invite codes (generated by referrers)
CREATE TABLE invite_codes (
  id TEXT PRIMARY KEY,
  code TEXT NOT NULL UNIQUE, -- e.g., 'FRIEND-ABC123'
  creator_id TEXT NOT NULL, -- The user who created this code
  max_uses INTEGER DEFAULT 10,
  use_count INTEGER NOT NULL DEFAULT 0,
  reward_type TEXT NOT NULL DEFAULT 'credit' CHECK (
    reward_type IN ('credit', 'discount_percent', 'discount_fixed', 'month_free')
  ),
  reward_value INTEGER NOT NULL DEFAULT 500, -- In cents or percentage points
  is_active INTEGER NOT NULL DEFAULT 1,
  expires_at INTEGER, -- Optional expiration
  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
  FOREIGN KEY (creator_id) REFERENCES users(id)
);

CREATE INDEX idx_invite_codes_code ON invite_codes(code);
CREATE INDEX idx_invite_codes_creator ON invite_codes(creator_id);

-- Table 2: Redemption records
CREATE TABLE invite_redemptions (
  id TEXT PRIMARY KEY,
  invite_code_id TEXT NOT NULL,
  referrer_id TEXT NOT NULL, -- The person who shared the code
  referred_user_id TEXT NOT NULL, -- The new user who used the code
  reward_referrer INTEGER NOT NULL DEFAULT 0, -- Cents awarded to referrer
  reward_referred INTEGER NOT NULL DEFAULT 0, -- Cents awarded to referee
  status TEXT NOT NULL DEFAULT 'pending' CHECK (
    status IN ('pending', 'completed', 'expired', 'fraudulent')
  ),
  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
  completed_at INTEGER, -- When conditions were met (e.g., referee pays)
  FOREIGN KEY (invite_code_id) REFERENCES invite_codes(id),
  FOREIGN KEY (referrer_id) REFERENCES users(id),
  FOREIGN KEY (referred_user_id) REFERENCES users(id)
);

CREATE INDEX idx_invite_redemptions_referrer ON invite_redemptions(referrer_id);
CREATE INDEX idx_invite_redemptions_referred ON invite_redemptions(referred_user_id);

-- Table 3: Credit ledger (for credit-based rewards)
CREATE TABLE credit_ledger (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  amount_cents INTEGER NOT NULL, -- Positive for credit, negative for spend
  balance_after_cents INTEGER NOT NULL,
  reason TEXT NOT NULL CHECK (
    reason IN (
      'referral_reward', 'referral_signup_bonus',
      'credit_purchase', 'subscription_payment',
      'admin_adjustment', 'expired'
    )
  ),
  reference_id TEXT, -- Links to invite_redemptions or invoice
  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
  FOREIGN KEY (user_id) REFERENCES users(id)
);

CREATE INDEX idx_credit_ledger_user ON credit_ledger(user_id);

-- View: Referral statistics per user
CREATE VIEW referral_stats AS
SELECT
  ic.creator_id as user_id,
  COUNT(DISTINCT ir.id) as total_referrals,
  COUNT(DISTINCT CASE WHEN ir.status = 'completed' THEN ir.id END) as completed_referrals,
  COALESCE(SUM(CASE WHEN ir.status = 'completed' THEN ir.reward_referrer END), 0) as total_rewards_earned,
  ROUND(AVG(CASE WHEN ir.status = 'completed' THEN ir.reward_referrer END), 0) as avg_reward_per_referral
FROM invite_codes ic
LEFT JOIN invite_redemptions ir ON ir.invite_code_id = ic.id
GROUP BY ic.creator_id;

Invite Code Generation

// src/lib/invite/codes.ts
import { createServerFn } from "@tanstack/react-start"

// Secure, human-friendly invite code generation
export function generateInviteCode(length: number = 8): string {
  // Use a character set that avoids ambiguous characters
  const chars = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789" // No I, O, 0, 1
  const prefix = "FRIEND-"
  const random = Array.from({ length }, () =>
    chars[Math.floor(Math.random() * chars.length)]
  ).join("")
  return `${prefix}${random}`
}

export const createInviteCode = createServerFn({ method: "POST" }).handler(
  async (_, { request }) => {
    const userId = await getUserId(request)
    const code = generateInviteCode()

    // Ensure uniqueness (collision probability is negligible but check anyway)
    const existing = await env.DB.prepare(
      "SELECT id FROM invite_codes WHERE code = ?"
    ).bind(code).first()

    if (existing) {
      return createInviteCode(_, { request }) // Retry
    }

    // Default reward: 500 cents ($5.00) account credit for both parties
    await env.DB.prepare(
      `INSERT INTO invite_codes (id, code, creator_id, reward_value)
       VALUES (?, ?, ?, 500)`
    ).bind(crypto.randomUUID(), code, userId).run()

    return { code, shareUrl: `https://tanstackship.com/invite/${code}` }
  }
)

Referral Flow Implementation

Step 1: Share the Referral Link

// src/components/invite/ShareInvite.tsx
import { useMutation } from "@tanstack/react-query"
import { createInviteCode } from "../../lib/invite/codes"

export function ShareInvite() {
  const mutation = useMutation({
    mutationFn: () => createInviteCode(),
  })

  const shareUrl = mutation.data?.shareUrl ?? ""

  return (
    <div className="p-6 border rounded-lg">
      <h2 className="text-xl font-bold mb-4">Refer a Friend, Earn Credit</h2>
      <p className="text-gray-600 mb-4">
        Share your invite link and earn $5 for every friend who signs up
      </p>

      <button
        onClick={() => mutation.mutate()}
        className="bg-blue-600 text-white px-6 py-2 rounded-lg"
        disabled={mutation.isPending}
      >
        {mutation.isPending ? "Generating..." : "Get Your Referral Link"}
      </button>

      {shareUrl && (
        <div className="mt-4">
          <label className="block text-sm font-medium mb-1">
            Your referral link
          </label>
          <div className="flex gap-2">
            <input
              type="text"
              value={shareUrl}
              readOnly
              className="flex-1 px-3 py-2 border rounded"
            />
            <button
              onClick={() => navigator.clipboard.writeText(shareUrl)}
              className="px-4 py-2 bg-gray-100 rounded hover:bg-gray-200"
            >
              Copy
            </button>
          </div>
        </div>
      )}
    </div>
  )
}

Step 2: Redeem the Invite Code on Signup

// src/lib/invite/redeem.ts
import { createServerFn } from "@tanstack/react-start"

export const redeemInviteCode = createServerFn({ method: "POST" }).handler(
  async ({ code, newUserId }: { code: string; newUserId: string }) => {
    // Validate the invite code
    const invite = await env.DB.prepare(
      `SELECT ic.*, u.email as creator_email
       FROM invite_codes ic
       JOIN users u ON u.id = ic.creator_id
       WHERE ic.code = ? AND ic.is_active = 1
       AND (ic.expires_at IS NULL OR ic.expires_at > unixepoch())
       AND ic.use_count < ic.max_uses`
    ).bind(code).first()

    if (!invite) {
      return { success: false, error: "Invalid or expired invite code" }
    }

    // Prevent self-referral
    if (invite.creator_id === newUserId) {
      return { success: false, error: "You cannot use your own invite code" }
    }

    const now = Math.floor(Date.now() / 1000)
    const redemptionId = crypto.randomUUID()

    // Create redemption record (pending until condition is met)
    await env.DB.prepare(
      `INSERT INTO invite_redemptions
        (id, invite_code_id, referrer_id, referred_user_id,
         reward_referrer, reward_referred, status, created_at)
       VALUES (?, ?, ?, ?, ?, ?, 'pending', ?)`
    ).bind(
      redemptionId,
      invite.id,
      invite.creator_id,
      newUserId,
      invite.reward_value, // Referrer gets the reward
      invite.reward_value, // Referee gets the reward
      now
    ).run()

    // Increment code usage
    await env.DB.prepare(
      `UPDATE invite_codes SET use_count = use_count + 1 WHERE id = ?`
    ).bind(invite.id).run()

    // Award credit to the referred user immediately (signup bonus)
    await awardCredit(newUserId, invite.reward_value, "referral_signup_bonus", redemptionId)

    return { success: true, bonusAmount: invite.reward_value }
  }
)

Step 3: Release Referrer Reward When Condition Is Met

// src/lib/invite/rewards.ts
// Triggered when the referred user completes their first payment
export const processReferralReward = createServerFn({ method: "POST" }).handler(
  async ({ referredUserId }: { referredUserId: string }) => {
    const pendingRedemption = await env.DB.prepare(
      `SELECT ir.*, ic.reward_type
       FROM invite_redemptions ir
       JOIN invite_codes ic ON ic.id = ir.invite_code_id
       WHERE ir.referred_user_id = ? AND ir.status = 'pending'`
    ).bind(referredUserId).first()

    if (!pendingRedemption) return { processed: false }

    // Award credit to the referrer
    await awardCredit(
      pendingRedemption.referrer_id,
      pendingRedemption.reward_referrer,
      "referral_reward",
      pendingRedemption.id
    )

    // Mark as completed
    await env.DB.prepare(
      `UPDATE invite_redemptions SET status = 'completed', completed_at = unixepoch()
       WHERE id = ?`
    ).bind(pendingRedemption.id).run()

    return { processed: true, amount: pendingRedemption.reward_referrer }
  }
)

Credit Engine Architecture

A robust credit system that handles referral rewards, subscription payments, and manual adjustments:

// src/lib/credit/engine.ts

export async function awardCredit(
  userId: string,
  amountCents: number,
  reason: CreditLedger["reason"],
  referenceId: string
) {
  const currentBalance = await getCreditBalance(userId)
  const newBalance = currentBalance + amountCents

  await env.DB.prepare(
    `INSERT INTO credit_ledger (id, user_id, amount_cents, balance_after_cents, reason, reference_id)
     VALUES (?, ?, ?, ?, ?, ?)`
  ).bind(
    crypto.randomUUID(),
    userId,
    amountCents,
    newBalance,
    reason,
    referenceId
  ).run()

  return newBalance
}

export async function spendCredit(
  userId: string,
  amountCents: number,
  referenceId: string
): Promise<boolean> {
  const balance = await getCreditBalance(userId)
  if (balance < amountCents) return false // Insufficient credit

  const newBalance = balance - amountCents

  await env.DB.prepare(
    `INSERT INTO credit_ledger (id, user_id, amount_cents, balance_after_cents, reason, reference_id)
     VALUES (?, ?, ?, ?, 'subscription_payment', ?)`
  ).bind(
    crypto.randomUUID(),
    userId,
    -amountCents,
    newBalance,
    referenceId
  ).run()

  return true
}

export async function getCreditBalance(userId: string): Promise<number> {
  const result = await env.DB.prepare(
    `SELECT balance_after_cents
     FROM credit_ledger
     WHERE user_id = ?
     ORDER BY created_at DESC
     LIMIT 1`
  ).bind(userId).first()

  return (result?.balance_after_cents as number) ?? 0
}

Fraud Prevention

Referral fraud is a real problem. Here is a multi-layered defense:

// src/lib/invite/fraud-detection.ts
import { createServerFn } from "@tanstack/react-start"

export const validateReferral = createServerFn({ method: "POST" }).handler(
  async ({ referrerId, refereeId, ipAddress }: {
    referrerId: string
    refereeId: string
    ipAddress: string
  }) => {
    const checks = await Promise.all([
      // Check 1: Same IP detection
      env.DB.prepare(
        `SELECT COUNT(*) as count FROM users
         WHERE ip_address = ? AND id != ?`
      ).bind(ipAddress, refereeId).first(),

      // Check 2: Referral velocity (how many in last 24h)
      env.DB.prepare(
        `SELECT COUNT(*) as count FROM invite_redemptions
         WHERE referrer_id = ? AND created_at > unixepoch() - 86400`
      ).bind(referrerId).first(),

      // Check 3: Same device fingerprint (if available)
      // Implementation depends on your fingerprinting approach
    ])

    const [ipCheck, velocityCheck] = (checks as [{ count: number }, { count: number }])

    if (ipCheck.count > 3) {
      // Flag for review — same IP as too many different users
      await flagForReview(referrerId, "referral_fraud_same_ip")
      return { valid: false, reason: "suspicious_activity" }
    }

    if (velocityCheck.count > 10) {
      // More than 10 referrals in 24 hours is suspicious for most SaaS
      await flagForReview(referrerId, "referral_fraud_high_velocity")
      return { valid: false, reason: "rate_limited" }
    }

    return { valid: true }
  }
)

Referral Program Analytics

-- Dashboard queries for monitoring referral program health

-- 1. Referral funnel
SELECT
  COUNT(DISTINCT ic.creator_id) as users_with_codes,
  COUNT(DISTINCT ir.referred_user_id) as users_who_clicked,
  COUNT(DISTINCT CASE WHEN ir.status = 'completed' THEN ir.referred_user_id END) as converted_referrals,
  COUNT(DISTINCT CASE WHEN s.status = 'active' THEN ir.referred_user_id END) as retained_referrals
FROM invite_codes ic
LEFT JOIN invite_redemptions ir ON ir.invite_code_id = ic.id
LEFT JOIN subscriptions s ON s.user_id = ir.referred_user_id AND s.status = 'active'

-- 2. Top referrers
SELECT
  u.email,
  COUNT(ir.id) as referrals_sent,
  COUNT(CASE WHEN ir.status = 'completed' THEN 1 END) as referrals_completed,
  SUM(CASE WHEN ir.status = 'completed' THEN ir.reward_referrer END) / 100.0 as rewards_earned
FROM users u
JOIN invite_codes ic ON ic.creator_id = u.id
LEFT JOIN invite_redemptions ir ON ir.invite_code_id = ic.id
GROUP BY u.id
ORDER BY referrals_completed DESC
LIMIT 25

-- 3. Referral vs. organic retention comparison
SELECT
  CASE WHEN ir.id IS NOT NULL THEN 'referred' ELSE 'organic' END as acquisition_channel,
  COUNT(DISTINCT u.id) as total_users,
  COUNT(DISTINCT CASE WHEN s.status = 'active' THEN u.id END) as active_users,
  ROUND(AVG(s.mrr), 2) as avg_mrr,
  ROUND(AVG(s.created_at - u.created_at) / 86400, 0) as avg_days_to_churn_or_now
FROM users u
LEFT JOIN subscriptions s ON s.user_id = u.id
LEFT JOIN invite_redemptions ir ON ir.referred_user_id = u.id
GROUP BY acquisition_channel

Referral Program Optimization Checklist

[ ] Reward structure is two-sided (both referrer and referee benefit)
[ ] Reward value is 25-50% of one month's subscription value
[ ] Invite codes are easy to share (URL, copy button, email, social)
[ ] Fraud prevention checks are in place (same IP, velocity, self-referral)
[ ] Credit system handles concurrent spends correctly
[ ] Referral rewards are released only after condition is met (not immediately)
[ ] Referral analytics dashboard shows funnel and ROI
[ ] Email notifications sent to referrer when friend signs up
[ ] Email notifications sent to referrer when reward is credited
[ ] A/B testing framework is in place for reward amounts
[ ] Terms of Service cover referral fraud and reward revocation
[ ] Self-referral detection prevents users from gaming the system

Conclusion

A referral program is not a "set and forget" growth channel — it requires careful design, implementation, and ongoing optimization. The key principles are:

Reward both sides of the transaction — the referrer and the referee should both feel like they won
Delay referrer rewards until the referee takes a valuable action (pays, activates) to prevent fraud
Build credit infrastructure first — a credit engine that handles referral rewards today can also handle support credits, beta tester rewards, and promotional giveaways tomorrow
Monitor for fraud continuously — what starts as a growth channel can become a cost center without proper controls
Measure referral LTV vs. organic LTV — if referred customers are not more valuable, your reward structure or targeting needs adjustment

When done right, referrals become your highest-quality, lowest-cost acquisition channel — and turn your customers into your most effective sales team.

Related Resources

Real User Monitoring: Measuring Web Performance in Production

sweet — Fri, 19 Jun 2026 01:20:00 +0000

Lab tests (Lighthouse, CI benchmarks) tell you how your app performs on a test machine. Real User Monitoring tells you how your app performs for actual users on their devices, networks, and locations. RUM catches performance issues that lab tests never will — slow connections, memory pressure, ad blocker interference, and geographic variance. This guide covers the RUM implementation at tanstackship.com.

Lab vs Field Data

Aspect	Lab (Lighthouse)	Field (RUM)
Environment	Controlled (Moto G4, slow 3G)	Real user devices
Network	Simulated throttling	Actual connections (5G, 4G, 3G, WiFi)
Location	Single location	Global (330+ Cloudflare locations)
Device	Fixed device profile	All devices and form factors
Sample size	Single run per PR	Every page load
Detects	Optimization opportunities	Actual user experience issues
Missing	What real users experience	Controlled comparison

The truth: Lab data tells you what to fix. Field data tells you what users actually experience. You need both.

RUM Data Collection

Setting Up Web Vitals Collection

// src/lib/rum.ts
import { onLCP, onCLS, onINP, onTTFB, onFCP } from "web-vitals/attribution"

type VitalName = "LCP" | "CLS" | "INP" | "TTFB" | "FCP"

interface VitalReport {
  name: VitalName
  value: number
  rating: "good" | "needs-improvement" | "poor"
  id: string
  metadata: Record<string, string>
  deviceType: string
  connectionType: string
}

export function initRUM() {
  const vitals: Array<{ name: VitalName; fn: (metric: any) => void }> = [
    { name: "LCP", fn: onLCP },
    { name: "CLS", fn: onCLS },
    { name: "INP", fn: onINP },
    { name: "TTFB", fn: onTTFB },
    { name: "FCP", fn: onFCP },
  ]

  vitals.forEach(({ name, fn }) => {
    fn((metric) => {
      sendVital({
        name,
        value: metric.value,
        rating: metric.rating,
        id: metric.id,
        metadata: extractAttribution(metric),
        deviceType: getDeviceType(),
        connectionType: getConnectionType(),
      })
    })
  })
}

function extractAttribution(metric: any): Record<string, string> {
  if (metric.attribution) {
    // Extract useful debugging info
    const { element, url, fcp, ...rest } = metric.attribution
    return {
      ...(element && { lcpElement: element.tagName }),
      ...(url && { lcpUrl: url }),
    }
  }
  return {}
}

function getDeviceType(): string {
  const ua = navigator.userAgent
  if (/Mobi|Android/i.test(ua)) return "mobile"
  if (/Tablet|iPad/i.test(ua)) return "tablet"
  return "desktop"
}

function getConnectionType(): string {
  const conn = (navigator as any).connection
  return conn?.effectiveType ?? "unknown"
}

Sending RUM Data to the Backend

// Use sendBeacon for reliable delivery (survives page navigation)
function sendVital(report: VitalReport) {
  const payload = {
    ...report,
    pathname: window.location.pathname,
    timestamp: Date.now(),
  }

  if (navigator.sendBeacon) {
    navigator.sendBeacon("/api/vitals", JSON.stringify(payload))
  } else {
    fetch("/api/vitals", {
      method: "POST",
      body: JSON.stringify(payload),
      keepalive: true,
    })
  }
}

Server-Side Storage

// server/rum.ts
export const reportVital = createServerFn({ method: "POST" }).handler(
  async ({ request, context }) => {
    const data = await request.json()

    // Store in D1 for querying
    await context.env.DB.prepare(`
      INSERT INTO rum_metrics (
        id, name, value, rating, pathname,
        device_type, connection_type,
        country, metadata, created_at
      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
    `).bind(
      data.id,
      data.name,
      data.value,
      data.rating,
      data.pathname,
      data.deviceType,
      data.connectionType,
      request.cf?.country ?? "unknown",
      JSON.stringify(data.metadata),
      data.timestamp
    ).run()

    return { received: true }
  }
)

Analyzing RUM Data

Querying by Metric

export const getRumDashboard = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    // Overall metrics for the last 7 days
    const overall = await context.env.DB.prepare(`
      SELECT
        name,
        COUNT(*) as samples,
        APPROX_PERCENTILE(value, 0.5) as p50,
        APPROX_PERCENTILE(value, 0.75) as p75,
        APPROX_PERCENTILE(value, 0.95) as p95,
        SUM(CASE WHEN rating = 'good' THEN 1 ELSE 0 END) * 100.0 / COUNT(*) as good_pct
      FROM rum_metrics
      WHERE created_at > datetime('now', '-7 days')
      GROUP BY name
    `).all()

    // Breakdown by pathname (top 10 slowest)
    const byPath = await context.env.DB.prepare(`
      SELECT
        pathname,
        APPROX_PERCENTILE(CASE WHEN name = 'LCP' THEN value END, 0.5) as lcp_p50,
        APPROX_PERCENTILE(CASE WHEN name = 'INP' THEN value END, 0.5) as inp_p50,
        COUNT(*) as pageviews
      FROM rum_metrics
      WHERE created_at > datetime('now', '-7 days')
      GROUP BY pathname
      ORDER BY lcp_p50 DESC
      LIMIT 20
    `).all()

    return { overall: overall.results, slowestPaths: byPath.results }
  }
)

RUM Dashboard

RUM Dashboard (Last 7 Days)

Web Vitals Overview:
┌────────┬──────────┬──────────┬──────────┬─────────┐
│ Metric │ P50      │ P75      │ P95      │ % Good  │
├────────┼──────────┼──────────┼──────────┼─────────┤
│ LCP    │ 1,200ms  │ 2,100ms  │ 4,500ms  │ 78%     │
│ CLS    │ 0.02     │ 0.05     │ 0.15     │ 85%     │
│ INP    │ 80ms     │ 150ms    │ 350ms    │ 82%     │
│ TTFB   │ 150ms    │ 350ms    │ 900ms    │ 88%     │
└────────┴──────────┴──────────┴──────────┴─────────┘

Performance by Geographic Region:
┌─────────────┬─────────┬──────────┬──────────────┐
│ Region      │ P50 LCP │ P95 LCP  │ Slow % (>3s) │
├─────────────┼─────────┼──────────┼──────────────┤
│ US East     │ 900ms   │ 2,100ms  │ 3%           │
│ US West     │ 1,100ms │ 2,800ms  │ 5%           │
│ Europe      │ 1,300ms │ 3,200ms  │ 8%           │
│ Asia Pacific│ 2,100ms │ 5,500ms  │ 20%          │
│ South America│ 2,400ms│ 6,000ms  │ 25%          │
└─────────────┴─────────┴──────────┴──────────────┘

Top 5 Slowest Pages:
1. /dashboard/analytics (p50 LCP: 4.2s) — heavy charts
2. /products/listing (p50 LCP: 3.8s) — large images
3. /reports/export (p50 LCP: 3.5s) — slow API

Alerts from RUM Data

export const checkRumAlerts = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const alerts = []

    // Alert if LCP good percentage drops below threshold
    const lcpQuality = await context.env.DB.prepare(`
      SELECT
        COUNT(*) as total,
        SUM(CASE WHEN rating = 'good' THEN 1 ELSE 0 END) * 100.0 / COUNT(*) as good_pct
      FROM rum_metrics
      WHERE name = 'LCP' AND created_at > datetime('now', '-1 hour')
    `).first()

    if (lcpQuality && Number(lcpQuality.good_pct) < 70) {
      alerts.push({
        type: "rum_degradation",
        metric: "LCP",
        goodPct: Math.round(Number(lcpQuality.good_pct)),
        threshold: 70,
        severity: "high",
      })
    }

    // Alert if any specific page has p95 LCP > 5s
    const slowPages = await context.env.DB.prepare(`
      SELECT pathname, COUNT(*) as views
      FROM rum_metrics
      WHERE name = 'LCP'
        AND value > 5000
        AND created_at > datetime('now', '-1 hour')
      GROUP BY pathname
      HAVING views > 10
      ORDER BY views DESC
      LIMIT 5
    `).all()

    if (slowPages.results.length > 0) {
      alerts.push({
        type: "slow_pages",
        pages: slowPages.results,
        severity: "medium",
      })
    }

    return alerts
  }
)

Using RUM to Drive Optimizations

RUM Signal	Investigation	Optimization
High LCP on mobile	Check hero image size	Serve AVIF, preload hero, reduce image size
High CLS on product page	Check dynamic content insertion	Reserve space, fix font swap layout shift
High INP on dashboard	Profile main thread activity	Break up long tasks, lazy load charts
Poor APAC LCP	Geographic latency issue	Edge caching, CDN optimization
Poor TTFB on auth pages	Auth middleware overhead	Optimize session lookup, cache auth state

RUM Data Schema

-- migrations/rum_metrics.sql
CREATE TABLE IF NOT EXISTS rum_metrics (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,         -- LCP, CLS, INP, TTFB, FCP
  value REAL NOT NULL,        -- Metric value in ms or score
  rating TEXT NOT NULL,       -- good, needs-improvement, poor
  pathname TEXT NOT NULL,     -- URL path
  device_type TEXT,           -- mobile, desktop, tablet
  connection_type TEXT,       -- 4g, 3g, 2g, slow-2g
  country TEXT,               -- Two-letter country code
  metadata TEXT,              -- JSON with attribution data
  created_at INTEGER NOT NULL
);

CREATE INDEX idx_rum_name ON rum_metrics(name);
CREATE INDEX idx_rum_created ON rum_metrics(created_at);
CREATE INDEX idx_rum_path ON rum_metrics(pathname);

RUM Implementation Checklist

[ ] Web Vitals library installed and initialized on all pages
[ ] RUM data sent via sendBeacon for reliable delivery
[ ] Server endpoint stores metrics in D1 or Analytics Engine
[ ] Sample rate configured (100% for initial setup, then reduce to 10-25%)
[ ] Dashboard built for p50/p75/p95 metrics
[ ] Geographic breakdown visible in dashboard
[ ] Pathname-level aggregation for slow page detection
[ ] Automated alerts for RUM degradation
[ ] Device type segmentation (mobile vs desktop)
[ ] Connection type tracking for network-aware optimization
[ ] Integration with CI pipeline — compare PR RUM vs production RUM
[ ] Historical data retention for trend analysis

Conclusion

Real User Monitoring bridges the gap between what you test in development and what your users experience in production. Without RUM, you are optimizing based on assumptions. With RUM, every optimization decision is backed by data from actual users.

The implementation is straightforward:

Collect Web Vitals from every page load
Store them in D1 or Analytics Engine
Build dashboards for visualization
Set alerts for degradation
Use the data to prioritize optimization work

For a production SaaS with RUM implemented across all pages, see tanstackship.com.

Related Resources

Holiday and Seasonal Promotions: A SaaS Discount Strategy That Works

sweet — Thu, 18 Jun 2026 01:37:00 +0000

Discounting is a double-edged sword for SaaS. Done well, holiday promotions can accelerate annual plan adoption, reactivate churned users, and drive seasonal spikes. Done poorly, they train users to wait for discounts and devalue your product. This guide covers a structured approach to holiday promotions — which holidays to target, what discount structures work, how to manage campaign timing, and the database infrastructure you need to run them. See production campaign management at tanstackship.com.

The SaaS Discounting Dilemma

Discount Strategy	Risk	Reward	Best For
20-30% off annual plans	Low (annual commitment offsets discount)	High	Black Friday, New Year
Free month	Medium (user may cancel after)	Medium	Trial conversion push
Lifetime discount (early adopter)	High (permanent revenue reduction)	Very high	Launch
2-for-1 annual	Medium	High	End-of-year push
First 3 months 50% off	Medium (churn after discount)	Medium	Q1 slumps

Key principle: Discount annual plans, not monthly. An annual discount locks in revenue for 12 months. A monthly discount creates churn risk when the promotional period ends.

Holiday Calendar by Market

Major SaaS Promotion Windows

Holiday	Date	Market	SaaS Opportunity
New Year / Q1 Push	Jan 1-31	Global	Annual plan adoption
Valentine's Day	Feb 14	US, EU	"Love your business" campaign
Spring Sale	March-April	Global	New year, new stack
Tax Season	April	US	Spending mindset
Summer Slump	June-August	Global	"Get ahead before fall"
Back to School	Sept	US, EU	Productivity push
Singles' Day (11.11)	Nov 11	China	Biggest shopping day globally
Black Friday / Cyber Monday	Nov-Dec	Global	The biggest SaaS promo window
Christmas / Year-End	Dec 15-31	Global	Last-chance annual deals

Campaign Structure

Campaign Database Schema

// D1 schema for campaign management
export const campaigns = sqliteTable("campaigns", {
  id: text("id").primaryKey(),
  name: text("name").notNull(),
  slug: text("slug").notNull().unique(),
  type: text("type", {
    enum: ["holiday", "seasonal", "launch", "retention", "reactivation"],
  }).notNull(),
  discountPercent: real("discount_percent").notNull(),
  discountType: text("discount_type", {
    enum: ["percentage", "fixed", "free_month", "tiered"],
  }).notNull(),
  appliesTo: text("applies_to", {
    enum: ["annual", "monthly", "all_plans", "specific_plans"],
  }).notNull(),
  specificPlans: text("specific_plans"), // JSON array of plan IDs
  startDate: integer("start_date", { mode: "timestamp" }).notNull(),
  endDate: integer("end_date", { mode: "timestamp" }).notNull(),
  maxRedemptions: integer("max_redemptions"),
  currentRedemptions: integer("current_redemptions").default(0),
  isActive: integer("is_active", { mode: "boolean" }).default(true),
  couponCode: text("coupon_code"),
  metadata: text("metadata"), // JSON for campaign assets
  createdAt: integer("created_at", { mode: "timestamp" }),
})

Creating a Campaign

// server/campaigns.ts
export const createCampaign = createServerFn({ method: "POST" }).handler(
  async ({ data, context }: { data: CreateCampaignInput }) => {
    const id = crypto.randomUUID()

    // Create Stripe coupon
    const coupon = await stripe.coupons.create({
      percent_off: data.discountPercent,
      duration: "once",
      max_redemptions: data.maxRedemptions,
      applies_to: {
        products: data.specificPlans.length > 0
          ? data.specificPlans
          : undefined,
      },
    })

    await context.env.DB.prepare(`
      INSERT INTO campaigns
        (id, name, slug, type, discount_percent, discount_type,
         applies_to, start_date, end_date, max_redemptions, coupon_code)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
    `).bind(
      id, data.name, data.slug, data.type,
      data.discountPercent, data.discountType,
      data.appliesTo, data.startDate.getTime(),
      data.endDate.getTime(), data.maxRedemptions,
      coupon.id
    ).run()

    return { id, couponId: coupon.id }
  }
)

Black Friday Campaign Example

Pre-Launch (2 Weeks Before)

// Prepare campaign assets and notifications
export const prepareCampaign = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const upcoming = await context.env.DB.prepare(`
      SELECT * FROM campaigns
      WHERE start_date > ? AND start_date < ?
      AND is_active = 1
    `).bind(Date.now(), Date.now() + 14 * 24 * 60 * 60 * 1000).all()

    for (const campaign of upcoming.results) {
      // Send announcement emails to subscribers
      await sendCampaignAnnouncement(campaign)

      // Update pricing page to show upcoming sale
      // Update in KV for zero-downtime
      await context.env.KV.put("campaign:upcoming", JSON.stringify({
        name: campaign.name,
        discountPercent: campaign.discount_percent,
        startDate: campaign.start_date,
        slug: campaign.slug,
      }))
    }

    return { prepared: true, count: upcoming.results.length }
  }
)

Live Campaign

// Apply discount during checkout
export const applyCampaignDiscount = createServerFn({ method: "POST" }).handler(
  async ({ data, context }: {
    data: { campaignSlug: string; priceId: string }
  }) => {
    const campaign = await context.env.DB.prepare(`
      SELECT * FROM campaigns
      WHERE slug = ? AND is_active = 1
      AND start_date <= ? AND end_date >= ?
    `).bind(data.campaignSlug, Date.now(), Date.now()).first()

    if (!campaign) {
      return { valid: false, error: "Campaign not active" }
    }

    // Check redemption limit
    if (campaign.max_redemptions && campaign.current_redemptions >= campaign.max_redemptions) {
      return { valid: false, error: "Campaign fully redeemed" }
    }

    // Increment counter
    await context.env.DB.prepare(`
      UPDATE campaigns SET current_redemptions = current_redemptions + 1
      WHERE id = ?
    `).bind(campaign.id).run()

    return {
      valid: true,
      couponCode: campaign.coupon_code,
      discountPercent: campaign.discount_percent,
    }
  }
)

Promotion Types: Which to Use

Type	Conversion Rate	Revenue Impact	Best Timing
% off annual	+30-50%	High (annual lock-in)	Black Friday, New Year
Free months	+20-30%	Medium	Launch, reactivation
Tiered discount	+25-40%	Medium-High	Extended periods
Limited time	+40-60%	High (urgent)	24-48 hour flash sales
BOGO (buy org, get 1 free)	+15-20%	Medium	Team/Org plans
Bundle discount	+20-25%	Medium	Feature add-ons

Percentage Off vs Free Months

Percentage off annual plan:
  Normal: $29/mo × 12 = $348/year
  With 30% off: $243.60/year (saves $104.40)
  ✅ User commits for 12 months
  ✅ You get cash upfront
  ✅ Lower churn risk

Free months on monthly plan:
  Normal: $29/mo × 12 = $348/year
  With 2 months free: $29/mo × 10 = $290/year (saves $58)
  ❌ User can cancel any time
  ❌ Revenue is deferred
  ❌ Higher churn risk

Winner: Percentage off annual plan

Analytics and Attribution

// Track campaign performance
export const getCampaignAnalytics = createServerFn({ method: "GET" }).handler(
  async ({ data, context }: { data: { campaignId: string } }) => {
    const [campaign, conversions, revenue] = await Promise.all([
      context.env.DB.prepare("SELECT * FROM campaigns WHERE id = ?")
        .bind(data.campaignId).first(),
      context.env.DB.prepare(`
        SELECT COUNT(*) as conversions, SUM(mrr) as total_mrr
        FROM subscriptions
        WHERE coupon_id = (SELECT coupon_code FROM campaigns WHERE id = ?)
        AND created_at BETWEEN
          (SELECT start_date FROM campaigns WHERE id = ?) AND
          (SELECT end_date FROM campaigns WHERE id = ?)
      `).bind(data.campaignId, data.campaignId, data.campaignId).first(),
      context.env.DB.prepare(`
        SELECT SUM(amount) as total_revenue
        FROM invoices
        WHERE subscription_id IN (
          SELECT id FROM subscriptions
          WHERE coupon_id = (SELECT coupon_code FROM campaigns WHERE id = ?)
        )
      `).bind(data.campaignId).first(),
    ])

    return { campaign, conversions, revenue }
  }
)

Anti-Discounting Patterns

Behavior	Problem	Solution
Always running a promotion	Users wait for discounts	Create clear promotion windows
Discounting monthly plans	High churn after promotion	Discount annual only
50%+ discounts	Devalues the product	Cap at 30-40%
No expiration	No urgency	Limited time only
Discounting core features	Trains users to value features less	Discount commitment, not features

Campaign Calendar Template

Q1 (Jan-Mar): New Year Annual Plan Push
  - "New Year, New Stack" — 25% off annual
  - Target: Free users on monthly, upgrade to annual

Q2 (Apr-Jun): Spring Refresh
  - "Spring Cleaning" — 20% off annual
  - Target: Inactive users reactivation

Q3 (Jul-Sep): Back to Business
  - "Back to School for Your Business" — 20% off team plans
  - Target: Team/org plan upgrades

Q4 (Oct-Dec): Black Friday + Year-End
  - Pre-BF: "Early Black Friday" — 30% off annual (limited quantity)
  - BF/CM: "Black Friday Deal" — 35% off annual
  - Year-End: "Last Chance 2026" — 25% off annual
  - Target: All segments, maximum conversion

Promotion Management Checklist

[ ] Campaign start/end dates set with proper timezone handling (UTC)
[ ] Stripe coupon created with redemption limits
[ ] Pricing page dynamically shows/hides promotional pricing
[ ] Email sequences ready: announcement, reminder, last chance, expired
[ ] UTM parameters set for all campaign links
[ ] Analytics dashboard tracking: impressions, clicks, conversions, revenue
[ ] Post-campaign retention analysis (do promo users retain at normal rates?)
[ ] Expired campaigns automatically hidden from checkout
[ ] Customer support briefed on campaign details
[ ] Refund policy adjusted for promotional purchases

Conclusion

Holiday promotions are a powerful growth lever for SaaS — when executed strategically. The key principles are:

Discount annual plans, not monthly — annual commitment protects your revenue
Cap discounts at 30-35% — higher discounts devalue the product
Create urgency — limited-time offers convert better than permanent discounts
Track everything — UTM, coupon codes, conversion analytics, retention rates
Plan a calendar — know your promotion windows months in advance

The campaign management infrastructure — database schema, Stripe integration, analytics tracking — should be built once and reused for every promotion. With the right infrastructure, a holiday campaign is a matter of configuration, not engineering.

For a SaaS with built-in campaign management, UTM tracking, and promotion infrastructure, see tanstackship.com.