AutoCom Docs

Products Module

The Products module provides a unified product catalog that works across all store integrations. Whether you're syncing from Shopify, WooCommerce, or managing products manually, the Products module maintains a consistent data model.

Overview

Products in Auto Commerce are designed to be:

  • Platform-agnostic: Work the same way regardless of source
  • Extensible: Support custom attributes from any module
  • Variant-aware: Handle product variants with different SKUs, prices, and inventory
  • Inventory-tracked: Real-time stock management with low-stock alerts

Data Model

Core Product Fields

id: UUID
external_id: string (from source platform)
source_module: string (e.g., 'store-shopify')
sku: string
name: string
description: text
price: decimal
compare_at_price: decimal
cost_price: decimal
track_inventory: boolean
stock_quantity: integer
low_stock_threshold: integer
status: 'active' | 'draft' | 'archived'

Product Variants

Products can have multiple variants (size, color, etc.):

variant_id: UUID
product_id: UUID
sku: string
name: string
price: decimal
stock_quantity: integer
options: JSON (e.g., {"size": "L", "color": "Blue"})

Dynamic Attributes

Modules can add custom attributes without modifying core schema:

product_id: UUID
attribute_key: string
attribute_value: string
module_source: string

Example attributes:

  • shopify_variant_id (from Shopify module)
  • hsn_code (from tax module)
  • weight (from shipping module)

API Endpoints

List Products

GET /api/v1/products

Query Parameters:

  • page: Page number (default: 1)
  • per_page: Items per page (default: 20)
  • search: Search by name or SKU
  • status: Filter by status (active, draft, archived)
  • source_module: Filter by source module

Response:

{
  "data": [
    {
      "id": "uuid",
      "sku": "TSHIRT-001",
      "name": "Premium Cotton T-Shirt",
      "price": 999.00,
      "stock_quantity": 50,
      "status": "active",
      "variants": [...]
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 5,
    "total_items": 100
  }
}

Get Product

GET /api/v1/products/{id}

Create Product

POST /api/v1/products

Request Body:

{
  "sku": "TSHIRT-001",
  "name": "Premium Cotton T-Shirt",
  "description": "High-quality 100% cotton t-shirt",
  "price": 999.00,
  "compare_at_price": 1299.00,
  "cost_price": 500.00,
  "track_inventory": true,
  "stock_quantity": 50,
  "low_stock_threshold": 10,
  "status": "active"
}

Update Product

PATCH /api/v1/products/{id}

Update Inventory

PATCH /api/v1/products/{id}/inventory

Request Body:

{
  "stock_quantity": 45,
  "adjustment_type": "set" // or "increment" or "decrement"
}

Product Sync

Products are automatically synced from enabled store modules:

From Shopify

  • Product created/updated in Shopify → Webhook triggers sync
  • Stock updates reflected in real-time
  • Product images synced automatically

From WooCommerce

  • Polling-based sync every 5 minutes
  • Manual sync available via API
  • Handles product variations

Inventory Management

Low Stock Alerts

When inventory falls below low_stock_threshold:

  • Event triggered: ProductLowStock
  • Notification sent to configured channels
  • Dashboard alert displayed

Stock Reservations

When an order is created:

  1. Stock is reserved (not yet deducted)
  2. On order confirmation → Stock deducted
  3. On order cancellation → Stock released

Module Integration

Extending Products

Other modules can extend products with custom data:

// In your module
ProductService::addAttribute($productId, 'custom_field', 'value', 'my-module');

Product Events

Listen to product events in your module:

Event::listen(ProductCreated::class, function ($event) {
    // Your module logic
});

Event::listen(ProductUpdated::class, function ($event) {
    // Your module logic
});

Event::listen(ProductLowStock::class, function ($event) {
    // Send notification, create purchase order, etc.
});

Best Practices

  1. Always use SKU: Ensure every product has a unique SKU for tracking
  2. Set inventory thresholds: Configure low stock alerts to prevent stockouts
  3. Use variants: For products with options, use variants instead of separate products
  4. Regular syncs: Keep product data in sync with source platforms
  5. Monitor stock levels: Set up alerts and dashboards to track inventory

Next Steps