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):
- All allocated items transition to
distributedstatus - Their hub location is cleared (they've left the system)
- The distribution event is marked
completed - 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):
- The distribution has both a
hubId(source warehouse) androuteId - Items are allocated from hub inventory as usual
- The route must have a load stop at this hub before the distribution stop
- When the load completes, items physically move from hub to vehicle
- 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
Related guides
- Allocate inventory — reserve items before completing
- Cost sharing and carrier fees — CSA rates for hub distributions
- Handle route exceptions — cancel or un-complete events
