Cron Jobs - Despia Documentation

Why You Need Cron-Based Sync

The Problem with Webhooks Alone

Webhooks are the primary sync mechanism, but they can fail:

Failure Scenario	Impact	Probability
Network timeout during delivery	Webhook lost	Low (~1-2%)
Server downtime when webhook arrives	Webhook lost	Low (~0.5%)
Database transaction failure	Data not saved	Very Low (~0.1%)
Webhook processing bug	Incorrect sync	Low (~1%)
Cancellation webhook delay	2+ hour delay	High (100%)
RevenueCat retry exhausted	Permanent loss	Very Low (~0.01%)

Result: 1-3% of subscription changes may not sync immediately via webhooks.

The Solution: Defense in Depth

Layer 1: Webhooks (Primary)          ─── 97-99% coverage
Layer 2: Cron Sync (Backup)          ─── Catches remaining 1-3%
Layer 3: User-Triggered Sync         ─── On-demand verification

Combined reliability: 99.9%+ sync accuracy

Architecture Overview

Rate Limit Calculation

RevenueCat API Limits

Hard Limit: 480 requests per minute (8 requests per second)

Safe Operating Parameters

const RATE_LIMITS = {
  MAX_REQUESTS_PER_MINUTE: 480,
  SAFE_BUFFER: 0.7, // Use only 70% of limit (336 req/min)
  CRON_INTERVAL_MINUTES: 5,
  REQUESTS_PER_SECOND: 5.6, // 336 / 60 seconds
  MS_BETWEEN_REQUESTS: 179 // 1000ms / 5.6
};

// Calculate max users per cron run
const MAX_USERS_PER_RUN = Math.floor(
  RATE_LIMITS.MAX_REQUESTS_PER_MINUTE * 
  RATE_LIMITS.SAFE_BUFFER * 
  RATE_LIMITS.CRON_INTERVAL_MINUTES
);
// Result: 1,680 users per 5-minute run

Why 70% Buffer?

Other API usage: Your app makes real-time API calls
Webhook responses: RevenueCat may call your webhook handlers
Burst protection: Avoid hitting rate limit spikes
Multiple services: Other systems may use the same API key

Implementation

Core Sync Function

const REVENUECAT_API_KEY = process.env.REVENUECAT_API_KEY;
const REVENUECAT_PROJECT_ID = process.env.REVENUECAT_PROJECT_ID;

// Rate limit configuration
const RATE_LIMIT = {
  MAX_PER_MINUTE: 480,
  SAFE_BUFFER: 0.7,
  SAFE_REQUESTS_PER_MINUTE: 480 * 0.7, // 336
  MS_BETWEEN_REQUESTS: (60 * 1000) / (480 * 0.7), // ~179ms
  MAX_PER_5MIN_RUN: 336 * 5 // 1,680 users
};

/**
 * Main cron job function
 * Runs every 5 minutes
 */
