When a booking completes, Stora creates a tenancy and subscription. But how does the customer actually get access to a physical unit? That’s what unit allocations handle.
A unit allocation links a specific unit to a tenancy. It tracks when the unit was reserved, when access was granted, and by whom. Every allocation-related action — reserving, granting access, overlocking, deallocating — changes the unit’s status and, if the operator uses a smart entry provider, automatically syncs that change to their access control hardware.
How the pieces connect
A unit allocation sits between a tenancy and a unit. It’s the record that says “this specific unit has been assigned to this tenancy.”
- A site has tenancies — each one a storage agreement with a contact.
- Each tenancy can have one or more unit allocations — one per physical unit assigned.
- Each unit allocation points to a unit, which belongs to a unit type at the same site.
The unit allocation also records:
- When the unit was reserved (
reserved_at)
- When access was granted (
granted_access_at)
Unit status lifecycle
Every unit has a status that reflects where it is in the allocation lifecycle. The status changes as the unit moves through reservation, occupancy, and eventual deallocation.
| Status | Meaning |
|---|
available | Ready to be allocated |
reserved | Allocated to a tenancy that hasn’t started yet |
occupied | Tenant has access |
overlocked | Access restricted — typically due to non-payment |
unavailable (taken offline for maintenance) or repossessed (contents marked for repossession). These are operator-managed states and aren’t covered in detail here.
The happy path is straightforward: available → reserved → occupied → available. Overlocking and removing overlocks handle the non-payment exception path.
How units get allocated
There are two ways a unit gets allocated to a tenancy: automatically by Stora, or manually via the API.
Auto-reservation
If the operator has auto-reservation enabled, Stora automatically reserves a unit when a storefront booking completes. It selects an available unit of the correct type and creates the allocation.
If no units of the correct type are available at the time of booking, the tenancy is created without an allocation and the operator is notified to assign a unit manually.
Auto-reservation only applies to bookings made through the operator’s storefront. Orders created via the API do not trigger auto-reservation — your integration controls when and how units are allocated.
Reserving a unit via the API
To allocate a unit to a tenancy that hasn’t started yet, use the reserve endpoint:
curl -X POST https://public-api.stora.co/2025-09/units/unit_1e36123098e22cf8/reserve \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"tenancy_id": "ten_acaf3269a573af74"
}'
{
"unit": {
"id": "unit_1e36123098e22cf8",
"status": "reserved",
"unit_allocation": {
"id": "alloc_5f7475758314968d"
}
}
}
available to reserved and a unit allocation is created.
Constraints:
- The unit must be
available.
- The tenancy’s start date must be in the future. If the tenancy has already started, use grant access instead.
Granting access
A reserved unit isn’t accessible yet — the tenant can’t physically enter the storage space. The unit needs to transition to occupied for access to be granted.
Automatic on move-in day
Stora automatically transitions reserved units to occupied on the tenancy’s start date. This runs at approximately 6:00 AM in the operator’s local timezone.
Once the transition happens, the unit.occupied webhook fires and, if the operator uses a smart entry provider, the access control system is synced to grant the tenant physical access.
Granting access via the API
You don’t have to wait for move-in day. The grant access endpoint lets you transition a unit to occupied immediately:
curl -X POST https://public-api.stora.co/2025-09/units/unit_1e36123098e22cf8/grant_access \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"tenancy_id": "ten_acaf3269a573af74"
}'
{
"unit": {
"id": "unit_1e36123098e22cf8",
"status": "occupied",
"unit_allocation": {
"id": "alloc_5f7475758314968d"
}
}
}
| Starting status | What happens |
|---|
reserved | The existing reservation transitions to occupied. The unit must be reserved for the same tenancy you provide in the request. |
available | The unit is allocated and access is granted in a single step — no separate reserve call needed. |
reserved state.
Restricting and restoring access
Overlocking
Overlocking restricts a tenant’s access to their units — typically because of failed payments. The overlock endpoint operates on all occupied units for a given contact:
curl -X POST https://public-api.stora.co/2025-09/units/overlock \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"contact_id": "con_0ac0514ed0711462"
}'
{
"success": {
"message": "2 customer units were successfully overlocked."
},
"meta": {
"unit_ids": [
"unit_1e36123098e22cf8",
"unit_2e36123098e22cf8"
]
}
}
overlocked. A unit.overlocked webhook fires for each unit.
Operators can also configure Stora to auto-overlock units when a payment fails. If this is enabled, Stora handles the transition automatically — you don’t need to call the overlock endpoint yourself. The unit.overlocked webhook still fires so your integration can react.
Removing an overlock
To restore access, use the remove overlock endpoint with the same contact ID:
curl -X POST https://public-api.stora.co/2025-09/units/remove_overlock \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"contact_id": "con_0ac0514ed0711462"
}'
occupied. A unit.occupied webhook fires for each unit.
Deallocating a unit
Deallocation removes the unit allocation entirely and returns the unit to available:
curl -X POST https://public-api.stora.co/2025-09/units/unit_1e36123098e22cf8/deallocate \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
{
"unit": {
"id": "unit_1e36123098e22cf8",
"status": "available",
"unit_allocation": null
}
}
reserved, occupied, overlocked, or repossessed.
Auto-deallocation on move-out
If the operator has auto-deallocation enabled, Stora automatically deallocates units when a tenancy ends. The unit.deallocated and unit.available webhooks fire, and the access control system is synced to revoke access.
Access control sync
If the operator has configured a smart entry provider in Stora (such as Noke, PTI, Paxton, or any of the other supported providers), every status change described in this guide automatically syncs to the third-party access control system. You don’t need to do anything extra.
When you call an allocation endpoint — reserve, grant access, overlock, remove overlock, or deallocate — Stora:
- Updates the unit’s status
- Publishes the change to the configured access control provider
- Notifies the provider to grant or restrict physical access accordingly
For example, when a unit transitions to occupied, Stora tells the access control provider to allow the tenant entry. When it transitions to overlocked, the provider restricts access. When it’s deallocated, the provider revokes access entirely.
This means the API is your single point of control for both the logical state of a unit and the physical access to it. You don’t need to integrate with individual access control providers — Stora handles that layer.
Webhook events
Subscribe to these events to react to allocation changes in real time:
| Event | When it fires |
|---|
unit.reserved | A unit has been reserved for a tenancy |
unit.occupied | A unit is now occupied — the tenant has access |
unit.overlocked | Access has been restricted |
unit.deallocated | The unit allocation has been removed |
unit.available | The unit is available again |
