Get Transfer Limits

OverviewCopy Anchor Link

Returns the current member's transfer limits including tier defaults, member-specific overrides, and current usage statistics. Use this endpoint to verify transfer limits before attempting transfers and to display available transfer capacity to users.

AuthenticationCopy Anchor Link

Requires a valid Clerk JWT token in the Authorization header.

curl -X GET "http://localhost:3000/v1/members/me/transfers/limits" \
  -H "Authorization: Bearer YOUR_CLERK_JWT"

ResponseCopy Anchor Link

{
  "perTransferMax": 50000,
  "dailyLimit": 100000,
  "monthlyLimit": 500000,
  "minimumTransfer": 100,
  "dailyUsed": 5000,
  "dailyRemaining": 95000,
  "monthlyUsed": 25000,
  "monthlyRemaining": 475000
}

Limit TypesCopy Anchor Link

Per Transfer MaximumCopy Anchor Link

• Purpose: Maximum points in a single transfer
• Typical Values: 50,000 - 100,000 points
• Use Case: Prevent large single transfers
• Override: Can be increased for VIP members

Daily LimitCopy Anchor Link

• Purpose: Maximum points transferred per calendar day
• Reset: Midnight UTC
• Typical Values: 100,000 - 250,000 points
• Cumulative: Includes all transfers (direct + pending)

Monthly LimitCopy Anchor Link

• Purpose: Maximum points transferred per calendar month
• Reset: First day of month at midnight UTC
• Typical Values: 500,000 - 1,000,000 points
• Rollover: No rollover of unused limits

Minimum TransferCopy Anchor Link

• Purpose: Smallest transfer amount allowed
• Typical Values: 50 - 100 points
• Reason: Prevent spam/abuse of small transfers

Tier-Based LimitsCopy Anchor Link

Standard TierCopy Anchor Link

{
  "perTransferMax": 50000,
  "dailyLimit": 100000,
  "monthlyLimit": 500000,
  "minimumTransfer": 100
}

Premium TierCopy Anchor Link

{
  "perTransferMax": 75000,
  "dailyLimit": 200000,
  "monthlyLimit": 750000,
  "minimumTransfer": 75
}

VIP TierCopy Anchor Link

{
  "perTransferMax": 100000,
  "dailyLimit": 250000,
  "monthlyLimit": 1000000,
  "minimumTransfer": 50
}

Usage CalculationsCopy Anchor Link

Daily UsageCopy Anchor Link

• Tracks: All transfers within current calendar day (UTC)
• Includes: Direct transfers + pending transfers created
• Resets: Daily at midnight UTC
• Calculation: dailyRemaining = dailyLimit - dailyUsed

Monthly UsageCopy Anchor Link

• Tracks: All transfers within current calendar month (UTC)
• Includes: Direct transfers + pending transfers created
• Resets: First day of month at midnight UTC
• Calculation: monthlyRemaining = monthlyLimit - monthlyUsed

Member OverridesCopy Anchor Link

Custom LimitsCopy Anchor Link

• VIP Members: May have higher limits
• Business Accounts: Custom enterprise limits
• Support Approved: Temporary limit increases
• Algorithm: effectiveLimit = max(tierDefault, memberOverride)

Temporary IncreasesCopy Anchor Link

• Duration: Usually 30-90 days
• Approval: Requires support ticket
• Use Cases: Special events, bulk gifting campaigns
• Monitoring: Increased fraud monitoring during override period

Use CasesCopy Anchor Link

Pre-Transfer ValidationCopy Anchor Link

const validateTransfer = async (amount: number) => {
  const response = await fetch('/api/members/me/transfers/limits');
  const limits = await response.json();
  
  const errors = [];
  
  if (amount < limits.minimumTransfer) {
    errors.push(`Minimum transfer is ${limits.minimumTransfer} points`);
  }
  
  if (amount > limits.perTransferMax) {
    errors.push(`Maximum per transfer is ${limits.perTransferMax} points`);
  }
  
  if (amount > limits.dailyRemaining) {
    errors.push(`Daily limit exceeded. ${limits.dailyRemaining} points remaining today`);
  }
  
  if (amount > limits.monthlyRemaining) {
    errors.push(`Monthly limit exceeded. ${limits.monthlyRemaining} points remaining this month`);
  }
  
  return {
    valid: errors.length === 0,
    errors,
    limits
  };
};

Display Transfer CapacityCopy Anchor Link

const displayTransferLimits = async () => {
  const response = await fetch('/api/members/me/transfers/limits');
  const limits = await response.json();
  
  const maxTransferToday = Math.min(
    limits.perTransferMax,
    limits.dailyRemaining,
    limits.monthlyRemaining
  );
  
  return {
    maxTransferToday,
    dailyProgress: (limits.dailyUsed / limits.dailyLimit) * 100,
    monthlyProgress: (limits.monthlyUsed / limits.monthlyLimit) * 100,
    resetTimes: {
      daily: getNextMidnightUTC(),
      monthly: getFirstOfNextMonthUTC()
    }
  };
};

Bulk Transfer PlanningCopy Anchor Link

const planBulkTransfers = async (recipients: number[], amount: number) => {
  const response = await fetch('/api/members/me/transfers/limits');
  const limits = await response.json();
  
  const totalAmount = recipients.length * amount;
  const maxTransfersToday = Math.floor(limits.dailyRemaining / amount);
  const maxTransfersThisMonth = Math.floor(limits.monthlyRemaining / amount);
  
  return {
    canTransferAll: totalAmount <= Math.min(limits.dailyRemaining, limits.monthlyRemaining),
    maxToday: Math.min(recipients.length, maxTransfersToday),
    maxThisMonth: Math.min(recipients.length, maxTransfersThisMonth),
    needsSpread: totalAmount > limits.dailyRemaining,
    daysRequired: Math.ceil(totalAmount / limits.dailyLimit)
  };
};

Performance NotesCopy Anchor Link

CachingCopy Anchor Link

• Server-side: Limits cached for 5 minutes
• Client-side: Safe to cache for 1-2 minutes
• Invalidation: Updated after each transfer

Real-time UpdatesCopy Anchor Link

• Usage Tracking: Updated immediately after transfers
• Limit Changes: Applied within 5 minutes
• Overrides: Applied immediately after approval

Monitoring & AlertsCopy Anchor Link

Near Limit WarningsCopy Anchor Link

const checkLimitWarnings = (limits) => {
  const warnings = [];
  
  if (limits.dailyRemaining < limits.dailyLimit * 0.1) {
    warnings.push('Approaching daily transfer limit');
  }
  
  if (limits.monthlyRemaining < limits.monthlyLimit * 0.1) {
    warnings.push('Approaching monthly transfer limit');
  }
  
  return warnings;
};

Usage AnalyticsCopy Anchor Link

• Daily Pattern: Track typical daily usage
• Monthly Trends: Monitor monthly transfer patterns
• Limit Utilization: Percentage of limits used
• Optimization: Suggest limit adjustments based on usage

Related EndpointsCopy Anchor Link

• Create Transfer - Use limits for transfer validation
• List Pending Transfers - View transfers that count toward limits
• Get Wallet Balance - Check available points for transfer