- Backend: FastAPI app with all models, services, schemas, routes - Admin Panel: Next.js dashboard with all modules (CRM, POS, repairs, warranties, billing, notifications, etc.) - Ecommerce: storefront (submodule) + product catalog - AI Agents: .agents/ skill library for Antigravity IDE - Docs: architecture, billing, notification gateway markdown - Submodules: Backend/OpenWA, Ecommerce/File 2/storefront
4.8 KiB
4.8 KiB
Dynamic Delivery Engine & Cash on Delivery (COD) Deprecation Policy
1. Overview & Policy Rationale
As part of the iFixKart Unified Commerce platform hardening:
- Cash on Delivery (COD) is Completely Deprecated & Forbidden:
- Cash on Delivery creates severe operational friction, high Return to Origin (RTO) expenses, and courier reconciliation overhead.
- All e-commerce purchases must be completed via secure online payment gateways (Razorpay: UPI, Credit/Debit Cards, Netbanking, Wallets) or zero-amount checkout covered completely by earned Store Credits.
- Any order creation request with
payment_method == "COD"is strictly blocked by the backend with an HTTP 400 Bad Request exception.
- Zero Hardcoded Static Free Delivery:
- Static "Free Delivery over ₹999" hardcoded banners and progress bars have been eliminated from all storefront components.
- Free delivery is disabled by default (
shipping_free_delivery_enabled = false). - Standard shipping charges (
shipping_delivery_charge = ₹99.0) apply to all orders by default. - Promotional Free Delivery can only be enabled dynamically through the Admin Settings panel (
/settings-> Delivery & Shipping blade).
2. Dynamic Settings Schema
Delivery rules are stored dynamically in the MySQL settings table as key-value pairs:
| Key | Default Value | Description |
|---|---|---|
shipping_delivery_charge |
99.0 |
Standard flat delivery fee applied when free delivery is not active or not qualified. |
shipping_free_delivery_enabled |
false |
Global toggle allowing promotional free shipping. When false, all orders incur standard delivery fee regardless of subtotal. |
shipping_free_delivery_min_order_amount |
999.0 |
Minimum order subtotal required to qualify for free shipping when shipping_free_delivery_enabled is set to true. |
3. Backend Architecture & Enforcement
3.1 Delivery Service (DeliveryService.py)
- Provides
get_delivery_settings(db)andupdate_delivery_settings(db, settings). - Core calculation engine:
def calculate_shipping_cost(db: Session, subtotal: float) -> float:
settings = get_delivery_settings(db)
if settings.get("free_delivery_enabled", False):
min_order = settings.get("free_delivery_min_order_amount", 999.0)
if subtotal >= min_order:
return 0.0
return float(settings.get("delivery_charge", 99.0))
3.2 Order Creation & Rejection (OrderService.py)
- Explicit COD rejection hook:
if payment_method and payment_method.strip().upper() == "COD":
raise HTTPException(
status_code=400,
detail="Cash on Delivery (COD) is not supported. Please complete your payment online using UPI, Card, Netbanking, or Store Credits."
)
- Shipping cost calculation is bound to
DeliveryService.calculate_shipping_cost(db, subtotal).
3.3 Dynamic Delivery API Endpoints (SettingsRouter.py)
GET /api/v1/settings/delivery(Public): Returns{ delivery_charge, free_delivery_enabled, free_delivery_min_order_amount }. Used by Storefront Cart, Drawer, and Checkout pages.PUT /api/v1/settings/delivery(Admin Authenticated): Allows store administrators to adjust charges, toggle free delivery, and update the qualifying threshold.
4. Admin Panel Settings Blade (/settings)
The Admin Dashboard provides a dedicated "Delivery & Shipping" tab under System Settings:
- Standard Delivery Charge (₹): Numeric input to configure the base delivery cost.
- Promotional Free Delivery Toggle: Switch to toggle free delivery availability.
- Free Delivery Minimum Threshold (₹): Active when the toggle is enabled to specify the minimum cart amount.
- Active Rule Simulator: Real-time display showing administrators how rules apply to orders below and above the threshold.
5. Storefront Frontend Dynamic Adaptation
5.1 Checkout Page (app/checkout/page.tsx)
- COD radio card and submission branch completely removed.
- Payment options strictly limited to Online Payment (Razorpay) or Zero-Amount checkout when Store Credits cover 100% of the total amount.
- Dynamically loads delivery settings on mount and computes shipping dynamically.
5.2 Cart Page (app/cart/page.tsx) & Cart Drawer (CartDrawer.tsx)
- Free shipping progress bar (
"Add ₹X more to get Free Delivery") is completely hidden unlessdeliverySettings.free_delivery_enabled === true. - When disabled, only the standard delivery fee is reflected in the breakdown with no static promises.
5.3 Static Text Cleanups
- Header TopBar: Updated from
"Free Shipping over ₹999!"to"Express Pan-India Delivery | 100% Genuine Spare Parts". - Features section: Changed from
"Free Shipping"to"Fast Express Delivery". - Trust Badges: Dynamically outputs
"Express Delivery"when free shipping is disabled.