Skip to main content
Fluxrate uses APScheduler to run background jobs that automate the billing lifecycle. These workers run automatically when the server starts and require no external infrastructure (no Redis, no Celery).

​
Worker Architecture

FastAPI Application (startup)
  └─► APScheduler
        ├─► Invoice Generator  (every hour at :00)
        └─► Invoice Finalizer  (every 5 minutes)

​
Workers

WorkerSchedulePurpose
Invoice GeneratorEvery hour at :00Create DRAFT invoices for due subscriptions
Invoice FinalizerEvery 5 minutesFinalize DRAFT invoices → OPEN, send emails
Startup CatchupOn server startProcess any missed invoices during downtime

​
Startup Behavior

When the server starts, it immediately runs the invoice generator to catch any subscriptions that became due while the server was offline. This ensures no billing gaps due to downtime.

​
Worker Monitoring

Check worker health: 
GET /api/v1/workers/health

{
  "timestamp": "2025-01-15T14:00:00Z",
  "scheduler": {
    "running": true,
    "jobs": [
      {
        "id": "invoice_generation",
        "next_run_time": "2025-01-15T15:00:00Z",
        "trigger": "cron[hour='*', minute='0']"
      },
      {
        "id": "invoice_finalization",
        "next_run_time": "2025-01-15T14:05:00Z",
        "trigger": "cron[minute='*/5']"
      }
    ]
  },
  "workers": {
    "invoice_generator": {
      "status": "healthy",
      "consecutive_failures": 0,
      "last_run": "2025-01-15T14:00:00Z"
    },
    "invoice_finalizer": {
      "status": "healthy",
      "consecutive_failures": 0,
      "last_run": "2025-01-15T14:00:00Z"
    }
  },
  "overall_status": "healthy"
}

​
Worker Status Values

StatusMeaning
healthyWorking normally
warning1-2 recent failures
critical3+ consecutive failures
staleNo runs in >2 hours
unknownNever run

Invoice Generation

How subscriptions are processed and invoices created

Invoice Finalization

How draft invoices become open and get emailed