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

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:

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