AutoCom Docs

ResellerCatalog Module

The ResellerCatalog module provides master product management and cascading margin pricing for the multi-level reseller network.

Overview

This module handles:

  • Master Product Catalog - Super admin's central product repository
  • Cascading Pricing - Each level sets prices for their downstream resellers
  • Cost Visibility - Each reseller sees products at their cost
  • Margin Enforcement - Minimum margin requirements per product

Key Concepts

Master Products

Master products are created by the super admin and represent the source of truth for the product catalog:

// Master Product structure
[
    'id' => 'uuid',
    'owner_tenant_id' => 'super-admin-uuid',
    'sku' => 'PROD-001',
    'name' => 'Premium Widget',
    'description' => 'High-quality widget for all purposes',
    'base_cost' => 100.00,              // Absolute base cost
    'minimum_margin_percent' => 15,      // Minimum margin for resellers
    'recommended_retail_price' => 180,   // Suggested selling price
    'stock_quantity' => 500,
    'track_inventory' => true,
    'images' => ['url1', 'url2'],
    'attributes' => ['color' => 'blue', 'size' => 'large'],
    'status' => 'active',
]

Reseller Product Pricing

Each reseller has pricing set by their parent:

// Reseller Product Pricing structure
[
    'id' => 'uuid',
    'master_product_id' => 'product-uuid',
    'reseller_tenant_id' => 'reseller-uuid',     // Who this pricing is for
    'parent_tenant_id' => 'parent-uuid',          // Who set this pricing
    'cost_to_reseller' => 120.00,                 // What reseller pays
    'minimum_margin_percent' => 12,               // Min margin for sub-resellers
    'is_available' => true,
]

Cascading Price Calculator

The CascadingPriceCalculator service handles all pricing logic:

Calculate Cost for Reseller

use Modules\ResellerCatalog\App\Services\CascadingPriceCalculator;

$calculator = app(CascadingPriceCalculator::class);

// Get the cost for a specific reseller
$result = $calculator->calculateCostForReseller($masterProduct, $reseller);

// Returns:
[
    'cost' => 138.00,
    'breakdown' => [
        ['tenant_id' => 'super-admin', 'cost' => 100, 'margin' => 20, 'selling' => 120],
        ['tenant_id' => 'distributor', 'cost' => 120, 'margin' => 18, 'selling' => 138],
    ]
]

Set Pricing for Sub-Reseller

$calculator->setPricingForSubReseller(
    parentTenant: $distributor,
    subReseller: $retailer,
    product: $masterProduct,
    marginPercent: 15  // Distributor's margin
);

// Creates ResellerProductPricing record:
// - cost_to_reseller = distributor's cost + 15% = 138
// - parent_tenant_id = distributor
// - reseller_tenant_id = retailer

Get Available Products

// Get all products available to a reseller at their cost
$products = $calculator->getAvailableProducts($reseller);

// Returns collection with cost information:
[
    [
        'master_product' => MasterProduct,
        'cost' => 138.00,
        'minimum_margin' => 12,
        'suggested_price' => 155.00,
    ],
    // ...
]

API Endpoints

Master Products (Super Admin Only)

GET    /api/v1/reseller-catalog/master-products
POST   /api/v1/reseller-catalog/master-products
GET    /api/v1/reseller-catalog/master-products/{id}
PUT    /api/v1/reseller-catalog/master-products/{id}
DELETE /api/v1/reseller-catalog/master-products/{id}

My Catalog (Resellers)

GET    /api/v1/reseller-catalog/my-catalog
GET    /api/v1/reseller-catalog/my-catalog/{productId}

Pricing Management

GET    /api/v1/reseller-catalog/pricing
POST   /api/v1/reseller-catalog/pricing/set
GET    /api/v1/reseller-catalog/pricing/{productId}/breakdown

Example API Responses

List Master Products

GET /api/v1/reseller-catalog/master-products
Authorization: Bearer <token>
X-Tenant: super-admin-uuid

