Referral Rewards

Overview

The referral rewards system in TanStack Ship drives user growth by incentivizing existing users to invite new users to the platform. Built on a dual-reward model, both the referring user (inviter) and the newly invited user receive credit rewards upon successful conversion, creating a mutually beneficial growth loop that reduces customer acquisition costs.

As part of the platform, the referral rewards module integrates with the invitation system (tracking who invited whom), the credit system (dispensing rewards as spendable points), and the user dashboard (providing visibility into referral status and reward balances). The system processes rewards with idempotency guarantees, ensuring that each successful referral results in exactly one reward payout.

Design Flow

The referral rewards system automates the complete reward lifecycle, from event trigger through idempotent payout to audit logging:

Core Capabilities

Dual Reward Structure

When a new user signs up through a referral link, the system automatically disburses rewards to both parties:

This dual-incentive structure creates a powerful growth mechanism — existing users are motivated to share their referral links, while new users receive immediate value upon joining.

Client-side referral status example:

import { useQuery } from '@tanstack/react-query'

export function ReferralStatus() {
  const { data } = useQuery({
    queryKey: ['referral-stats'],
    queryFn: () =>
      fetch('/api/referrals/stats').then((r) => r.json()) as Promise<{
        totalRewardsEarned: number
        successfulReferrals: number
        pendingRewards: number
      }>,
  })

  return (
    <div className="rounded-lg border p-4">
      <h3 className="mb-3 font-semibold">Your Referral Rewards</h3>
      <dl className="grid grid-cols-3 gap-4">
        <div>
          <dt className="text-xs text-muted-foreground">Earned</dt>
          <dd className="text-xl font-bold">{data?.totalRewardsEarned ?? '—'}</dd>
        </div>
        <div>
          <dt className="text-xs text-muted-foreground">Referrals</dt>
          <dd className="text-xl font-bold">{data?.successfulReferrals ?? 0}</dd>
        </div>
        <div>
          <dt className="text-xs text-muted-foreground">Pending</dt>
          <dd className="text-xl font-bold">{data?.pendingRewards ?? 0}</dd>
        </div>
      </dl>
    </div>
  )
}

Configurable Reward Management

Administrators can configure reward parameters from the admin dashboard:

• Inviter Reward Amount — Set the number of credit points awarded to the referring user
• New User Welcome Amount — Configure the welcome bonus for newly invited users
• Reward Toggle — Enable or disable the reward system globally
• Payout History — View detailed transaction logs of all reward payouts
• Threshold Configuration — Optionally require the inviter to have an active subscription for rewards to apply

Idempotent Reward Processing

The reward system is designed with idempotency as a core reliability feature:

If a single referral is processed multiple times — whether due to retries, concurrency race conditions, or other scenarios — the system ensures the reward is paid exactly once. This is achieved through unique constraint enforcement on the referral-to-reward mapping, combined with transactional processing in the reward payout logic.

Transaction History and Audit Trail

All reward operations are documented in the transaction log, providing complete transparency:

• Reward amount and type classification (inviter reward vs. new user welcome)
• Associated referral record with inviter and invitee identifiers
• Processing timestamp with accurate chronological ordering
• Status tracking (pending, completed, failed) with failure reason capture

Design Philosophy

Dual-Incentive Growth Model

The referral rewards system is designed around a dual-incentive structure that rewards both the referrer and the referred user. This creates a powerful viral acquisition loop: existing users become brand advocates motivated by tangible credit rewards, while new users receive immediate value upon joining, increasing conversion rates from referral traffic. The configurable reward ratio allows platform operators to optimize the balance between acquisition cost and referral velocity based on their specific growth economics.

Idempotency-First Reliability

Every reward payout is protected by idempotency guarantees enforced at the database level through unique constraints on the referral-to-reward mapping. Whether a referral event is processed once or a hundred times due to webhook retries, concurrency race conditions, or system failures, the reward is paid exactly once. This idempotency-first approach is foundational to the system's reliability — it eliminates an entire class of payout bugs without requiring complex distributed locking or external coordination. Unlike ReferralCandy — which relies on external API idempotency with network dependencies — our reward processing uses database-level unique constraints within your own infrastructure, ensuring payout guarantees survive network partitions.

Configurable Reward Economics

Reward amounts, eligibility criteria, and payout conditions are fully configurable through the admin dashboard without code changes. This enables platform operators to run experiments — adjusting reward sizes, testing eligibility thresholds, or temporarily disabling rewards — and observe the impact on acquisition metrics in real-time. The system's transaction log provides the data needed to calculate cost-per-acquisition and return on investment for the referral program.

Best Practices

Optimal Reward Sizing

Set reward amounts that are meaningful enough to motivate sharing but sustainable for your unit economics. A common ratio is 2.5:1 between inviter and new user rewards (e.g., 500 credits for the inviter, 200 for the new user). Monitor the cost-per-acquisition through the attribution analytics dashboard and adjust accordingly.

Abuse Prevention

Implement eligibility requirements to prevent gaming the system. Common safeguards include requiring the inviter to have an active subscription or a minimum account age before rewards become payable.

Transparent Communication

Display clear referral reward terms to both inviters and invitees. The user dashboard should show the exact reward amounts, payout conditions, and current status of pending rewards.

Monitoring and Optimization

Track key referral metrics — referral conversion rate, average reward cost per acquired user, and referred user lifetime value. Use these metrics to optimize reward amounts and eligibility criteria.

Frequently Asked Questions

How does the referral reward system work? When an existing user shares their referral link and a new user signs up using that link, both parties receive credit rewards.

Can I change reward amounts after the system is live? Yes. Reward amounts are configurable from the admin dashboard. Changes take effect immediately for all future referrals.

What happens if a user tries to refer themselves? The system prevents self-referral through IP tracking and account validation. If a user attempts to use their own invitation code, the system rejects the referral.

How does idempotency prevent duplicate rewards? The system uses unique constraints on the combination of invitation ID and reward type. If the same referral event is processed twice, the second attempt fails the constraint check.

Can rewards be manually adjusted by administrators? Yes. Administrators can create manual credit transactions through the admin interface to adjust rewards if needed.

What reports are available for referral performance? The admin dashboard provides payout history, referral success rates, total rewards disbursed, and per-user referral statistics.

Configuration

Manage referral rewards from the admin dashboard. Configuration options include:

• Inviter reward amount (in credit points)
• New user welcome amount (in credit points)
• Global enable/disable toggle
• Eligibility requirements (subscription status, account age minimum)

Rewards are paid through the credit system, which must be active. No additional environment variables are required.

Integration Points

The referral rewards system integrates with these platform modules:

• Invitation System — Referral rewards are triggered when an invitation code is redeemed during registration
• Credit System — Rewards are paid out as credit points through the credit transaction system
• User Dashboard — Users track their referral status, pending and completed rewards
• Campaigns & Offers — Referral campaigns can be amplified with additional bonus offers
• Attribution Analytics — Referral-driven acquisitions are tracked as attributed conversions