What it does
- Facilities. Warehouses, depots, offices and pickup-drop points, each with its address and operating detail.
- In-facility locations. A nested hierarchy — zone, then aisle, then rack, then shelf, then bin — describing where things physically sit inside a facility.
- The package journey. Every move a package makes inside a facility, recorded rather than overwritten: received into a bay, moved to a bin, picked, staged, loaded onto a run.
- Exception states. Packages marked damaged or lost, with the time it happened, so a discrepancy is a recorded fact rather than an absence.
- Pick, pack and ship workflows. Planned — assembling orders from stock held in the facility.
Facilities, the in-facility location hierarchy, and package movement and status tracking are available now. Inventory counts held against a location, and the pick-pack-ship workflow on top of them, are planned. Stock quantities per facility arrive with the Product Catalogs module.
How it works
The hierarchy is yours to shape
Nothing forces a depth. A small cross-dock might use two or three zones and stop there; a large distribution centre can go all the way to individual bins. You describe the building you actually have, and every level is optional. The structure is ordinary platform data, so a scanning app, an ERP sync and an AI agent all read the same layout.
Movement is recorded, not overwritten
When a package moves from a receiving bay to a bin, the platform records the move. It does not simply replace the previous location with the new one. The consequence is that a package has a journey you can replay — which is what you need when something has gone missing and the question is where it was last seen, and by whom.
Facilities are where storage meets delivery
A facility is not a separate world from your deliveries. A run starts from one, a stop can be one, and a package’s in-facility location is part of the same package record that later gets loaded onto a vehicle. There is no handover between a warehouse system and a delivery system, because there is no boundary — the package that was in bin C-14 this morning is the package on run 42 this afternoon.
A facility, not just a warehouse
The model is deliberately general. The same structure describes a warehouse, a depot, a branch office, or a locker bank used as a pickup point. That matters as networks get more mixed — you should not need a different concept for each kind of building you operate.
Permissions
| Permission | What it allows | Needed |
|---|---|---|
| facilities.read | Read facilities and the in-facility location hierarchy within them. | Required |
| facilities.write | Create, update and delete facilities and their in-facility locations. | Required to configure |
| orders.read | Read the orders whose packages are being handled. | Required |
| orders.write | Create and edit orders and the packages under them, including marking a package moved, damaged or lost. | Required |
| stops.read | Read the stops that collect from or deliver to a facility. | Recommended |
| stops.write | Link packages to the stops that will move them. | Recommended |
| runs.read | Read the runs that load out of a facility. | Optional |
| documents.read | Read metadata for documents attached to goods — receipts, dockets, condition photos. | Optional |
| documents.write | Attach document metadata to goods handled in a facility. | Optional |
API reference
Inventory and pick-pack-ship have no public contract yet. The depot structure they build on is callable today on the core facilities API.
| Service | What it covers | Reference | Contract |
|---|---|---|---|
| facilities-api | Facilities and in-facility locations — zone, aisle, rack, shelf, bin. Core platform. | OpenAPI description | openapi.json |
The contract above belongs to the core platform, not to this module. It is listed because it is the surface that does this work today — when the module publishes its own API, it will appear here.
Each openapi.json is the generated OpenAPI 3.1 contract, served by the service itself — it is never hand-edited, so it cannot drift from the running API. The OpenAPI description link opens the same contract as a browsable reference. Both resolve to the environment these docs are served from, so a page read on the test site links to the test contract.
Events
Package handling is the event-rich part of this module. Subscribing to these gives you a live feed of what is happening inside your buildings without polling.
| Event | Raised when | Tells you |
|---|---|---|
| package.created | A package is created for an order. | The package and the order it belongs to. |
| package.moved | A package moves to a new location inside a facility. | The package and its new in-facility location — this is the package-journey event. |
| package.status.changed | A package’s lifecycle status transitions. | The status it moved from and the status it moved to. |
| package.damaged | A package is marked damaged. | The package and the time it was marked — the trigger for a claim or an exception workflow. |
| package.lost | A package is marked lost. | The package and the time it was marked. |
| package.delivered | A package is delivered. | The package and the stop it was delivered at — the point it leaves your facility network for good. |
| note.created | A note is added against a package or facility. | What the note was attached to, and when. |
The envelope these arrive in, the delivery and retry guarantees, and every other event type are in Events & webhooks — or jump straight to the event catalog.