async function syncSubscriptionsWithRevenueCat() {
  const startTime = Date.now();
  
  console.log(' Starting subscription sync job...');
  
  try {
    // Step 1: Get users to sync (prioritized)
    const usersToSync = await getUsersForSync(RATE_LIMIT.MAX_PER_5MIN_RUN);
    
    console.log(`Found ${usersToSync.length} users to sync`);
    
    // Step 2: Process in batches with rate limiting
    const results = {
      total: usersToSync.length,
      synced: 0,
      matched: 0,
      discrepancies: 0,
      errors: 0,
      notFound: 0
    };
    
    for (let i = 0; i < usersToSync.length; i++) {
      const user = usersToSync[i];
      
      try {
        // Fetch from RevenueCat V2
        const rcData = await fetchCustomerDataV2(
          user.app_user_id, 
          REVENUECAT_PROJECT_ID
        );
        
        if (!rcData) {
          results.notFound++;
          await logSyncResult(user.app_user_id, 'not_found');
          continue;
        }
        
        // Compare with database
        const hasDiscrepancy = await detectDiscrepancy(user, rcData);
        
        if (hasDiscrepancy) {
          // Sync database with RevenueCat
          await syncDatabaseWithRevenueCat(user.app_user_id, rcData);
          results.discrepancies++;
          results.synced++;
          
          console.log(` Synced ${user.app_user_id} - discrepancy found`);
          await logSyncResult(user.app_user_id, 'synced', hasDiscrepancy);
        } else {
          results.matched++;
          await logSyncResult(user.app_user_id, 'matched');
        }
        
      } catch (error) {
        results.errors++;
        console.error(` Error syncing ${user.app_user_id}:`, error.message);
        await logSyncError(user.app_user_id, error);
      }
      
      // Rate limiting: sleep between requests
      if (i < usersToSync.length - 1) {
        await sleep(RATE_LIMIT.MS_BETWEEN_REQUESTS);
      }
      
      // Progress logging every 100 users
      if ((i + 1) % 100 === 0) {
        console.log(`Progress: ${i + 1}/${usersToSync.length} users processed`);
      }
    }
    
    // Step 3: Log completion
    const duration = ((Date.now() - startTime) / 1000).toFixed(2);
    
    console.log(' Sync job completed', {
      duration: `${duration}s`,
      ...results,
      discrepancyRate: `${((results.discrepancies / results.total) * 100).toFixed(2)}%`
    });
    
    // Step 4: Alert if discrepancy rate is high
    const discrepancyRate = results.discrepancies / results.total;
    if (discrepancyRate > 0.05) {
      await sendAlert('High subscription discrepancy rate', {
        rate: `${(discrepancyRate * 100).toFixed(2)}%`,
        total: results.total,
        discrepancies: results.discrepancies
      });
    }
    
    // Step 5: Store metrics
    await storeSyncMetrics({
      timestamp: new Date(),
      duration_seconds: duration,
      ...results
    });
    
    return results;
    
  } catch (error) {
    console.error(' Sync job failed:', error);
    await sendAlert('Subscription sync job failed', { error: error.message });
    throw error;
  }
}

/**
 * Get users for sync - prioritized queue
 */
async function getUsersForSync(limit) {
  // Priority 1: Subscriptions expiring within 7 days
  const expiringUsers = await db.query(`
    SELECT app_user_id, is_active, expires_at, last_revenuecat_sync_at
    FROM user_subscriptions
    WHERE is_active = true
      AND expires_at IS NOT NULL
      AND expires_at BETWEEN NOW() AND NOW() + INTERVAL '7 days'
    ORDER BY expires_at ASC
    LIMIT $1
  `, [Math.floor(limit * 0.3)]); // 30% of quota
  
  // Priority 2: Billing issues
  const billingIssueUsers = await db.query(`
    SELECT app_user_id, is_active, expires_at, last_revenuecat_sync_at
    FROM user_subscriptions
    WHERE billing_issue = true
      AND is_active = true
    ORDER BY last_updated ASC
    LIMIT $1
  `, [Math.floor(limit * 0.2)]); // 20% of quota
  
  // Priority 3: Recently cancelled (within 48 hours)
  const recentlyCancelledUsers = await db.query(`
    SELECT app_user_id, is_active, expires_at, last_revenuecat_sync_at
    FROM user_subscriptions
    WHERE subscription_status = 'cancelled'
      AND cancelled_at > NOW() - INTERVAL '48 hours'
    ORDER BY cancelled_at DESC
    LIMIT $1
  `, [Math.floor(limit * 0.2)]); // 20% of quota
  
  // Priority 4: Stale cache (not synced in 24+ hours)
  const staleCacheUsers = await db.query(`
    SELECT app_user_id, is_active, expires_at, last_revenuecat_sync_at
    FROM user_subscriptions
    WHERE (last_revenuecat_sync_at IS NULL 
           OR last_revenuecat_sync_at < NOW() - INTERVAL '24 hours')
      AND is_active = true
    ORDER BY last_revenuecat_sync_at ASC NULLS FIRST
    LIMIT $1
  `, [Math.floor(limit * 0.2)]); // 20% of quota
  
  // Priority 5: Random sample of active users
  const randomUsers = await db.query(`
    SELECT app_user_id, is_active, expires_at, last_revenuecat_sync_at
    FROM user_subscriptions
    WHERE is_active = true
    ORDER BY RANDOM()
    LIMIT $1
  `, [Math.floor(limit * 0.1)]); // 10% of quota
  
  // Combine and deduplicate
  const allUsers = [
    ...expiringUsers.rows,
    ...billingIssueUsers.rows,
    ...recentlyCancelledUsers.rows,
    ...staleCacheUsers.rows,
    ...randomUsers.rows
  ];
  
  // Remove duplicates by app_user_id
  const uniqueUsers = Array.from(
    new Map(allUsers.map(user => [user.app_user_id, user])).values()
  );
  
  return uniqueUsers.slice(0, limit);
}

