Jump to content

Quote Calculator: Difference between revisions

From Logistack
Created page with "= 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/Managers:''' configure pricing, surcharges, and r..."
 
 
(19 intermediate revisions by the same user not shown)
Line 7: Line 7:


== Audience ==
== Audience ==
* '''Admins/Managers:''' configure pricing, surcharges, and rules.
* '''Admins:''' configure pricing, surcharges, and rules.
* '''Staff/Drivers:''' generate quick quotes for callers.
* '''Staff:''' generate quick quotes for callers.
* '''Customers:''' (optional) self-serve indicative quotes via the website.
* '''Customers:''' Self-serve accurate quotes via the website.


== Capabilities ==
== Capabilities ==
* Distance-based pricing from depot to destination (and optional return).
* Distance-based pricing from depot to destination and return.
* Cost model: fuel (mpg × diesel £/L), labour £/hr, base fee, per-mile, and regional surcharges.
* Cost model: fuel (mpg × diesel £/L), labour £/hr, base fee, per-mile, and regional surcharges.
* Optional extras: stairs, 2-person crew, fragile/marble handling, after-hours.
* All quotes requests are record in administration along with customer phone and email for easy follow up.
* Rounding rules (e.g., to nearest £1/£5), minimum/maximum caps, and discount codes.
* One-click convert quote → booking, with data carried through to Jobs/Invoices.


== Configuration ==
== Configuration ==
All values below are configurable in Settings → Pricing (or via environment constants).
All values below are configurable in Settings.


; Core Cost Parameters
=== Core Cost Parameters ===
* '''Depot postcode:''' e.g., <code>CO6 4FH</code>
 
* '''Depot postcode:''' e.g., <code>CO64FH</code>
* '''Base fee (£):''' e.g., <code>25.00</code>
* '''Base fee (£):''' e.g., <code>25.00</code>
* '''Per-mile rate (£/mile):''' e.g., <code>1.10</code>
* '''Per-mile rate (£/mile):''' e.g., <code>1.10</code>
Line 28: Line 27:
* '''Diesel price (£/L):''' e.g., <code>1.42</code>
* '''Diesel price (£/L):''' e.g., <code>1.42</code>
* '''Vehicle MPG (UK):''' e.g., <code>38.0</code>
* '''Vehicle MPG (UK):''' e.g., <code>38.0</code>
* '''Loading/Unload time (mins):''' per stop or per job
* '''Minimum charge (£):''' floor price for any job
* '''Return mileage:''' include/exclude


; Regional Surcharges
=== Regional Surcharges ===
 
* '''London surcharge (£):''' e.g., <code>50.00</code>
* '''London surcharge (£):''' e.g., <code>50.00</code>
* '''ULEZ / Congestion:''' fixed amounts or pass-through (configurable)
* '''ULEZ / Congestion:''' fixed amounts or pass-through (configurable)
* '''Zones/Exclusions:''' optional postcodes or polygons
* '''Dartford Crossing'''
* '''London Tunnels'''
 
=== Presentation ===


; Presentation
* '''Rounding:''' none / nearest £1 / £5
* '''VAT behaviour:''' include/exclude
* '''VAT behaviour:''' include/exclude
* '''Discount codes:''' fixed/percent with start/end dates
* '''Discount codes:''' applied when creating an invoice


== Price Formula (reference) ==
== Price Formula (reference) ==
Line 73: Line 71:


== Permissions ==
== Permissions ==
* '''Admin/Manager:''' can configure pricing, view logs, export quotes.
* '''Admin:''' can configure pricing, view logs, export quotes.
* '''Staff:''' can create quotes; cannot edit pricing.
* '''Manager:''' can view logs and export quotes.
* '''Customer (optional):''' can generate public indicative quotes (no internal costs shown).
* '''Staff:''' can create quotes
* '''Customer / visitors:''' can generate quotes.


== User Flow ==
== User Flow ==
# Enter destination postcode (and pickup if multi-leg).
# Enter destination postcode (no space e.g. CO43FH).
# Select vehicle/service type and any extras.
# Click '''Calculate'''. A quotation is displayed along with a break down of the costs.
# Click '''Calculate'''. A price with line items is shown.
# Quotation saved in administration.
# Click '''Save Quote''' to store, or '''Convert to Booking'''.
# Happy with quotation? Click here to Book the delivery.
# Customer books the service.
#Booking sent to administration.


== Data Flow & Integration ==
== Database ==
* On calculate: client sends form → <code>calculate-quote.php</code> → 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.


== API / Endpoints ==
All 2.8 million postcodes are included, from England, Scotland and Wales.
* '''UI file:''' <code>quote-calculator.php</code>
* '''AJAX endpoint:''' <code>files/calculate-quote.php</code> (POST)
* '''Geodata helper:''' <code>files/fetch-postcode.php</code> → returns lat/long from DB cache
* '''Optional REST:''' <code>GET /api/quotes/price?from=...&to=...&vehicle=...</code>
 
