ifixkart-admin/docs/billing/dynamic-delivery-and-cod-policy.md
Adithiyan bbd3a3e959 feat: initial commit — full platform snapshot
- 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
2026-10-13 12:59:47 +05:30

86 lines
4.8 KiB
Markdown

# 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.