AutoCom Docs

Products Module

The Products module provides a full-featured product management system including catalog management, categories, suppliers, purchase orders, collections, analytics, and import/export capabilities.

Overview

Products in AutoCom support:

  • Multi-type products: Physical, digital, and bundle products
  • Category hierarchy: Nested categories with tree view
  • Supplier management: Full vendor/supplier CRUD with purchase orders
  • Inventory tracking: Real-time stock management with low stock alerts
  • Approval workflow: Draft → Pending Review → Approved / Rejected
  • Multi-channel visibility: Control which channels see each product
  • Labels & badges: New, Featured, Sale, Bestseller
  • Product collections: Manual and automated groupings
  • Related products: Cross-sells, up-sells, and related products
  • Price history: Track all price changes over time
  • Activity log: Full audit trail of product changes
  • Import/Export: CSV-based bulk operations
  • Analytics: Best sellers, dead stock, category breakdown, inventory value
  • Catalog sync: Super admin can force products to resellers via ResellerCatalog

Navigation

Catalog & Inventory
├── Products          /catalog/products
├── Categories        /catalog/categories
├── Collections       /catalog/collections
├── Suppliers         /catalog/suppliers
├── Stock Management  /catalog/stock
├── Low Stock Alerts  /catalog/alerts
├── Purchase Orders   /catalog/purchase-orders
├── Analytics         /catalog/analytics
└── Import / Export   /catalog/import

Data Model

Product

Field Type Description
id UUID Primary key
sku string Stock keeping unit
name string Product name
description text Product description
price decimal Selling price
compare_at_price decimal Original/compare price
cost_price decimal Cost/purchase price
category_id UUID Category FK
supplier_id UUID Supplier FK
product_type enum physical / digital / bundle
status enum active / draft / archived
approval_status enum draft / pending_review / approved / rejected
track_inventory boolean Track stock levels
stock_quantity integer Current stock
low_stock_threshold integer Alert threshold
weight / dimensions decimal Shipping info
barcode / hsn_code string Identification
gst_rate decimal Tax rate (0, 5, 12, 18, 28)
labels jsonb Product badges
channel_visibility jsonb Visible channels
tags jsonb Product tags
meta_title / meta_description string SEO fields
slug string URL slug

Related Tables

  • categories: Nested tree with parent_id self-reference
  • product_variants: SKU, price, stock per variant + weight/dimensions
  • product_images: URL, alt text, position, optional variant_id
  • product_attributes: Key-value pairs from any module
  • product_bundles: Bundle components with quantity and discount
  • related_products: Related / cross-sell / up-sell links
  • product_collections: Manual and automated groupings
  • suppliers: Full vendor info with lead time and payment terms
  • purchase_orders: PO lifecycle with auto-inventory adjustment
  • product_activity_log: Audit trail
  • product_price_history: Price change tracking

API Endpoints

Products

Method Endpoint Description
GET /products List with filters
POST /products Create product
GET /products/{id} Get product detail
PATCH /products/{id} Update product
DELETE /products/{id} Delete product
GET /products/search?q= Search products
GET /products/low-stock Low stock products
GET /products/statistics Product statistics
PATCH /products/{id}/inventory Adjust inventory
POST /products/bulk/inventory Bulk adjust
GET /products/{id}/activity Activity log
GET /products/{id}/price-history Price history
POST /products/{id}/duplicate Duplicate product
POST /products/{id}/submit-review Submit for review
POST /products/{id}/approve Approve product
POST /products/{id}/reject Reject product

Bulk Operations

Method Endpoint Description
POST /products/bulk/status Bulk update status
POST /products/bulk/delete Bulk delete
POST /products/bulk/category Bulk assign category
POST /products/bulk/labels Bulk update labels
POST /products/bulk/channels Bulk update channels
POST /products/bulk/approval Bulk update approval

Categories