/**
 * Detect discrepancy between database and RevenueCat
 */
async function detectDiscrepancy(dbUser, rcData) {
  // Check if active status matches
  const dbIsActive = dbUser.is_active;
  const rcIsActive = rcData.active_entitlements?.items?.some(
    ent => ent.expires_at > Date.now()
  );
  
  if (dbIsActive !== rcIsActive) {
    return {
      type: 'active_status',
      db: dbIsActive,
      rc: rcIsActive
    };
  }
  
  // Check if entitlements match
  const dbEntitlements = dbUser.entitlements || {};
  const rcEntitlements = {};
  
  rcData.active_entitlements?.items?.forEach(ent => {
    if (ent.expires_at > Date.now()) {
      rcEntitlements[ent.entitlement_id] = ent.expires_at;
    }
  });
  
  const dbEntIds = Object.keys(dbEntitlements).sort();
  const rcEntIds = Object.keys(rcEntitlements).sort();
  
  if (JSON.stringify(dbEntIds) !== JSON.stringify(rcEntIds)) {
    return {
      type: 'entitlements',
      db: dbEntIds,
      rc: rcEntIds
    };
  }
  
  // Check if expiration dates match (within 1 minute tolerance)
  if (dbUser.expires_at && rcData.active_entitlements?.items?.length > 0) {
    const dbExpiresMs = new Date(dbUser.expires_at).getTime();
    const rcExpiresMs = Math.max(
      ...rcData.active_entitlements.items.map(ent => ent.expires_at)
    );
    
    const diffMs = Math.abs(dbExpiresMs - rcExpiresMs);
    if (diffMs > 60000) { // More than 1 minute difference
      return {
        type: 'expiration_date',
        db: new Date(dbExpiresMs).toISOString(),
        rc: new Date(rcExpiresMs).toISOString(),
        diff_minutes: (diffMs / 60000).toFixed(2)
      };
    }
  }
  
  return null; // No discrepancy
}

/**
 * Utility: Sleep function for rate limiting
 */
function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

/**
 * Log sync result to database
 */
async function logSyncResult(appUserId, status, discrepancy = null) {
  await db.query(`
    INSERT INTO sync_logs (
      app_user_id,
      status,
      discrepancy,
      synced_at
    ) VALUES ($1, $2, $3, NOW())
  `, [
    appUserId,
    status,
    discrepancy ? JSON.stringify(discrepancy) : null
  ]);
}

/**
 * Log sync error
 */
async function logSyncError(appUserId, error) {
  await db.query(`
    INSERT INTO sync_errors (
      app_user_id,
      error_message,
      error_stack,
      occurred_at
    ) VALUES ($1, $2, $3, NOW())
  `, [
    appUserId,
    error.message,
    error.stack
  ]);
}

/**
 * Store sync metrics for monitoring
 */
async function storeSyncMetrics(metrics) {
  await db.query(`
    INSERT INTO sync_metrics (
      timestamp,
      duration_seconds,
      total_users,
      synced_count,
      matched_count,
      discrepancies_count,
      errors_count,
      not_found_count,
      discrepancy_rate
    ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
  `, [
    metrics.timestamp,
    metrics.duration_seconds,
    metrics.total,
    metrics.synced,
    metrics.matched,
    metrics.discrepancies,
    metrics.errors,
    metrics.notFound,
    metrics.discrepancies / metrics.total
  ]);
}

/**
 * Send alert for critical issues
 */
