Errand Dispatch Platform Development

Overview

After a user fills in pickup, delivery and item details (Part 1), the platform must return an accurate fee before payment. The pricing engine ties together map distance, configurable business rules and order attributes — all updatable from the admin panel without redeploying the mobile app.

Part 2 — Pricing Engine

Fee Formula

Delivery price is calculated per vehicle type. The formula implemented in the backend is:

1. Distance fee — Base fare + max(0, route km − included km) × per-km rate.
2. Weight fee — max(0, parcel kg − included kg) × per-kg rate.
3. Item-type surcharge — Flat amount from the selected goods item type (surchargeAmount in admin).
4. Subtotal — Distance fee + weight fee + item-type surcharge.
5. Final fee — Subtotal × night coefficient × special-date coefficient (both default to 1 when not applicable).

The mobile app shows this breakdown in the fee-help dialog so users understand what they are paying for.

Per-Vehicle Configuration

Each enabled vehicle type (motorcycle, e-bike, etc.) has its own fee profile in admin:

• Base fare, included km, per-km rate
• Included kg, per-kg rate for excess weight
• Max weight and max distance — orders exceeding these limits cannot use that vehicle
• Travel mode — DRIVING, BICYCLING or WALKING, passed to Google Directions for route distance
• Night period — Configurable start/end time and extra rate (e.g. +20%); applies when the order's appointment time falls in the night window

Special-Date Surcharge Rules

Separate from night pricing, admins can define special-date rules (e.g. public holidays) on the fee-surcharge page:

• Effective start/end datetime, surcharge rate (0–100%), priority and per-vehicle scope
• When the order appointment time hits a rule, its rate is applied as a multiplier on the subtotal
• If multiple rules overlap, the highest-priority rule wins

Route Distance

• Google Maps — Directions API returns road distance and a route polyline stored on the order.
• Fallback — When no map API key is configured, a deterministic address-hash estimate (1–25 km) keeps fee preview working in demo environments.

The home page recalculates the estimate whenever pickup, delivery, weight, vehicle or appointment time changes.

Admin Fee Configuration

Operators adjust pricing without redeploying the app:

• Fee config — Per-vehicle base/km/weight/night settings
• Goods categories & item types — Item classification and flat surcharges
• Special-date rules — Peak-period multipliers on the fee-surcharge page
• Operating areas — Geographic boundaries; out-of-area addresses are blocked before submit

FAQ

Can delivery fees be changed without redeploying the app?
Yes. Vehicle fee profiles, item-type surcharges and special-date rules are loaded at order time from the admin panel.

How is the final price calculated?
(Distance fee + weight fee + item-type surcharge) × night factor × special-date factor. Coupons apply on top at checkout.

Series Navigation

Part 1 — Customer Ordering · Part 2 — Pricing Engine · Part 3 — Payment & Wallet · Part 4 — Dispatch & Rider · Part 5 — Admin & Settlement · Part 6 — Deployment & Tech