Method Endpoint Description
GET /categories List (supports tree view)
POST /categories Create category
GET /categories/{id} Get category
PATCH /categories/{id} Update category
DELETE /categories/{id} Delete category
POST /categories/reorder Reorder categories

Suppliers

Method Endpoint Description
GET /suppliers List suppliers
POST /suppliers Create supplier
GET /suppliers/{id} Get supplier
PATCH /suppliers/{id} Update supplier
DELETE /suppliers/{id} Delete supplier
GET /suppliers/{id}/products Supplier's products

Collections

Method Endpoint Description
GET /collections List collections
POST /collections Create collection
GET /collections/{id} Get collection
PATCH /collections/{id} Update collection
DELETE /collections/{id} Delete collection
POST /collections/{id}/products Add products
DELETE /collections/{id}/products Remove products

Purchase Orders

Method Endpoint Description
GET /purchase-orders List POs
POST /purchase-orders Create PO
GET /purchase-orders/{id} Get PO
PATCH /purchase-orders/{id} Update PO
DELETE /purchase-orders/{id} Delete PO
POST /purchase-orders/{id}/submit Submit PO
POST /purchase-orders/{id}/confirm Confirm PO
POST /purchase-orders/{id}/receive Receive items
POST /purchase-orders/{id}/cancel Cancel PO
GET /purchase-orders/suggestions Reorder suggestions

Analytics

Method Endpoint Description
GET /products/analytics/overview Overview stats
GET /products/analytics/best-sellers Top sellers
GET /products/analytics/dead-stock Dead stock
GET /products/analytics/categories Category breakdown
GET /products/analytics/inventory-value Inventory value
GET /products/analytics/price-changes Price change report

Import/Export

Method Endpoint Description
POST /products/import Upload CSV
GET /products/import/template Download template
POST /products/export Export products
GET /products/export/download/{file} Download export

Approval Workflow

Products support a 4-state approval workflow:

  1. Draft - Initial state, product not visible
  2. Pending Review - Submitted for review
  3. Approved - Approved by reviewer
  4. Rejected - Rejected with notes

Only draft or rejected products can be submitted for review. Reviewer ID and notes are tracked.

Catalog Products

Products with source_module = 'reseller-catalog' and external_id are synced from the master catalog. These products:

  • Cannot be deleted
  • Only status, labels, channels, and tags can be modified
  • Show a "Catalog Product" lock badge in the UI

Backend Services

The Products module uses a service-layer architecture. All business logic lives in services, not controllers.

Service Responsibility
ProductService Product CRUD, slug generation, image/variant/bundle sync, related products, statistics
InventoryService Stock adjustments, low-stock queries, bulk inventory updates, reorder suggestions
ProductActivityService Audit trail — logs create, update, status change, inventory adjustment, price change, approval actions
PriceHistoryService Records price/cost changes with old/new values, provides paginated history per product/variant
PurchaseOrderService PO creation, PO number generation, item receiving with auto-inventory adjustment
ProductAnalyticsService Overview stats, best sellers, dead stock, category breakdown, inventory value, price change reports
ProductImportService CSV parsing, row validation, bulk product creation via queue
ProductExportService Cursor-based CSV export with filters
CatalogSyncService Syncs mandatory master products to tenant DBs (in ResellerCatalog module)

Activity Logging

Every significant product action is automatically logged:

create    → "Product created"
update    → "Product updated" + changed fields
status    → "Status changed from draft to active"
inventory → "Inventory adjusted by +50 (restock)"
price     → "Price changed from ₹999 to ₹899"
approval  → "Submitted for review" / "Approved" / "Rejected: reason"

Logs are stored in product_activity_log with actor_id, action, description, and JSON changes.

Price History

Price changes are tracked in product_price_history for these fields:

  • price (selling price)
  • compare_at_price (compare/MRP)
  • cost_price (purchase cost)

Each record stores: product_id, variant_id (optional), field, old_value, new_value, changed_by, created_at.

Product Bundles

Bundle products (product_type = 'bundle') contain component products:

