Logistics & Supply Chain
Shipment Exception Prediction API
Exception management in most operations means reacting to a customer complaint. The scan data usually knew hours or days earlier.
- 3PLs and freight forwarders
- Carriers
- E-commerce operations teams
- Transport management software
- Last-mile platforms
What your customers would see
example interfaceMockupIllustrative mockup of the interface we would build. Figures shown are examples, not results from a live deployment.
The problem this solves
Every logistics operation has an exception desk, and in most of them the work arrives from outside. A customer calls about a parcel that has not moved. A consignee flags a missed delivery window. A warehouse notices a container that should have arrived. By then the useful intervention window has closed and the job is damage control rather than recovery.
The signals that precede an exception are mundane and sitting in the event stream. A shipment that has not scanned in longer than its usual interval for that leg. A parcel scanned into a hub that handles its destination region only on certain days. A consignment whose next expected event is a handoff to a partner with a backlog. Silence itself is information — the absence of an expected scan is often the earliest signal available.
The modelling challenge is not detection, it is precision. An exception engine that flags eight per cent of shipments is ignored within a fortnight, because an exception desk with twelve people cannot work a queue of forty thousand. The build has to be tuned to a workable alert volume, with the threshold set by how many interventions the operation can actually make, and with each alert carrying enough reasoning that the desk knows what to do with it.
Who buys this
3PLs and freight forwarders, Carriers, E-commerce operations teams, Transport management software, Last-mile platforms
What the API returns
What comes back
- Exception probability per in-flight shipment, by exception type
- Expected next event with the window in which it should occur
- Silence detection against the shipment's own expected scan rhythm
- Predicted exception type: delay, misroute, missed handoff, damage, loss
- Recommended action per alert, mapped to what the operation can do
- Alert volume control so the queue matches available intervention capacity
- Reasoning on every alert, with the contributing events named
- Outcome feedback capture so precision can be measured and improved
Endpoints
| Method | Path | Returns |
|---|---|---|
| GET | /v1/shipments/{id}/exception-risk | Exception risk and reasoning for one shipment |
| POST | /v1/shipments/score | Score a batch of in-flight shipments |
| GET | /v1/queue | Current exception queue, ranked and volume-controlled |
| POST | /v1/events | Post scan and milestone events for continuous scoring |
| POST | /v1/outcomes | Report what actually happened, for precision measurement |
| WS | /v1/stream | Push new exceptions as they are detected |
Request and response
illustrativeRequest
{
"shipment_id": "shp_99124",
"service": "international_express",
"origin": "CNSZX",
"destination": "GB_M1",
"promised_delivery": "2026-10-28",
"events": [
{ "type": "collected", "at": "2026-10-20T08:12:00Z", "location": "CNSZX" },
{ "type": "departed_origin_hub", "at": "2026-10-21T02:40:00Z", "location": "CNSZX" },
{ "type": "arrived_transit_hub", "at": "2026-10-22T19:05:00Z", "location": "DEHAM" }
]
}Response
{
"shipment_id": "shp_99124",
"scored_at": "2026-10-24T06:00:00Z",
"exception_risk": 0.63,
"band": "high",
"predicted_types": [
{ "type": "missed_handoff", "probability": 0.38 },
{ "type": "delay_over_24h", "probability": 0.21 },
{ "type": "misroute", "probability": 0.04 }
],
"expected_next_event": {
"type": "departed_transit_hub",
"expected_by": "2026-10-23T12:00:00Z",
"status": "overdue",
"overdue_hours": 42
},
"reasoning": [
{ "signal": "scan_silence", "detail": "42h since last event; lane p90 is 19h", "weight": 0.47 },
{ "signal": "partner_backlog", "detail": "DEHAM to GB handoff running above normal dwell", "weight": 0.22 },
{ "signal": "promise_proximity", "detail": "2 days to promised delivery", "weight": 0.11 }
],
"recommended_action": {
"action": "query_partner_handoff",
"owner": "exception_desk",
"window_hours": 8
},
"queue": { "rank": 14, "of": 212, "capacity_threshold": 250 }
}Where the data comes from
| Your scan and milestone events | The event stream across your own network and your partners — both the events and their absence are the primary signal |
| Carrier and partner tracking integrations | Status from partners who hold a leg, which is where most missed handoffs actually occur |
| Your historical exception outcomes | Labelled past exceptions with what they turned out to be, without which precision cannot be measured |
| Service and lane definitions | Expected event sequences and dwell times per service, so overdue means something specific |
| Facility and partner operating calendars | Hub cut-offs and non-operating days, which explain a large share of apparent silences |
| Disruption signals | Weather, port congestion and known network incidents, which separate a systemic delay from a lost shipment |
The intelligence layer
The difference between a demo and a service is mostly in this section. These are the parts that keep the answer trustworthy once real traffic is hitting it.
- Expected-event modelling per service and lane, so overdue is measured against that leg's own distribution rather than a global threshold
- Silence treated as a first-class feature, since the absence of a scan is frequently the earliest available signal
- Multi-class prediction over exception types, because the recommended action differs completely between a misroute and a partner backlog
- Threshold selection driven by the operation's intervention capacity, not by maximising a classification metric nobody can act on
- Precision and recall reported at the operating threshold, with the trade-off made explicit to the exception desk
- Reason attribution on every alert from the contributing events, so the desk receives a case rather than a score
- Outcome feedback loop with retraining, since an exception engine without labels degrades quietly
- Separate handling of systemic events — a port closure generates thousands of correlated alerts and should be collapsed into one
What it changes for the business
Intervention while it still helps
Alerts arrive with hours or days of lead time instead of after the consignee has called.
A workable queue
Volume control sized to the desk means alerts get worked rather than ignored.
Partner accountability
Handoff dwell data makes a partner conversation specific rather than anecdotal.
Measured performance
Outcome feedback gives a real precision figure, so the engine can be trusted or corrected on evidence.
How it fits into your product
How it embeds
- Events posted as they arrive, with scoring triggered on event or on a schedule
- Ranked queue endpoint that respects a configured daily alert capacity
- WebSocket and webhooks into your exception desk tooling or ticketing system
- Outcome posting from the desk's own resolution workflow, which feeds precision measurement
- Systemic-event grouping so a port closure produces one case rather than four thousand alerts
- Deployment inside your infrastructure where shipment and customer data cannot leave
Included in every build
- Authentication, scoped API keys and per-customer rate limiting
- Input validation with predictable, documented error responses
- Versioned endpoints so your integration never breaks without notice
- Request and response logging for audit and dispute resolution
- Latency, error-rate and usage monitoring with alerting
- OpenAPI specification, sandbox environment and client examples
- Backups, failover design and a documented recovery procedure
- An agreed support arrangement once the service is live
How we would build it
about 20 weeksDiscovery and feasibility
Weeks 1–3
This one depends heavily on data access, so we start by proving the sources exist, can be licensed for your use, and actually carry the signal the model needs. If they do not, you find out here.
Architecture and baseline model
Weeks 4–6
A written architecture and a baseline model measured against a holdout period, so you know what accuracy you are buying before the full build starts.
Production build
Weeks 7–16
Data pipelines, model training and serving, historical archive, validation harness, API, security, monitoring and documentation.
Validation and integration
Weeks 17–20
Backtesting against held-out history, accuracy reporting your team can audit, integration support and an agreed retraining cadence.
Commercial models
There is no fixed price list, because the cost is driven by data complexity, integration count, model requirements, request volume and the support level you need. Scope is agreed in writing before development starts.
Fixed-scope prototype
A defined slice of the service, built and priced as one piece of work. The usual first step when the business case needs proving internally.
Fixed-price build
An agreed scope against a written architecture, delivered for an agreed price. Best when the requirements are already clear.
Build then retainer
We build the service, then operate and improve it under a monthly agreement covering monitoring, updates and model maintenance.
White-label product
The service runs under your brand, your domain and your pricing, with MLPivot invisible to your customers.
Questions buyers ask
How many false alarms will the desk see?
That is a dial, not a fixed property, and the honest answer is that you choose it. At a threshold giving roughly 200 alerts a day on a large book, expect a meaningful share to resolve on their own. Tighten the threshold and precision rises while genuine exceptions are missed. We set it with the desk based on how many interventions they can make, and we report precision at that operating point rather than quoting a figure from a more flattering threshold.
Can you predict theft or loss?
We predict that a shipment is not progressing as it should, which covers loss as one outcome among several. Distinguishing a stolen consignment from a mis-scanned one in advance is generally not possible from event data, and the API does not claim to. Loss appears as a low-probability class with wide uncertainty, and we would not present it more confidently than that.
What if our partners' tracking data is poor?
Then performance on those legs is poor, and that is worth knowing explicitly rather than averaging away. Where a partner emits two scans for a five-day leg, the model has very little to work with and the API reports low confidence for that segment. The practical fix is usually improving the data feed, not the model.
Does it need historical exception labels to start?
It needs them to be good. Expected-event and silence detection work from day one on event history alone, which is already useful. Exception-type prediction and calibrated precision require labelled outcomes, so the first months typically run with the desk posting outcomes while the type model trains.
How do you handle a major disruption?
Correlated alerts are collapsed into a single systemic case with the affected shipments attached, because a port closure that triggers four thousand individual alerts destroys the queue. The desk gets one case to manage and a list, not an inbox nobody can open.
Related blueprints
Delivery Time Prediction API
Estimated delivery windows and delay probabilities per shipment, as the promise engine behind a commerce or carrier product.
Supplier Reliability Scoring API
Punctuality, quality incident and disruption risk scoring per supplier, for procurement and supply chain software.
Route Risk Intelligence API
Disruption, weather exposure, security and delay indicators along a planned route, for transport planning and freight software.
Want this built for your platform?
Tell us what your product does today and what you want another system to be able to ask it. We will come back with an approach, a scope and a price.