Operating snapshot

Both operations use the same current operating state. A manifest request has eight top-level fields; a booking check adds new_movements.

Field	Meaning
data_as_of	When the source platform read this snapshot.
planning_period	Start and end of the period to plan.
timezone	The IANA operating timezone, normally Europe/London.
locations	Warehouses, customer properties, and handover points with coordinates.
nuggets	Each Nugget's availability, hire allocation, and current location.
movements	Movement legs already accepted for scheduling.
drivers	Availability, qualifications, and Fleet Check allowances when available.
lorries	Availability, Nugget capacity, and equipment.
new_movements	Booking-check only: the proposed booking's movement legs.

Locations and movement legs

A location is a place where work may happen. Sending a location does not ask the planner to visit it. A movement leg supplies that requirement, its time window, and the Nuggets involved.

Several movement legs can refer to the same location, and several movement legs can share one parent booking_id.

Supported location types are warehouse, customer_property, and handover_point.

Movement types

• deliver_empty asks the planner to select one or more available off-hire Nuggets and deliver them within the customer window.
• collect_empty identifies an off-hire Nugget to collect from a customer property.
• move_nugget moves one or more identified Nuggets from an origin to a destination.

Every movement has its own stable id. A customer movement should also carry its parent booking_id; an internal or administrative movement may omit it.

Deliver an empty Nugget

{
  "type": "deliver_empty",
  "id": "MOVEMENT-1001",
  "booking_id": "BOOKING-1001",
  "destination_id": "cheltenham-customer",
  "window": {
    "start": "2026-08-19T07:00:00+01:00",
    "end": "2026-08-19T12:00:00+01:00"
  },
  "quantity": 1,
  "empty_source": "any_available",
  "split_across_lorries": true
}

empty_source can be any_available or warehouse_only. With any_available, the planner may collect and redirect a suitable off-hire Nugget instead of returning to a warehouse first.

Collect an empty Nugget

{
  "type": "collect_empty",
  "id": "MOVEMENT-1002",
  "booking_id": "BOOKING-1002",
  "nugget_id": "NUGGET-42",
  "location_id": "customer-42",
  "window": {
    "start": "2026-08-19T09:00:00+01:00",
    "end": "2026-08-19T15:00:00+01:00"
  },
  "must_clear_by": "2026-08-19T17:00:00+01:00"
}

must_clear_by is a hard latest departure from the property. Omit it when the customer window is the only constraint.

Move identified Nuggets

{
  "type": "move_nugget",
  "id": "MOVEMENT-1003",
  "booking_id": "BOOKING-1003",
  "nugget_ids": ["NUGGET-42"],
  "origin_id": "customer-42",
  "destination_id": "tewkesbury-warehouse",
  "pickup_window": {
    "start": "2026-08-19T10:00:00+01:00",
    "end": "2026-08-19T14:00:00+01:00"
  },
  "arrival_window": {
    "start": "2026-08-19T10:00:00+01:00",
    "end": "2026-08-19T17:00:00+01:00"
  },
  "split_across_lorries": true
}

arrival_window is optional. When supplied, both the pickup and destination windows must be satisfied.

Nugget status

Nugget availability and customer allocation are separate, as in the system specification. availability is in_service, in_maintenance, quarantined, or destroyed. on_hire_to_customer_id identifies the customer currently hiring the Nugget; when absent, the Nugget is off-hire.

An off-hire in-service Nugget may be available at a warehouse or awaiting collection at a customer property. A destroyed Nugget may remain in the snapshot for inventory consistency but is excluded from planning resources.

Identifiers

Identifiers are supplied by the source platform and returned unchanged. Names are for people reading the payload; planning decisions and response references use the identifiers.