Quote Calculator

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 → Pricing (or via environment constants).

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
• Loading/Unload time (mins): per stop or per job
• Minimum charge (£): floor price for any job
• Return mileage: include/exclude

Regional Surcharges

• London surcharge (£): e.g., 50.00
• ULEZ / Congestion: fixed amounts or pass-through (configurable)
• Zones/Exclusions: optional postcodes or polygons

Presentation

• Rounding: none / nearest £1 / £5
• VAT behaviour: include/exclude
• Discount codes: fixed/percent with start/end dates

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/Manager: can configure pricing, view logs, export quotes.
• Staff: can create quotes; cannot edit pricing.
• Customer (optional): can generate public indicative quotes (no internal costs shown).

User Flow

1. Enter destination postcode (and pickup if multi-leg).
2. Select vehicle/service type and any extras.
3. Click Calculate. A price with line items is shown.
4. Click Save Quote to store, or Convert to Booking.

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.

API / Endpoints

• UI file: quote-calculator.php
• AJAX endpoint: files/calculate-quote.php (POST)
• Geodata helper: files/fetch-postcode.php → returns lat/long from DB cache
• Optional REST: GET /api/quotes/price?from=...&to=...&vehicle=...

AJAX payload (example):

POST /files/calculate-quote.php
postcode=SW1A1AA&vehicle=van&crew=2&extras[]=stairs

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.

See Also

• Bookings Module
• Jobs Module
• Invoices Module
• Customer Access Module