Full Request Example

{
"order": {
"name": "Aggregate Delivery — London",   // optional
"number": "ORD-2026-00142",              // optional
"hazardous_goods": null,                 // optional  enum: explosive | gas | flammable | combustible | oxidizer | poison | radioactive | corrosive | other
"tunnel_category": null,                 // optional  enum: B | C | D | E
"toll_transponder": null,                // optional  enum: prepay | cash | none
"sections": [
{
// ── Origin (plant) ──────────────────────────────────────────
"origin": {
"type": "plant",                   // required  enum: plant | customer | depot
"lat": 37.7879,                    // required — Bay Bridge approach (SF Embarcadero)
"lng": -122.3964,                  // required
// Plant-level handling costs
"loading_cost_value": 45.00,       // optional — cost per hour (or flat)
"loading_cost_calc_method": "per_h",  // optional  enum: per_h | per_t | per_m3 | flat | included
"in_facility_time_minutes": 20,    // optional — gate / admin time at plant
// Additional fees
"fees": [                          // optional
{
"fee_name": "gate_fee",        // optional — label shown in breakdown
"calc_method": "flat_per_trip",// optional  enum: per_t | per_m3 | per_cu_yd | per_km | per_mi | flat_per_trip | flat_per_section | flat_per_order | none
"value": 12.50                 // optional — fee amount
},
{
"fee_name": "scale_ticket_fee",// optional — label shown in breakdown
"calc_method": "flat_per_trip",// optional  enum: per_t | per_m3 | per_cu_yd | per_km | per_mi | flat_per_trip | flat_per_section | flat_per_order | none
"value": 4.00                  // optional — fee amount
}
]
},
// ── Destination (non-facility drop point) ───────────────────
"destination": {
"type": null,                      // optional — enum: plant | null (null = non-facility location)
"lat": 37.8044,                    // required
"lng": -122.2712,                  // required
// Plant-level handling costs at destination
"unloading_cost_value": 38.00,        // optional — cost per hour (or flat)
"unloading_cost_calc_method": "per_h",// optional  enum: per_h | per_t | per_m3 | flat | included
"in_facility_time_minutes": 15,       // optional
// Additional fees
"fees": [                             // optional
{
"fee_name": "release_fee",        // optional — label shown in breakdown
"calc_method": "flat_per_trip",   // optional  enum: per_t | per_m3 | per_cu_yd | per_km | per_mi | flat_per_trip | flat_per_section | flat_per_order | none
"value": 8.00                     // optional — fee amount
},
{
"fee_name": "document_fee",       // optional — label shown in breakdown
"calc_method": "flat_per_trip",   // optional  enum: per_t | per_m3 | per_cu_yd | per_km | per_mi | flat_per_trip | flat_per_section | flat_per_order | none
"value": 6.50                     // optional — fee amount
}
]
},
// ── Transport (truck) ────────────────────────────────────────
"transport": {
"name": "Volvo FH 6x4",              // optional — label only
"type": "truck",                     // optional  enum: truck | van | rail | other
"max_load_weight_value": 28,       // required — payload capacity in weight
"max_load_weight_uom": "t",        // required  enum: t
"max_load_volume_value": 60,       // required — payload capacity in volume
"max_load_volume_uom": "m3",       // required when max_load_volume_value is set  enum: m3 | cu_yd
// Dimensions — forwarded to HERE routing
"height_m": 4.0,                   // required
"length_m": 16.5,                  // required
"width_m": 2.55,                   // required
"truck_weight_t": 44,              // required — empty/unladen truck weight in tonnes
"weight_t": 72,                    // required — gross vehicle weight (truck + max payload) in tonnes
"axle_count": 5,                   // required
"trailer_count": 1,                // optional
// Fuel & emissions
"fuel_type": "diesel",             // required  enum: diesel | petrol | electric | hydrogen | lng | cng
"registration_country": "GB",      // optional  ISO-3166-1 alpha-2
// Movement cost method — two-level cascade:
//   transport.calc_method ?? order_item.product_line_calc_method ?? "time"
"calc_method": "distance",             // optional — transport override; null = inherit from product line
"cost_per_distance_loaded": 2.85,  // required if resolved calc_method = distance
"cost_per_distance_loaded_uom": "km", // required if calc_method = distance  enum: km | mi
"cost_per_distance_empty":          1.20,
"cost_per_distance_empty_uom": "km",  // required if calc_method = distance  enum: km | mi
"cost_per_h_loaded": null,         // required if calc_method = time
"cost_per_h_empty": null,          // required if calc_method = time
// Fuel consumption (drives fuel cost calculation)
"fuel_consumption_loaded": 32,                  // optional
"fuel_consumption_loaded_uom": "l_per_100km", // optional  enum: l_per_100km | mpg
"fuel_consumption_empty": 24,                 // optional
"fuel_consumption_empty_uom": "l_per_100km",  // optional  enum: l_per_100km | mpg
"fuel_price_value": 1.65,                     // optional — override system price (USD)
"fuel_price_uom": "usd_per_l",                // optional  enum: usd_per_l | usd_per_gal
"small_load_limit_value": 20,              // optional
"small_load_limit_type": "t",              // optional  enum: t | m3 | cu_yd | pct
"small_load_surcharge_value": 95.00        // optional
},
// ── Order items ──────────────────────────────────────────────
// Multiple items on the same section are automatically split into
// separate sections (one per item) before calculating — you do NOT
// need to duplicate origin/destination/transport for each product.
"order_items": [
{
"name": "Asphalt",                  // optional — label
"quantity_value": 500,              // required
"quantity_uom": "t",                // required  enum: t | m3 | cu_yd  (multipliers looked up automatically)
"product_line": "asphalt",          // optional — slug from product_lines; enables density-based t↔volume conversion
"product_line_calc_method": "distance", // optional — product line default; used when transport.calc_method is null
"loading_rate_per_h": 150,          // optional — UOM/h (e.g. t/h when quantity_uom = "t")
"unloading_rate_per_h": 120         // optional
},
{
"name": "Aggregates",               // second product on same route — will become a separate section
"quantity_value": 1000,
"quantity_uom": "m3",               // volume UOM — density injected from product_line when present
"product_line": "aggregates",       // optional — routes server will inject density_t_per_m3 = 1.6 for this slug
"loading_rate_per_h": 200,
"unloading_rate_per_h": 180
}
],
}
]
},
// ── Route profiles ─────────────────────────────────────────────────
// Use the API key shown in Settings → Route Profiles. Omit or set null to inherit active profiles from Settings.
// enum: fastest | shortest | no_tolls | no_ferries | no_tunnels | no_motorways | no_tolls_no_ferries | shortest_no_tolls
"route_profiles": ["fastest", "shortest", "no_tolls"],  // optional — falls back to Settings
// ── Settings (optional — global calculation adjustments) ───────────
"settings": {
"system": "metric",                     // required  enum: metric | imperial
"between_loads_only": false,            // optional — falls back to Settings → Transport Cost
"include_final_return": true,           // optional — falls back to Settings → Transport Cost
"trip_rounding": null,                  // optional — falls back to Settings → Trip Rounding  enum: none | round_up | round_down
"trip_time_adjustment_pct": 5,          // optional — % added to HERE drive time
"trip_distance_adjustment_pct": 0,      // optional — % added to HERE distance
"risk_adjustment_pct": 3,              // optional — % added to total cost
"complexity_factor_pct": 2            // optional — % added to total cost
}
}