Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stora.co/llms.txt

Use this file to discover all available pages before exploring further.

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.
StatusMeaning
availableReady to be allocated
reservedAllocated to a tenancy that hasn’t started yet
occupiedTenant has access
overlockedAccess restricted — typically due to non-payment
Units can also be 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"
    }
  }
}
The unit transitions from 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"
    }
  }
}
Grant access handles two scenarios:
Starting statusWhat happens
reservedThe existing reservation transitions to occupied. The unit must be reserved for the same tenancy you provide in the request.
availableThe unit is allocated and access is granted in a single step — no separate reserve call needed.
This is useful when you want to give a tenant early access before their tenancy officially starts, or when you’re managing allocations entirely through the API and don’t need the intermediate 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"
    ]
  }
}
All of the contact’s occupied units transition to 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"
  }'
All of the contact’s overlocked units transition back to 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
  }
}
A unit can be deallocated from any allocated status: 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:
  1. Updates the unit’s status
  2. Publishes the change to the configured access control provider
  3. 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:
EventWhen it fires
unit.reservedA unit has been reserved for a tenancy
unit.occupiedA unit is now occupied — the tenant has access
unit.overlockedAccess has been restricted
unit.deallocatedThe unit allocation has been removed
unit.availableThe unit is available again
Webhook payloads include the full unit resource, so you can update your local state directly without an additional API call. See Webhooks for setup and payload structure.