Skip to main content

Dispatch Hub Cost Allocation: Rules, and API Mapping

C
Written by Charles Scannell
Updated over 2 weeks ago

Introduction

This knowledge base document outlines how cost allocation is currently handled in the M2X Dispatch Hub, with a focus on empty legs, service legs (e.g., trailer swaps), and the association between jobs, orders, and tasks.

Part 1 - Dispatch Hub Cost Allocation

How Cost Allocation Currently Works in Dispatch Hub

Default Rules

  • Jobs are Depot-to-Depot: Costs incurred between the start and end depots are allocated to the associated order.

Scenario

Allocation Behavior

Empty leg: Depot → Pickup

Allocated to Order

Pickup → Delivery

Allocated to Order

Delivery → Depot (click return to home depot)

If added after the fact required to be manually allocated through the Costs tab or the activity updated.

Trailer Swap / Service Leg

If added after the fact required to be manually allocated through the Costs tab or the activity updated.

Part 2: API Mapping - Where to Find Cost & Payload Data

Accessing the Full Vehicle Timeline: Current Workaround

To ensure complete visibility of all tasks executed by a vehicle (across pickups, deliveries, empty legs, and service legs), there is currently no consolidated API that returns all timeline activity in one call.

  • Use the vehicles/{vehicleId}/tasks/serviceDay/{serviceDay} endpoint to retrieve all published tasks for a specific vehicle on a given service day.

  • This API must be queried individually for each service day in the relevant timeline period—there is no support for a multi-day service window.

  • From this API, extract all taskIds to build a complete list of tasks present in the vehicle's operational timeline.

  • These taskIds can then be used to call vehicleTimelineStatements/{vehicleTimelineStatementId} to retrieve payload, metrics, and asset data per task.

However, this process only surfaces task-level information, not cost allocations. To access cost allocations:

  • You must query the vehicleTimelineStatementsAllocation API through the lens of orders, assuming the tasks are correctly associated.

  • If any task (e.g. service leg or empty leg) is not linked to an order, its cost allocation will not appear in the allocations API, even if the task is visible in the timeline.

This allows users to:

  1. Construct a complete list of executed tasks on a vehicle over a time period (i.e. the "vehicle timeline").

  2. Map those tasks to the corresponding cost allocations via the orders they are linked to.

  3. Identify gaps or missing allocations due to unlinked service legs.

1. BillingGroupsDetails API

  • Purpose: Provides overall precisionPrice, precisionTkm, precisionKm, and precisionHr for a full billing group.

  • Use Case: Best for viewing total cost and distance/duration across an entire job or order.

  • Limitations: Excludes unlinked or orphaned service legs.

Example:

"precisionPrice": 1946.4015066666666, "precisionTkm": 6606.777599999999, "precisionKm": 706.268, "precisionHr": 11.817222222222222'

2. VehicleTimelineStatements API

  • Purpose: Returns payload and timeline metrics per task (pickup, delivery, service).

  • Details: Includes payloadKg, distanceMeters, driveDurationSeconds, etc.

  • Requirement: You must know the relevant taskIds — typically sourced from the jobs/orders API, assuming the tasks are linked correctly.

  • Note: This is the only API that will show a service leg if it is not linked to an order/master job. In this case, it will not appear in cost allocations but will still show operational data.

3. VehicleTimelineStatementsAllocation API

  • Purpose: Provides leg-level cost allocation details for all tasks within a given activity.

  • Details: Includes allocation.cost, allocation.durationSeconds, allocation.distanceMeters, and distanceMetersWeightKg.

  • Strength: This is the key API for understanding how costs are distributed across individual legs within a job.

Example Breakdown:

"cost": 1281.8887516666668, "durationSeconds": 27122, "distanceMeters": 456920, "distanceMetersWeightKg": 6614467650

  • Pickup Leg: 711.16

  • Delivery Leg: 555.73

  • Empty Service Leg: 15.00

These all sum to match the billing group-level cost in the BillingGroupsDetails API, providing a full view of cost attribution at the leg level.

Summary

To access accurate and complete cost and payload data across all legs:

API

Data Provided

Dependencies/Notes

BillingGroupsDetails API

Overall precision pricing for the full order/job

Does not show unlinked service legs

VehicleTimelineStatements API

Payload, location, and time data per task

Requires task IDs; no cost data; essential for confirming leg presence

VehicleTimelineStatementsAllocation API

Cost allocation per leg within an activity

Must be cross-checked with VehicleTimelineStatements to ensure all legs are captured

The VehicleTimelineStatementsAllocation API is the authoritative source for understanding how each leg contributes to total job costs. However, it must be used in conjunction with the VehicleTimelineStatements API to ensure all expected legs (especially service legs or unlinked tasks) are included in the allocation. To ensure consistency and complete billing visibility, every task must be properly linked to its order, and the system should adopt a rule-based method to prevent unallocated "no-mans-land" service legs.

Related Articles
Create a consignment or manifest (General Freight)
Subcontracting in General Freight
Did this answer your question?