Run a hub distribution

Distributions represent food leaving Surplus to reach a recipient. From a hub, you can manage both onsite pickups (recipient comes to the hub) and route deliveries (food is loaded onto a route for delivery).

Before you start

Items must be allocated to the distribution before it can be completed. See Allocate inventory if the distribution has no allocated items yet.

Completing a distribution

When a distribution is completed (food has been handed off to the recipient):

  1. All allocated items transition to distributed status
  2. Their hub location is cleared (they've left the system)
  3. The distribution event is marked completed
  4. Impact metrics update automatically

Empty completions (zero items) are valid — for example, if a recipient doesn't show up and the distribution is completed as-is.

Hub-connected route distributions

For deliveries via route (not onsite pickup):

  1. The distribution has both a hubId (source warehouse) and routeId
  2. Items are allocated from hub inventory as usual
  3. The route must have a load stop at this hub before the distribution stop
  4. When the load completes, items physically move from hub to vehicle
  5. When the driver completes the distribution stop, items are finalized as distributed

This is the "load → deliver" pattern that connects hub staging to route execution.

Cancelling a distribution

Cancelling releases all allocations and marks the event as terminal. Use this when a planned distribution will not happen at all.

Deleting a hub-connected route distribution

For route distributions sourced from a hub, deletion:

  • Releases all allocated items back to hub inventory
  • Removes the route stop
  • Deletes the distribution event entirely