Medusa Stock Monitoring Plugin

A Medusa v2 plugin that monitors product inventory levels and sends email notifications to admins when:

1. Stock falls below a configured threshold (e.g., 10 units)
2. Stock reaches zero
3. Products have unchanged stock for a configured number of days (default: 90 days, slow-moving)

Features

• Low Stock Alerts: Notifies all admins when product stock falls below configured threshold
• Out of Stock Alerts: Notifies all admins when product stock reaches zero
• Slow-Moving Stock Alerts: Notifies all admins when products have unchanged stock for configured days (default: 90 days)
• Configurable Thresholds: Set global low stock threshold and slow-moving days threshold
• Automatic Admin Detection: Automatically queries and notifies all admin users from the user table
• Scheduled Monitoring: Daily automated stock checks via scheduled job
• Admin API: RESTful API with pagination, filtering, and search capabilities
• Production Ready: Proper logging, input validation, retry mechanism, and performance optimizations

Installation

1. Install the plugin:

   npm install stock-monitoring

   Or with yarn:

   yarn add stock-monitoring

2. Configure medusa-config.js:

   Add the plugin to your modules configuration in your Medusa project's medusa-config.js.

   module.exports = defineConfig({
     // ...
     modules: {
       stock_monitoring: {
         resolve: "stock-monitoring",
         options: {
           low_stock_threshold: 10, // Optional: default is 10
           slow_moving_days_threshold: 90, // Optional: default is 90 days
         },
       },
     },
     plugins: [
       {
         resolve: "stock-monitoring",
         options: {
           low_stock_threshold: 10, // Optional: default is 10
           slow_moving_days_threshold: 90, // Optional: default is 90 days
         },
       },
     ],
   })

3. Run Migrations:

   The plugin uses Medusa's existing inventory_item table for tracking stock changes, so no migrations are required. However, if you've already run migrations, you can skip this step.

   npx medusa db:migrate

   Note: The plugin automatically notifies all admin users from the user table. No additional configuration is needed.

Configuration

Default Settings

• Low Stock Threshold: 10 units (configurable via plugin options in medusa-config.js)
• Slow Moving Days Threshold: 90 days (configurable via plugin options in medusa-config.js)
• Schedule: Daily at midnight (0 0 * * *)
• Admin Notifications: All admin users from the user table are automatically notified

Configuration

Plugin Options are configured in medusa-config.js:

plugins: [
  {
    resolve: "stock-monitoring",
    options: {
      low_stock_threshold: 15, // Change low stock threshold here
      slow_moving_days_threshold: 120, // Change slow-moving threshold here (in days)
    },
  },
]

Admin Notifications: The plugin automatically queries all admin users from Medusa's user table and sends notifications to all of them. No additional configuration is needed.

API Reference

Get Current Alerts

GET /admin/stock-monitoring/alerts

Query Parameters:

• limit (optional): Number of alerts per page (default: 50, max: 200)
• offset (optional): Number of alerts to skip (default: 0)
• alert_type (optional): Filter by alert type (low_stock, out_of_stock, slow_moving)
• product_id (optional): Filter by product ID
• variant_id (optional): Filter by variant ID
• search (optional): Search by product or variant title (case-insensitive)

Examples:

# Get first page of alerts
GET /admin/stock-monitoring/alerts?limit=50&offset=0

# Filter by alert type
GET /admin/stock-monitoring/alerts?alert_type=out_of_stock

# Search for specific product
GET /admin/stock-monitoring/alerts?search=laptop

# Combine filters
GET /admin/stock-monitoring/alerts?alert_type=low_stock&limit=20&offset=0

Response:

{
  "alerts": [
    {
      "variant_id": "variant_123",
      "product_id": "prod_123",
      "product_title": "Product Name",
      "variant_title": "Variant Title",
      "current_quantity": 5,
      "alert_type": "low_stock",
      "threshold": 10
    },
    {
      "variant_id": "variant_456",
      "product_id": "prod_456",
      "product_title": "Another Product",
      "variant_title": "Default Variant",
      "current_quantity": 0,
      "alert_type": "out_of_stock"
    }
  ],
  "count": 2,
  "limit": 50,
  "offset": 0
}

How It Works

1. Scheduled Job: A daily scheduled job runs at midnight to check all product variants
2. Admin User Query: The job queries all admin users from Medusa's user table
3. Stock Level Query: The job queries all products and their variants, then checks inventory levels from inventory_item table
4. Alert Detection: The job identifies:
   • Variants with stock below threshold
   • Variants with zero stock
   • Variants with unchanged stock for configured days threshold (using inventory_item.updated_at timestamp)
5. Notification: When alerts are found, emails are sent to all admin users automatically
6. Slow-Moving Detection: Uses inventory_item.updated_at timestamp from Medusa's existing inventory tables - no separate history table needed

Alert Types

Low Stock

Triggered when a product variant's stock falls below the configured threshold.

Out of Stock

Triggered when a product variant's stock reaches zero.

Slow Moving

Triggered when a product variant's stock has remained unchanged for the configured number of days (default: 90 days). Uses inventory_item.updated_at timestamp from Medusa's inventory tables.

Requirements

• Medusa v2.11.2 or higher
• Notification service configured (e.g., SendGrid, SES)
• Inventory module enabled

Development

# Build the plugin
npm run build

# Watch mode for development
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm test:watch

# Run tests with coverage
npm test:coverage

Production Features

Logging

The plugin uses Medusa's logger service for structured logging. All log messages include contextual metadata for better debugging and monitoring.

Input Validation

Threshold values are validated on plugin initialization:

• Must be positive integers
• Clear error messages for invalid values
• Prevents misconfiguration issues

Retry Mechanism

Failed notifications are automatically retried up to 3 times with exponential backoff:

• Initial retry delay: 1 second
• Exponential backoff: 2s, 4s
• All retry attempts are logged

Performance Optimizations

• Batching: Products processed in batches of 100 for large catalogs
• Pagination: API supports pagination to handle large result sets
• Filtering: Efficient filtering by alert type, product, or variant
• Search: Fast search by product/variant title

Error Handling

• Graceful handling of missing admin users
• Error recovery for inventory query failures
• Comprehensive error logging with context

License

MIT