← Back to Documentation Home

Price Monitoring Cron API

Overview

The Price Monitoring Cron API is a scheduled Edge Function that automatically monitors product prices from competitor sources. It runs on a schedule (hourly) and orchestrates price checking through the Python backend.

Edge Function: price-monitoring-cron
Trigger: Scheduled (hourly) or manual invocation
Backend Service: Python API at /api/v1/price-monitoring/check-now

Architecture

Supabase Cron (hourly)
  ↓
Edge Function (price-monitoring-cron)
  ↓
Python Backend API (/api/v1/price-monitoring/check-now)
  ↓
CompetitorScraperService
  ├─→ Firecrawl API (scrape competitor pages)
  ├─→ CreditsIntegrationService (debit credits)
  ├─→ AICallLogger (log usage)
  ├─→ Database (save price history)
  └─→ PriceAlertService (check alerts)

Authentication

This is a cron job that requires a secret header for security:

X-Cron-Secret: <cron_secret>

The secret must match the CRON_SECRET environment variable.

Manual Invocation

While this function is designed to run on a schedule, it can be manually triggered:

Method: POST
Path: /

Headers:

X-Cron-Secret: <cron_secret>

Response:

{
  success: true,
  message: string,
  processed: number,      // Total products processed
  succeeded: number,      // Successfully monitored
  failed: number,         // Failed to monitor
  results: Array<{
    product_id: string,
    product_name: string,
    status: 'success' | 'failed',
    price_changes: number,
    alerts_triggered: number,
    error?: string
  }>
}

How It Works

1. Query Products Due for Monitoring

The function calls the database function get_products_due_for_monitoring() which returns products where:

2. Process Each Product

For each product, the function:

  1. Calls Python backend API: POST /api/v1/price-monitoring/check-now
  2. Python backend handles:
    • Scraping competitor pages via Firecrawl
    • Debiting credits via CreditsIntegrationService
    • Logging AI usage via AICallLogger
    • Saving price history to database
    • Creating price monitoring jobs
    • Checking and triggering price alerts

3. Update Next Check Time

After processing, the next_check_at is updated based on the monitoring frequency:

Monitoring Frequencies

Frequency Check Interval Use Case
hourly Every hour High-priority products
daily Every 24 hours Standard monitoring
weekly Every 7 days Low-priority products
monthly Every 30 days Occasional checks

Price Alerts

When price changes are detected, the system checks for active alerts:

Alert Types:

Alert Actions:

Database Tables

price_monitoring_jobs

Tracks each monitoring execution:

{
  id: string,
  product_id: string,
  status: 'pending' | 'processing' | 'completed' | 'failed',
  sources_checked: number,
  prices_found: number,
  credits_used: number,
  started_at: string,
  completed_at: string,
  error_message?: string
}

price_history

Stores historical price data:

{
  id: string,
  product_id: string,
  source_id: string,
  price: number,
  currency: string,
  availability: boolean,
  scraped_at: string,
  metadata: object
}

price_alerts

User-configured price alerts:

{
  id: string,
  user_id: string,
  product_id: string,
  alert_type: string,
  threshold_value: number,
  is_active: boolean,
  last_triggered_at?: string
}

Error Handling

{
  success: false,
  error: string,
  processed: number,
  succeeded: number,
  failed: number
}

Common Errors:

Monitoring & Logs

The function logs detailed information:

Related Documentation