Module: CommerceX / E-commerce (ecommerce / merchant)
Status: 🟢 Production verified (real orders + commission recorded) · Last validated: 2026-09-06 · Priority: P0 (Critical)
This is the reference/exemplar module — it demonstrates the full documentation depth every other module page should reach. It is validated againstclasss/CommerceOrdersModule.php,classs/ProductsModule.php,api/commerce/*, and the live schema.
Key-mapping note: this module is ecommerce in kv_module_control but merchants enroll under the merchant key in kv_module_registry. See ../../00-architecture/module-registry.md.
A. Purpose
Online marketplace: merchants list products; customers buy and pay (wallet-first, optional COD); Koovira routes fulfilment, takes commission, and settles the merchant. Revenue = 5% platform commission per order (platform_commission_settings), plus delivery/fees.
Ground-truth scale (2026-09-06): products_master = 24,761 products; orders_master = 13 orders; commission_transactions = 92 (cross-module); platform_commission_settings = 11 rules. Live commission has been processed for CommerceX (systemflow audit cited 15 processed txns ≈ ₹1,034) — verify current values before quoting.
B. Actors
- Customer / buyer — browses, carts, checks out, tracks, returns/reviews. (
buyer_id) - Merchant / seller — lists products, manages inventory, accepts & fulfils orders, settles.
(seller_id, company_id)
- Merchant staff — sub-user with scoped permissions (see ../../10-actors/README.md).
- Delivery/courier/hyperlocal partner — fulfilment (routing engine).
- Admin — commission config, disputes, refunds (padmin).
C. Entry points
Consumer: /ecomproductlist.php, /commercex.php, product detail pages, /mycart.php (checkout), /commerce_order_view_page (order view; assets/newjs/commerce_order_view_page.js). AJAX: api/commerce/cart.php (cart + checkout), api/v1/. Merchant: /merchant/ecommerce_products.php, _product_add/edit, ecommerce_inventory.php, orders.php, vieworder.php. External API: api/developer/products.php, api/developer/orders.php (token-scoped products. / orders.*).
D. Onboarding / preconditions
- Module
ecommerceactive inkv_module_control(it is:master_status=1). - Merchant enrolled (
merchanttype), company created (company_master), module setup done. - Selling gated by KYC/verification and membership per platform rules (validate the exact gate in
the merchant product-publish path when documenting section E publish feature).
- Buying requires only a logged-in
customer_masteruser with wallet balance (wallet-first) or an
allowed COD path.
E. Feature registry (prefix COM-)
Seeded here; maintain the master list in ../../STATUS.md.
| ID | Feature | Actor | Gate | Entry | Tables (write) | Code | Money | Status |
|---|---|---|---|---|---|---|---|---|
| COM-001 | Browse / product list | anon+customer | module on | ecomproductlist.php | — | ProductsModule | none | 🟢 |
| COM-002 | Product detail (buyer view) | anon+customer | published + seller active | product page | — | ProductsModule::getProductDetailForBuyer() | none | 🟢 |
| COM-003 | Add to cart | customer | login | mycart.php / api/commerce/cart.php | shopping_cart, cart_items(0) | api/commerce/cart.php | none | 🟡 (see data-model: cart storage) |
| COM-004 | Checkout with wallet | customer | login + balance | api/commerce/cart.php | orders_master, order_status_history, kv_order_finance_*, wallet_transactions, commission_transactions | CommerceOrdersModule::checkoutWithWallet() :563 | wallet debit + commission | 🟢 |
| COM-005 | Checkout COD | customer | allow_cod=1 | same | orders_master (payment_method='cod') | checkoutWithWallet() :597-609 | deferred | 🟡 (gated by admin flag) |
| COM-006 | Quick vs regular delivery | customer | quick needs lat/lng + eligible seller | checkout | orders_master.delivery_mode, commerce_order_routing | CommerceRoutingEngine | delivery fee | 🟡 (0 sellers opted into quick) |
| COM-007 | Vendor acceptance / routing | seller | vendor-acceptance enabled | checkout→accept | commerce_order_routing (8), order_status_history | CommerceRoutingEngine::getFulfillmentCandidates() | — | 🟢 |
| COM-008 | Delivery evidence + OTP + unboxing | buyer/courier | order dispatched | delivery links | order_delivery_*, order_unboxing_videos, order_parcel_custody | CommerceOrdersModule delivery-trust methods :203-393 | — | 🟢 |
| COM-009 | Cancel / return / refund | buyer/seller/admin | status + window | order view / padmin | orders_master (cancel/return/refund cols), kv_order_finance_entries | (refund path) | refund | 🟠 (validate refund writer) |
| COM-010 | Merchant product create/publish | seller/staff | KYC + membership + module | merchant/ecommerce_product_add.php | products_master, product_variants, seller_inventory | ProductsModule | — | 🟢 |
Rows above are validated where a code citation is given; those marked 🟠/🟡 name exactly what still needs confirmation. Fill the remaining flows into their own files under this folder.
Detailed pages
- data-model.md — tables, the "lines live on
orders_master" finding, ER. - wallet-checkout-flow.md — COM-004 end-to-end (the archetype flow).
- Money: ../../40-financial/central-finance-ledger.md.
Cross-module dependencies
CommerceX → Wallet (debit) → central finance ledger → Commission → Billing/Invoice → Notifications, and → Routing/Delivery (hyperlocal/courier) for fulfilment. A product's availability depends on the merchant's active/verified state (getProductDetailForBuyer(publicOnly=true)).
Change-impact (if you change checkout)
Touches money (wallet, finance ledger, commission), inventory (seller_inventory/ products_master.stock_quantity), routing, delivery-trust, and notifications. Re-test: wallet balance correctness, commission recorded once, finance-ledger keyed to the right module, the two money-integrity guards below still hold.
Money-integrity guards already in place (do not regress)
Both are in checkoutWithWallet() and were real production bugs:
- Server-side pricing only (
:692-748): variant/price come fromproduct_variants/ DB, never
from the client. A client items[0][variant_json]={"price":1} previously bought anything for ₹1.
publicOnlyavailability guard (:667-683): a product unpublished/paused, or whose company
was suspended after it was carted, cannot convert to a paid order.