# Dynamic Delivery Engine & Cash on Delivery (COD) Deprecation Policy ## 1. Overview & Policy Rationale As part of the iFixKart Unified Commerce platform hardening: 1. **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. 2. **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)` and `update_delivery_settings(db, settings)`. - Core calculation engine: ```python 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: ```python 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 unless `deliverySettings.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.