Ecommerce Website Builder Module

Production-grade, multi-tenant online store module integrated with Biashara ERP inventory, POS, CRM, and Kenya payment rails.

Architecture

Subscription gating

• Module key: ecommerce_website
• Tier presets: enabled on retail_growth, retail_professional, retail_enterprise
• Add-on tier: ecommerce-website-addon (KES 50,000 setup + KES 2,500/month catalog default) — enable per tenant via Platform → Workspace → Online shop, or organizations.ecommerce_settings
• Bundled tenants: config/ecommerce.php → crena_included_slugs (e.g. Crena — no extra fee)
• Middleware: ecommerce.subscription, subscription.module:ecommerce_website
• Route map: config/subscription_route_modules.php (ecommerce, store prefixes)

Organization entitlement (ecommerce_settings JSON)

{
  "included": true,
  "addon_active": false,
  "addon_tier_slug": null,
  "setup_fee_paid_at": null,
  "custom_setup_fee": null,
  "custom_monthly_price": null,
  "pricing_notes": null
}

custom_setup_fee and custom_monthly_price override catalog defaults (config/ecommerce.php) when set by a platform super admin after assessing the tenant. Leave unset to bill catalog rates.

When included or addon_active is true, SubscriptionFeatures forces ecommerce_website => true regardless of base tier.

Staging preview (before custom domain)

Example (Crena on staging): /shop/crena-build-finish-ltd

Middleware: ecommerce.resolve → ResolveEcommerceStorefrontContext (runs before EnsureEcommerceStorefront).

Enable add-on for another tenant (platform super admin)

1. Sync catalogue so ecommerce-website-addon tier exists (Platform → Tiers → Sync).
2. Open Platform → Workspaces → {tenant} → Online shop (ecommerce):
   • Set entitlement to Add-on active
   • Optionally override setup/monthly fees and add internal assessment notes
   • Check Mark setup fee as paid when the one-time invoice is settled
3. Tenant opens /ecommerce → Activate store.

Catalog defaults: KES 50,000 setup + KES 2,500/month (config/ecommerce.php). Per-tenant overrides live in ecommerce_settings.custom_setup_fee / custom_monthly_price.

Tinker equivalent:

$org->ecommerce_settings = [
    'included' => false,
    'addon_active' => true,
    'addon_tier_slug' => 'ecommerce-website-addon',
    'custom_setup_fee' => 35000,      // optional — omit for catalog default
    'custom_monthly_price' => 2000,   // optional
    'pricing_notes' => 'Smaller catalog, shared theme',
    'setup_fee_paid_at' => now()->toIso8601String(),
];
$org->save();

Provision bundled tenant (CLI)

php artisan ecommerce:provision-tenant crena-build-finish-ltd --included --publish

Inventory sync

EcommerceInventorySyncService reads BranchInventory (same as POS). Online availability = on-hand minus active cart reservations.

• Product observer auto-syncs listings when ERP products change
• Paid orders deduct branch stock; mirrored into sales via PlaceEcommerceSaleService
• POS sales automatically reflect reduced online availability (shared stock rows)

Payments

Webhooks: POST /webhooks/ecommerce/mpesa/{organization} → ProcessEcommerceWebhookJob

Themes (2026)

Configured in config/ecommerce.php — 13 industry presets (fashion, electronics, pharmacy, etc.).

Super admin

Platform → Ecommerce: global enable, approvals, commission, AI toggle, tenant store list, theme marketplace.

Tenant workflow

1. Ensure tier includes ecommerce_website
2. Open /ecommerce → Activate store
3. Sync products from ERP catalog
4. Configure payments under /ecommerce/payments
5. Build pages under /ecommerce/builder
6. Storefront at {tenant}.domain/store

Supermarket theme pack (supermarket-grid)

Full retail theme with:

• Promo bar, mega-menu categories, aisle grid, flash countdown, trust badges
• Theme CSS: resources/css/themes/supermarket-grid.css
• Views: resources/views/storefront/themes/supermarket-grid/
• Auto-seeded home sections on activation or when switching theme in store settings

Set Theme → Supermarket Grid under /ecommerce/store, then open /store.

M-Pesa reconciliation

Tenant queue: /ecommerce/payments/reconciliation

• Query Daraja STK status (DarajaStkQueryService)
• Manual confirm with receipt code (reuses POS PosManualMpesaVerifier rules)
• Retry STK (max 3, configurable)
• Full audit trail in ecommerce_payment_reconciliation_events

Visual builder (drag-and-drop)

/ecommerce/builder — block palette, HTML5 drag reorder, inline inspector, device preview widths.

Block catalog: config/ecommerce_builder.php

Future-ready hooks

• ecommerce_analytics_events for GA4 / Meta CAPI
• API routes for Android/iOS apps
• AI features gated by config/ecommerce.ai
• GraphQL layer (add routes/graphql.php when needed)

Commands

php artisan migrate
php artisan test --filter=Ecommerce