async function sendAlert(title, details) {
  // TODO: Implement with your alerting system
  // Examples: Email, Slack, PagerDuty, etc.
  console.error(` ALERT: ${title}`, details);
  
  // Example Slack webhook:
  // await fetch(process.env.SLACK_WEBHOOK_URL, {
  //   method: 'POST',
  //   headers: { 'Content-Type': 'application/json' },
  //   body: JSON.stringify({
  //     text: ` ${title}`,
  //     attachments: [{ text: JSON.stringify(details, null, 2) }]
  //   })
  // });
}

module.exports = {
  syncSubscriptionsWithRevenueCat,
  getUsersForSync,
  detectDiscrepancy
};

Cron Schedule Configuration

Node.js with node-cron

const cron = require('node-cron');
const { syncSubscriptionsWithRevenueCat } = require('./sync-job');

// Run every 5 minutes
cron.schedule('*/5 * * * *', async () => {
  console.log(' Cron job triggered:', new Date().toISOString());
  
  try {
    await syncSubscriptionsWithRevenueCat();
  } catch (error) {
    console.error('Cron job failed:', error);
  }
});

console.log(' Cron job scheduled: Every 5 minutes');

System Crontab

# Edit crontab
crontab -e

# Add this line (runs every 5 minutes)
*/5 * * * * /usr/bin/node /path/to/your/app/sync-job.js >> /var/log/revenuecat-sync.log 2>&1

Vercel Cron (Next.js)

// vercel.json
{
  "crons": [
    {
      "path": "/api/cron/sync-subscriptions",
      "schedule": "*/5 * * * *"
    }
  ]
}

// pages/api/cron/sync-subscriptions.js
import { syncSubscriptionsWithRevenueCat } from '@/lib/sync-job';

export default async function handler(req, res) {
  // Verify cron secret
  if (req.headers.authorization !== `Bearer ${process.env.CRON_SECRET}`) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  
  try {
    const results = await syncSubscriptionsWithRevenueCat();
    return res.json({ success: true, results });
  } catch (error) {
    return res.status(500).json({ error: error.message });
  }
}

AWS Lambda with EventBridge

// handler.js
exports.handler = async (event) => {
  const { syncSubscriptionsWithRevenueCat } = require('./sync-job');
  
  try {
    const results = await syncSubscriptionsWithRevenueCat();
    
    return {
      statusCode: 200,
      body: JSON.stringify(results)
    };
  } catch (error) {
    console.error('Lambda sync failed:', error);
    
    return {
      statusCode: 500,
      body: JSON.stringify({ error: error.message })
    };
  }
};

// EventBridge rule (CloudFormation/Terraform)
// Rate: rate(5 minutes)

Database Schema

Sync Logs Table