Bundle: "Audio Starter Kit" (₹4,999)
├── Wireless Headphones (qty: 1, 10% discount)
├── Portable Speaker (qty: 1, 5% discount)
└── Audio Cable (qty: 2, 0% discount)
Method Endpoint Description
GET /products/{id}/bundles Get bundle components
PUT /products/{id}/bundles Set bundle components
GET /products/{id}/bundle-price Calculate bundle price from components

Related Products

Products can be linked as related, cross-sell, or up-sell:

Method Endpoint Description
GET /products/{id}/related Get related products
PUT /products/{id}/related Set related products
GET /products/{id}/cross-sells Get cross-sell products
PUT /products/{id}/cross-sells Set cross-sell products
GET /products/{id}/up-sells Get up-sell products
PUT /products/{id}/up-sells Set up-sell products

Purchase Order Lifecycle

Purchase orders follow a state machine:

draft → submitted → confirmed → partially_received → received
                 └→ cancelled
  • Draft: PO created, items can be edited
  • Submitted: Sent to supplier, awaiting confirmation
  • Confirmed: Supplier confirmed, awaiting delivery
  • Partially Received: Some items received, inventory auto-adjusted
  • Received: All items received, PO complete
  • Cancelled: PO cancelled (only from submitted state)

When items are received via POST /purchase-orders/{id}/receive, product inventory is automatically adjusted upward by the received quantity.

Reorder Suggestions

GET /purchase-orders/suggestions returns products below their low_stock_threshold, grouped by supplier, with suggested order quantities.

Category Tree

Categories support unlimited nesting via parent_id self-reference.

  • GET /categories?tree=1 returns root categories with recursively nested children
  • POST /categories/reorder accepts [{ id, position, parent_id }] for drag-and-drop reordering
  • Deleting a category promotes its children to the parent level
  • Categories with assigned products cannot be deleted

Digital Products

Products with product_type = 'digital' support:

  • digital_file_url — download URL
  • digital_file_name — display filename
  • download_limit — max downloads per order (null = unlimited)

Labels & Channel Visibility

Labels (jsonb array): ["new", "featured", "sale", "bestseller"]

  • Used for filtering and badge display in the UI

Channel Visibility (jsonb array): ["manual", "shopify", "woocommerce", "storefront"]

  • Controls which sales channels can see/list the product

Frontend Hooks

Hook Description
useProducts() CRUD, filters, bulk ops, approval workflow
useProduct(id) Single product, activity, price history
useLowStockProducts() Low stock product list
useCategories() Category CRUD and tree
useSuppliers() Supplier CRUD
useCollections() Collection CRUD
usePurchaseOrders() PO lifecycle
useProductAnalytics() Analytics data
useProductImport() CSV import/export

Frontend Pages

Page Route Description
Products List /catalog/products Filterable table with stats cards, bulk actions, approval workflow
Product Create /catalog/products/new Multi-tab form: basic, pricing, inventory, images, variants, digital, SEO
Product Detail /catalog/products/[id] Tabbed view: overview, variants, images, bundle, related, activity, price history
Product Edit /catalog/products/[id]/edit Same form as create, pre-populated. Restricted editing for catalog products
Categories /catalog/categories Tree view with expand/collapse, inline create/edit/delete
Collections /catalog/collections Card grid with create/edit dialogs
Suppliers /catalog/suppliers Table with full CRUD dialog (16 fields)
Stock Management /catalog/stock Inventory table with quick +/- adjust and bulk adjust
Low Stock Alerts /catalog/alerts Urgency-sorted list with deficit column and quick PO creation
Purchase Orders /catalog/purchase-orders PO table with status filters and badges
PO Create /catalog/purchase-orders/new Supplier select, items table, auto-fill from suggestions
PO Detail /catalog/purchase-orders/[id] Order info, items with ordered vs received, receive dialog
Analytics /catalog/analytics Overview cards, best sellers, dead stock, category breakdown
Import/Export /catalog/import CSV upload with template download, export with filters

Next Steps