'''AJAX payload (example):'''
<pre>
POST /files/calculate-quote.php
postcode=SW1A1AA&vehicle=van&crew=2&extras[]=stairs
</pre>


== Database ==
The database, an .sql file, was incredibly difficult to refine to the point where it was possible to upload, its current size is 88MB, was reduced from an initial 1.2GB.
* '''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 ==
== Validation ==
* UK postcode format (server + client).
* UK postcode format (server + client).
* Numeric bounds for miles, rates, and surcharges.
* Numeric bounds for miles, rates, and surcharges.
* Permission checks on pricing endpoints (only Admin/Manager may change settings).
* Permission checks on pricing endpoints (only Admin may change settings).
* Rate limiting on public calculator to prevent abuse.
* Rate limiting on public calculator to prevent abuse.


Line 117: Line 101:
* Enable '''Preserve log''' in DevTools when debugging Network requests.
* Enable '''Preserve log''' in DevTools when debugging Network requests.
* Consider CDN caching for static calculator assets.
* 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 ==
== Errors & Troubleshooting ==
* '''“No price returned”''' → Check <code>error_log</code>, confirm pricing settings exist, and that <code>fetch-postcode.php</code> can reach the DB.
* '''“No price returned”''' Only 2 possibilities, 1. The user entered the postcode with a space, or a customization of the quote_calc_save.php file.
* '''“0 miles”''' → Geodata not found; purge postcode cache and re-try.
* '''“Feels slow”''' Because Google Routes plans the route using roads (not as the crow flies), destinations a long way from your depot will take longer to calculate, thus the quote takes longer to appear - this is normal.
* '''“Feels slow”''' → Verify indices, reduce synchronous geocoding, and enable caching.
* '''“Google Error message”''' Almost always due to adding the API Key incorrectly - the only fix is changing via the database (phpMyAdmin).
* Provide a full report using [[How to Report an Issue]] (include Console + HAR).
* Provide a full report using [[Troubleshooting|How to Report an Issue]].


== Admin Tips ==
== Admin Tips ==
Line 137: Line 115:


== FAQ ==
== FAQ ==
* '''Can I include return mileage?''' Yes—toggle “Include return” in settings.
* '''Can I include return mileage?''' Yes, the calculator is set up for the total journey distance - why would we only charge for half the journey?
* '''Do customers see line items?''' Public view shows simplified items; staff see full breakdown.
* '''Do customers see line items?''' Public view a full breakdown of the cost by default, this can be modified. Admin can see what's important (Name, Phone & email, postcode, distance and price.
* '''How do I change the base fee?''' Settings → Pricing → Base fee.
* '''How do I change the settings?''' Watch the video below for a full explanation.
* '''Why does my mileage seem high?''' Ensure route mode is “road network,” not straight-line; clear cache and retry.
* '''Why does the mileage seem high?''' The journey distance is for there and back.


== Release Notes ==
== Release Notes ==
Line 146: Line 124:


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


== See Also ==
A few additions in the pipeline, both UI and functionality improvements - see Logistack development [[Roadmap]] for more info.
* [[Bookings Module]]
 
* [[Jobs Module]]
== Video Guide ==
* [[Invoices Module]]
 
* [[Customer Access Module]]
Watch video full screen for better clarity, and hit the gear icon to set quality to 1080 HD.
 
<youtube>Uxe2vjdGYxM</youtube>

Latest revision as of 06:39, 14 October 2025

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)
  • Dartford Crossing
  • London Tunnels

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

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

Database

All 2.8 million postcodes are included, from England, Scotland and Wales.

The database, an .sql file, was incredibly difficult to refine to the point where it was possible to upload, its current size is 88MB, was reduced from an initial 1.2GB.

Validation

  • UK postcode format (server + client).
  • Numeric bounds for miles, rates, and surcharges.
  • Permission checks on pricing endpoints (only Admin 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.

Errors & Troubleshooting

  • “No price returned” Only 2 possibilities, 1. The user entered the postcode with a space, or a customization of the quote_calc_save.php file.
  • “Feels slow” Because Google Routes plans the route using roads (not as the crow flies), destinations a long way from your depot will take longer to calculate, thus the quote takes longer to appear - this is normal.
  • “Google Error message” Almost always due to adding the API Key incorrectly - the only fix is changing via the database (phpMyAdmin).
  • Provide a full report using How to Report an Issue.

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, the calculator is set up for the total journey distance - why would we only charge for half the journey?
  • Do customers see line items? Public view a full breakdown of the cost by default, this can be modified. Admin can see what's important (Name, Phone & email, postcode, distance and price.
  • How do I change the settings? Watch the video below for a full explanation.
  • Why does the mileage seem high? The journey distance is for there and back.

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

A few additions in the pipeline, both UI and functionality improvements - see Logistack development Roadmap for more info.

Video Guide

Watch video full screen for better clarity, and hit the gear icon to set quality to 1080 HD.

Retrieved from "https://wiki.logistack.co.uk/index.php?title=Quote_Calculator&oldid=184"