CREATE TABLE sync_logs (
  id SERIAL PRIMARY KEY,
  app_user_id VARCHAR(255) NOT NULL,
  status VARCHAR(50) NOT NULL, -- matched, synced, not_found
  discrepancy JSONB,
  synced_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_sync_logs_user ON sync_logs(app_user_id);
CREATE INDEX idx_sync_logs_status ON sync_logs(status);
CREATE INDEX idx_sync_logs_synced_at ON sync_logs(synced_at);

Sync Errors Table

CREATE TABLE sync_errors (
  id SERIAL PRIMARY KEY,
  app_user_id VARCHAR(255) NOT NULL,
  error_message TEXT,
  error_stack TEXT,
  occurred_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_sync_errors_user ON sync_errors(app_user_id);
CREATE INDEX idx_sync_errors_occurred_at ON sync_errors(occurred_at);

Sync Metrics Table

CREATE TABLE sync_metrics (
  id SERIAL PRIMARY KEY,
  timestamp TIMESTAMP NOT NULL,
  duration_seconds DECIMAL(10, 2),
  total_users INTEGER,
  synced_count INTEGER,
  matched_count INTEGER,
  discrepancies_count INTEGER,
  errors_count INTEGER,
  not_found_count INTEGER,
  discrepancy_rate DECIMAL(5, 4)
);

CREATE INDEX idx_sync_metrics_timestamp ON sync_metrics(timestamp);

Monitoring and Alerts

Key Metrics to Track

async function getSyncHealthMetrics() {
  // Last 24 hours
  const metrics = await db.query(`
    SELECT 
      COUNT(*) as total_runs,
      AVG(duration_seconds) as avg_duration,
      SUM(total_users) as total_users_processed,
      SUM(discrepancies_count) as total_discrepancies,
      AVG(discrepancy_rate) as avg_discrepancy_rate,
      SUM(errors_count) as total_errors
    FROM sync_metrics
    WHERE timestamp > NOW() - INTERVAL '24 hours'
  `);
  
  return metrics.rows[0];
}

// Alert thresholds
const ALERT_THRESHOLDS = {
  DISCREPANCY_RATE: 0.05, // 5%
  ERROR_RATE: 0.02, // 2%
  DURATION_SECONDS: 240, // 4 minutes (should complete in < 5 min)
  CONSECUTIVE_FAILURES: 3
};

Health Check Endpoint

// GET /api/health/sync-job
async function handleSyncHealthCheck(req, res) {
  const metrics = await getSyncHealthMetrics();
  
  const health = {
    status: 'healthy',
    metrics,
    issues: []
  };
  
  // Check discrepancy rate
  if (metrics.avg_discrepancy_rate > ALERT_THRESHOLDS.DISCREPANCY_RATE) {
    health.status = 'warning';
    health.issues.push({
      severity: 'warning',
      message: 'High discrepancy rate detected',
      value: `${(metrics.avg_discrepancy_rate * 100).toFixed(2)}%`
    });
  }
  
  // Check error rate
  const errorRate = metrics.total_errors / metrics.total_users_processed;
  if (errorRate > ALERT_THRESHOLDS.ERROR_RATE) {
    health.status = 'warning';
    health.issues.push({
      severity: 'warning',
      message: 'High error rate detected',
      value: `${(errorRate * 100).toFixed(2)}%`
    });
  }
  
  // Check if job ran recently (within 10 minutes)
  const lastRun = await db.query(`
    SELECT timestamp 
    FROM sync_metrics 
    ORDER BY timestamp DESC 
    LIMIT 1
  `);
  
  if (lastRun.rows[0]) {
    const minutesSinceLastRun = 
      (Date.now() - new Date(lastRun.rows[0].timestamp).getTime()) / 60000;
    
    if (minutesSinceLastRun > 10) {
      health.status = 'unhealthy';
      health.issues.push({
        severity: 'critical',
        message: 'Sync job not running',
        value: `Last run: ${minutesSinceLastRun.toFixed(0)} minutes ago`
      });
    }
  }
  
  return res.json(health);
}

Best Practices

1. Gradual Rollout

Start with a small percentage of users:

// Phase 1: 10% of users
const limit = Math.floor(RATE_LIMIT.MAX_PER_5MIN_RUN * 0.1);

// Phase 2: 50% of users (after 1 week)
const limit = Math.floor(RATE_LIMIT.MAX_PER_5MIN_RUN * 0.5);

// Phase 3: 100% of users (after 2 weeks)
const limit = RATE_LIMIT.MAX_PER_5MIN_RUN;

2. Avoid Peak Hours

Skip sync during high-traffic periods:

function shouldSkipSync() {
  const hour = new Date().getUTCHours();
  
  // Skip 12pm-2pm UTC (peak usage)
  if (hour >= 12 && hour < 14) {
    console.log('  Skipping sync during peak hours');
    return true;
  }
  
  return false;
}

async function syncSubscriptionsWithRevenueCat() {
  if (shouldSkipSync()) {
    return { skipped: true, reason: 'peak_hours' };
  }
  
  // ... rest of sync logic
}

3. Circuit Breaker

Stop sync if too many errors occur:

const CIRCUIT_BREAKER = {
  MAX_CONSECUTIVE_ERRORS: 50,
  RESET_AFTER_MS: 5 * 60 * 1000 // 5 minutes
};

let consecutiveErrors = 0;
let circuitOpenedAt = null;

async function syncWithCircuitBreaker(user) {
  // Check if circuit is open
  if (circuitOpenedAt) {
    const timeSinceOpened = Date.now() - circuitOpenedAt;
    
    if (timeSinceOpened < CIRCUIT_BREAKER.RESET_AFTER_MS) {
      throw new Error('Circuit breaker open - too many errors');
    } else {
      // Reset circuit
      circuitOpenedAt = null;
      consecutiveErrors = 0;
    }
  }
  
  try {
    const result = await syncUser(user);
    consecutiveErrors = 0; // Reset on success
    return result;
  } catch (error) {
    consecutiveErrors++;
    
    if (consecutiveErrors >= CIRCUIT_BREAKER.MAX_CONSECUTIVE_ERRORS) {
      circuitOpenedAt = Date.now();
      await sendAlert('Circuit breaker opened', {
        consecutiveErrors,
        lastError: error.message
      });
    }
    
    throw error;
  }
}

4. Exponential Backoff for Rate Limits

async function fetchWithRetry(appUserId, projectId, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fetchCustomerDataV2(appUserId, projectId);
    } catch (error) {
      if (error.message.includes('429') || error.message.includes('rate limit')) {
        const backoffMs = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        console.warn(`Rate limited. Retrying in ${backoffMs}ms...`);
        await sleep(backoffMs);
      } else {
        throw error;
      }
    }
  }
  
  throw new Error('Max retries exceeded');
}