{
  "products": [
    {
      "id": "prod-uuid-1",
      "sku": "WIDGET-001",
      "name": "Premium Widget",
      "base_cost": 100.00,
      "minimum_margin_percent": 15,
      "recommended_retail_price": 180.00,
      "stock_quantity": 500,
      "status": "active",
      "resellers_count": 12,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 95
  }
}

Get My Catalog (Reseller View)

GET /api/v1/reseller-catalog/my-catalog
Authorization: Bearer <token>
X-Tenant: reseller-uuid

{
  "products": [
    {
      "id": "prod-uuid-1",
      "sku": "WIDGET-001",
      "name": "Premium Widget",
      "your_cost": 120.00,
      "minimum_margin_percent": 12,
      "suggested_selling_price": 138.00,
      "available_stock": 500,
      "is_available": true,
      "images": ["https://..."],
      "attributes": {
        "color": "blue",
        "size": "large"
      }
    }
  ]
}

Set Pricing for Sub-Reseller

POST /api/v1/reseller-catalog/pricing/set
Authorization: Bearer <token>
X-Tenant: distributor-uuid
Content-Type: application/json

{
  "product_id": "prod-uuid-1",
  "sub_reseller_id": "retailer-uuid",
  "margin_percent": 15,
  "is_available": true
}

{
  "message": "Pricing set successfully",
  "pricing": {
    "id": "pricing-uuid",
    "product_id": "prod-uuid-1",
    "reseller_id": "retailer-uuid",
    "cost_to_reseller": 138.00,
    "your_margin": 18.00,
    "margin_percent": 15
  }
}

Get Price Breakdown

GET /api/v1/reseller-catalog/pricing/prod-uuid-1/breakdown
Authorization: Bearer <token>
X-Tenant: retailer-uuid

{
  "product": {
    "id": "prod-uuid-1",
    "name": "Premium Widget",
    "base_cost": 100.00
  },
  "your_cost": 138.00,
  "breakdown": [
    {
      "level": 0,
      "tenant_name": "Super Admin",
      "cost": 100.00,
      "margin_percent": 20,
      "margin_amount": 20.00,
      "selling_price": 120.00
    },
    {
      "level": 1,
      "tenant_name": "Distributor ABC",
      "cost": 120.00,
      "margin_percent": 15,
      "margin_amount": 18.00,
      "selling_price": 138.00
    }
  ],
  "suggested_retail": 155.00,
  "minimum_margin_required": 12
}

Frontend Pages

Master Products Page (Super Admin)

Route: /reseller-catalog/master-products

Features:

  • Product list with search and filters
  • Create/edit product modal
  • Stock management
  • Bulk actions
  • Export to CSV

My Catalog Page (Reseller)

Route: /reseller-catalog/my-catalog

Features:

  • Products available at your cost
  • Suggested selling prices
  • Stock availability
  • Quick price calculator

Pricing Page

Route: /reseller-catalog/pricing

Features:

  • Set prices for sub-resellers
  • View pricing across your network
  • Margin analysis
  • Bulk pricing updates

Database Schema

master_products

CREATE TABLE master_products (
    id UUID PRIMARY KEY,
    owner_tenant_id VARCHAR(36) NOT NULL,
    sku VARCHAR(100) NOT NULL,
    name VARCHAR(255) NOT NULL,
    description TEXT,
    base_cost DECIMAL(14,2) NOT NULL,
    minimum_margin_percent DECIMAL(5,2) DEFAULT 0,
    recommended_retail_price DECIMAL(14,2),
    stock_quantity INTEGER DEFAULT 0,
    track_inventory BOOLEAN DEFAULT true,
    images JSONB DEFAULT '[]',
    attributes JSONB DEFAULT '{}',
    status VARCHAR(20) DEFAULT 'active',
    created_at TIMESTAMP,
    updated_at TIMESTAMP,

    UNIQUE(owner_tenant_id, sku)
);

reseller_product_pricing

CREATE TABLE reseller_product_pricing (
    id UUID PRIMARY KEY,
    master_product_id UUID NOT NULL REFERENCES master_products(id),
    reseller_tenant_id VARCHAR(36) NOT NULL,
    parent_tenant_id VARCHAR(36) NOT NULL,
    cost_to_reseller DECIMAL(14,2) NOT NULL,
    minimum_margin_percent DECIMAL(5,2) DEFAULT 0,
    is_available BOOLEAN DEFAULT true,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,

    UNIQUE(master_product_id, reseller_tenant_id)
);

CREATE INDEX idx_pricing_reseller ON reseller_product_pricing(reseller_tenant_id);
CREATE INDEX idx_pricing_parent ON reseller_product_pricing(parent_tenant_id);

Permissions

Permission Description
catalog.view View available products in catalog
catalog.manage_master Create and edit master products (super admin)
catalog.set_pricing Set pricing for sub-resellers
catalog.view_costs View cost breakdown and margins

Configuration

// config/reseller-catalog.php

return [
    // Default minimum margin for new products
    'default_minimum_margin' => 10,

    // Allow resellers to set zero margin
    'allow_zero_margin' => false,

    // Maximum chain depth for pricing
    'max_chain_depth' => 10,

    // Auto-create pricing for new sub-resellers
    'auto_inherit_pricing' => true,

    // Default markup for auto-pricing
    'default_auto_markup' => 15,
];

Events

The module dispatches these events:

Event When Fired
MasterProductCreated New master product created
MasterProductUpdated Master product modified
PricingSet Reseller pricing configured
StockUpdated Inventory quantity changed

Best Practices

Setting Margins

  1. Consider your costs - Include shipping, handling, and overhead
  2. Research competitors - Don't price yourself out of the market
  3. Leave room for sub-resellers - They need margin too
  4. Use minimum margins - Protect brand value

Managing Inventory

  1. Track at source - Super admin maintains master inventory
  2. Buffer stock - Reserve for unexpected demand
  3. Sync regularly - If using external inventory systems

Pricing Strategy

Base Cost:     ₹100
Super Admin:   +20% = ₹120 (sells to distributors)
Distributor:   +15% = ₹138 (sells to retailers)
Retailer:      +12% = ₹155 (sells to customers)

Next Steps