Location Occupancy
An occupancy interval records how long a Location holds stock for one Merchant and SKU. You can use this history to review storage usage per position and day, or measure how long stock stays in temporary cross-dock positions before leaving.
View occupancy history
- Navigate to Operations -> Warehouse -> Location Occupancy.
- Choose a Warehouse and, if needed, a Merchant.
- Filter by Location, Location Type, SKU, Status, or Temporary to narrow the results.
- Click Export and choose CSV to download the filtered intervals.
Access is controlled by the Operations -> Stock -> Location Occupancy role permission, which is not granted automatically. See User Roles.
By default, the grid shows intervals overlapping the last 30 days, including Locations occupied before that period that remained occupied during it. Set an Occupied At or Vacated At date filter to replace this default window. Clearing date filters restores the last-30-days window, including for CSV exports. If you set only an end date, the grid starts 29 days earlier so that the range is 30 days long; set a start date to look further back.
You only see Warehouses and Merchants your account can access. The grid is read-only and can be sorted by Occupied At or Vacated At; the newest intervals are listed first. The grid shows one Warehouse at a time. When you view all of your Warehouses at once, it starts with your current Warehouse; choose another in the Warehouse filter. A CSV export follows the same rule, so it contains the rows you see. An export is limited to 300,000 rows and five minutes; use the filters to export a larger history in parts.
The message above the grid shows the time through which the intervals are complete, normally about 40 minutes ago. Changes after that time are not shown yet, so an interval that still shows as open may already have ended, and its Duration runs to the current time. A day's figures are final once that time has passed the end of the day. When the message says the data is delayed, wait for it to catch up before you use the data for billing. The CSV file name includes the same time, in UTC.
Duration is shown as days, hours, minutes, and seconds (d:hh:mm:ss), so 1:02:03:04 is 1 day, 2 hours, 3 minutes, and 4 seconds.
What an interval records
Each interval keeps the Location label, Location Type, SKU, and whether the Location is Temporary as they were when the interval opened, so later renaming or changes to a Location do not rewrite the history. Changing only the label or the Temporary setting of a Location does not start a new interval.
Changing a Location's quantity without emptying it does not start a new interval. Intervals are tracked per Location, so moving stock to another Location closes the interval of the first Location and opens one for the second.
Open and Closed intervals
- Open means the Location has not yet been recorded as empty. Vacated At is blank and Duration continues to increase.
- Closed means the Location became empty, or its interval ended for one of the reasons below. Duration is the elapsed time between Occupied At and Vacated At.
A Location that is emptied and refilled within 60 seconds with the same SKU, Merchant, and Location Type is treated as one continuous interval, so brief gaps such as a pick followed by an immediate put-back do not appear as separate intervals. A longer gap closes the interval at the time the Location became empty.
| Reason | Meaning |
|---|---|
| Observed | Stock was recorded entering an empty Location or leaving it empty. |
| Backfill | Tracking started while stock was already present. The interval starts when tracking began, not when that stock originally arrived. |
| Split | The Location Type changed while the Location was occupied. The old interval closes and a new one starts at the same time. |
| Reconcile | The old interval closed and a new one started at the same time because the SKU or Merchant occupying the Location changed without the Location being emptied, or because a consistency check corrected the recorded history. |
Temporary Locations and billing
Use Temporary to include or exclude temporary positions, such as Locations used during cross-dock handling. Their occupancy can help you compare dwell times without treating them as long-term storage.
For storage billing, each interval is attributed to the Merchant whose stock occupied the position. Apply your agreed billing rules to the portion of each interval that overlaps your billing period. Duration shows the whole interval, not just the time inside your date filters; it is not an invoice amount or a rounded count of billable days. Position/day billing and cross-dock dwell analysis can use the same history with different rules for partial days and temporary positions.
Retrieve occupancy through the API
The same occupancy intervals are available through the Global API, so a billing system can retrieve them without exporting a file. See docs.shipstream.io for the API documentation.