Performance Optimization

Batch Database Queries

// Instead of querying one by one
for (const user of users) {
  const dbUser = await db.query('SELECT * FROM user_subscriptions WHERE app_user_id = $1', [user.app_user_id]);
  // ...
}

// Batch query
const userIds = users.map(u => u.app_user_id);
const dbUsers = await db.query(`
  SELECT * FROM user_subscriptions 
  WHERE app_user_id = ANY($1)
`, [userIds]);

const dbUserMap = new Map(dbUsers.rows.map(u => [u.app_user_id, u]));

Parallel Processing (with rate limit)

const pLimit = require('p-limit');

// Limit to 6 concurrent requests (respects ~6 req/sec)
const limit = pLimit(6);

const promises = users.map(user => 
  limit(() => syncUser(user))
);

const results = await Promise.allSettled(promises);

Testing

Manual Test

// Test with single user
async function testSync(appUserId) {
  const user = await db.query(
    'SELECT * FROM user_subscriptions WHERE app_user_id = $1',
    [appUserId]
  );
  
  const rcData = await fetchCustomerDataV2(appUserId, REVENUECAT_PROJECT_ID);
  
  const discrepancy = await detectDiscrepancy(user.rows[0], rcData);
  
  console.log('Discrepancy:', discrepancy);
  
  if (discrepancy) {
    await syncDatabaseWithRevenueCat(appUserId, rcData);
    console.log('Synced!');
  }
}

testSync('user_abc123');

Integration Test

// Test full sync job with limited users
async function testSyncJob() {
  // Override limit for testing
  const originalLimit = RATE_LIMIT.MAX_PER_5MIN_RUN;
  RATE_LIMIT.MAX_PER_5MIN_RUN = 10; // Test with 10 users
  
  const results = await syncSubscriptionsWithRevenueCat();
  
  RATE_LIMIT.MAX_PER_5MIN_RUN = originalLimit;
  
  console.log('Test results:', results);
}

Troubleshooting

High Discrepancy Rate

Symptom: > 5% of syncs show discrepancies Possible Causes:

Webhooks not being processed
Database write failures
Race conditions in webhook handler

Solution:

// Check webhook processing rate
const webhookStats = await db.query(`
  SELECT 
    COUNT(*) as total,
    COUNT(CASE WHEN processed_at IS NOT NULL THEN 1 END) as processed
  FROM processed_webhook_events
  WHERE created_at > NOW() - INTERVAL '24 hours'
`);

const processingRate = webhookStats.rows[0].processed / webhookStats.rows[0].total;
console.log('Webhook processing rate:', `${(processingRate * 100).toFixed(2)}%`);

Job Taking Too Long

Symptom: Sync job runs longer than 5 minutes Solution: Reduce batch size or increase frequency

// Reduce to 70% capacity
const limit = Math.floor(RATE_LIMIT.MAX_PER_5MIN_RUN * 0.7);

