Quote Calculator Module

See the video below for a demo on how this module works and how to edit the calculation factors.

Summary

The Quote Calculator provides a highly accurate cost of delivery, in real time from a postcode. It combines distance, fuel, labour, and regional surcharges (e.g., London/ULEZ/C-Charge), and then produces a customer-facing price with transparent line items.

Audience

Admins: configure pricing, surcharges, and rules.
Staff: generate quick quotes for callers.
Customers: Self-serve accurate quotes via the website.

Capabilities

Distance-based pricing from depot to destination and return.
Cost model: fuel (mpg × diesel £/L), labour £/hr, base fee, per-mile, and regional surcharges.
All quotes requests are record in administration along with customer phone and email for easy follow up.

Configuration

All values below are configurable in Settings.

Core Cost Parameters

Depot postcode: e.g., CO64FH
Base fee (£): e.g., 25.00
Per-mile rate (£/mile): e.g., 1.10
Labour rate (£/hr): e.g., 17.50
Diesel price (£/L): e.g., 1.42
Vehicle MPG (UK): e.g., 38.0

Regional Surcharges

London surcharge (£): e.g., 50.00
ULEZ / Congestion: fixed amounts or pass-through (configurable)

Presentation

VAT behaviour: include/exclude
Discount codes: applied when creating an invoice

Price Formula (reference)

distance_miles   = route_distance(from=Depot, to=Postcode[, return=true|false])

fuel_litres      = (distance_miles / vehicle_mpg_uk) * 4.546
fuel_cost        = fuel_litres * diesel_price_per_litre

labour_hours     = ( (distance_miles / avg_mph) + (loading_minutes/60) ) * crew_count
labour_cost      = labour_hours * labour_rate_per_hour

mileage_cost     = distance_miles * per_mile_rate
surcharges_total = london_surcharge + ulez + congestion + extras

subtotal         = base_fee + mileage_cost + fuel_cost + labour_cost + surcharges_total
subtotal         = max(subtotal, minimum_charge)
price_rounded    = apply_rounding(subtotal)
final_price      = apply_vat(price_rounded)

Example (illustrative):

Depot CO6 4FH → SW1A 1AA (one-way 68 mi), MPG 38, Diesel £1.42/L
fuel_litres ≈ (68 / 38) * 4.546 = 8.13 L
fuel_cost   ≈ 8.13 * 1.42 = £11.55
mileage     = 68 * £1.10 = £74.80
labour      = 2.0 hrs * £17.50 = £35.00   (example)
surcharges  = London £50.00
subtotal    = base £25 + £74.80 + £11.55 + £35 + £50 = £196.35 → rounded to £195/£200 per rule

Permissions

Admin: can configure pricing, view logs, export quotes.
Manager: can view logs and export quotes.
Staff: can create quotes
Customer / visitors: can generate quotes.

User Flow

Enter destination postcode (no space e.g. CO43FH).
Click Calculate. A quotation is displayed along with a break down of the costs.
Quotation saved in administration.
Happy with quotation? Click here to Book the delivery.
Customer books the service.
Booking sent to administration.

Data Flow & Integration

On calculate: client sends form → calculate-quote.php → responds with JSON/HTML.
On convert: quote persisted to quotes table; booking record created in bookings.
Customer details are linked if supplied; invoices can be auto-generated after job completion.

Database

quotes (id, customer_id, from_pc, to_pc, miles, fuel_cost, labour_cost, surcharges, total, created_at)
quote_items (quote_id, label, amount)
postcode_cache (postcode, lat, lon, updated_at)
pricing_settings (key, value, updated_at)

Validation

UK postcode format (server + client).
Numeric bounds for miles, rates, and surcharges.
Permission checks on pricing endpoints (only Admin/Manager may change settings).
Rate limiting on public calculator to prevent abuse.

Caching & Performance

Postcode → lat/lon cached in postcode_cache (TTL configurable).
Distance calculation memoised for last N lookups.
Enable Preserve log in DevTools when debugging Network requests.
Consider CDN caching for static calculator assets.

Security

Server-side validation is mandatory (do not trust client values).
Never return internal cost breakdowns on public endpoints.
Sanitize all inputs; use prepared statements (PDO) everywhere.
Mask secrets in logs; never log full JWTs, cookies, or API keys.

Errors & Troubleshooting

“No price returned” → Check error_log, confirm pricing settings exist, and that fetch-postcode.php can reach the DB.
“0 miles” → Geodata not found; purge postcode cache and re-try.
“Feels slow” → Verify indices, reduce synchronous geocoding, and enable caching.
Provide a full report using How to Report an Issue (include Console + HAR).

Admin Tips

Review minimum charge and rounding quarterly.
Keep diesel price updated weekly.
Use discount codes sparingly; prefer fixed-price overrides for special jobs.
Add London/ULEZ/C-Charge as separate line items to keep audits clean.

FAQ

Can I include return mileage? Yes—toggle “Include return” in settings.
Do customers see line items? Public view shows simplified items; staff see full breakdown.
How do I change the base fee? Settings → Pricing → Base fee.
Why does my mileage seem high? Ensure route mode is “road network,” not straight-line; clear cache and retry.

Release Notes

v1.8.7 – UI polish, faster list rendering, clearer errors on failed POD upload; minor rounding fixes in PDFs (see Release Notes).

Roadmap

Multi-stop quotes, time-window pricing, multilingual UX.
Mobile app deep link: quote → booking on device.
A/B testing for price presentation.