API Rate Limit Errors

Symptom: Getting 429 errors from RevenueCat Solution: Increase sleep time between requests

RATE_LIMIT.MS_BETWEEN_REQUESTS = 250; // Slower (240 req/min)

Quick Reference

Sync Job Configuration

const CONFIG = {
  CRON_SCHEDULE: '*/5 * * * *', // Every 5 minutes
  BATCH_SIZE: 1680, // Users per run
  RATE_LIMIT: 336, // Requests per minute (70% of 480)
  MS_BETWEEN_REQUESTS: 179, // Milliseconds
  PRIORITY_WEIGHTS: {
    EXPIRING_SOON: 0.3, // 30%
    BILLING_ISSUES: 0.2, // 20%
    RECENTLY_CANCELLED: 0.2, // 20%
    STALE_CACHE: 0.2, // 20%
    RANDOM_SAMPLE: 0.1 // 10%
  }
};

Alert Thresholds

const ALERTS = {
  DISCREPANCY_RATE: 0.05, // > 5%
  ERROR_RATE: 0.02, // > 2%
  MAX_DURATION: 240, // > 4 minutes
  STALE_JOB: 10 // No run in 10 minutes
};

Priority Queue Logic

Expires within 7 days (30%) - Catch expiring subscriptions
Billing issues (20%) - Resolve payment problems
Recently cancelled (20%) - Detect un-cancellations
Stale cache 24h+ (20%) - Refresh old data
Random sample (10%) - General health check

Summary

Cron job runs every 5 minutes
Processes 1,680 users per run (respects 70% rate limit buffer)
Prioritizes critical users (expiring, billing issues, etc.)
Self-healing - catches webhook failures automatically
Rate-limited - 179ms between requests
Monitored - tracks discrepancy rates and errors
Alerting - notifies on high discrepancy/error rates Combined with webhooks: 99.9%+ sync reliability

Deployment

Local Server

Best Practices

Native Features

Lovable

​Why You Need Cron-Based Sync

​The Problem with Webhooks Alone

​The Solution: Defense in Depth

​Architecture Overview

​Rate Limit Calculation

​RevenueCat API Limits

​Safe Operating Parameters

​Why 70% Buffer?

​Implementation

​Core Sync Function

​Cron Schedule Configuration

​Node.js with node-cron

​System Crontab

​Vercel Cron (Next.js)

​AWS Lambda with EventBridge

​Database Schema

​Sync Logs Table

​Sync Errors Table

​Sync Metrics Table

​Monitoring and Alerts

​Key Metrics to Track

​Health Check Endpoint

​Best Practices

​1. Gradual Rollout

​2. Avoid Peak Hours

​3. Circuit Breaker

​4. Exponential Backoff for Rate Limits

​Performance Optimization

​Batch Database Queries

​Parallel Processing (with rate limit)

​Testing

​Manual Test

​Integration Test

​Troubleshooting

​High Discrepancy Rate

​Job Taking Too Long

​API Rate Limit Errors

​Quick Reference

​Sync Job Configuration

​Alert Thresholds

​Priority Queue Logic

​Summary

Why You Need Cron-Based Sync

The Problem with Webhooks Alone

The Solution: Defense in Depth

Architecture Overview

Rate Limit Calculation

RevenueCat API Limits

Safe Operating Parameters

Why 70% Buffer?

Implementation

Core Sync Function

Cron Schedule Configuration

Node.js with node-cron

System Crontab

Vercel Cron (Next.js)

AWS Lambda with EventBridge

Database Schema

Sync Logs Table

Sync Errors Table

Sync Metrics Table

Monitoring and Alerts

Key Metrics to Track

Health Check Endpoint

Best Practices

1. Gradual Rollout

2. Avoid Peak Hours

3. Circuit Breaker

4. Exponential Backoff for Rate Limits

Performance Optimization

Batch Database Queries

Parallel Processing (with rate limit)

Testing

Manual Test

Integration Test

Troubleshooting

High Discrepancy Rate

Job Taking Too Long

API Rate Limit Errors

Quick Reference

Sync Job Configuration

Alert Thresholds

Priority Queue Logic

Summary