> ## 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.

# Allocations and access

> Understand how units are allocated to tenancies, how access is granted and restricted, and how Stora keeps third-party access control systems in sync.

When a booking completes, Stora creates a [tenancy and subscription](/2025-09/guides/core-concepts#the-rental-lifecycle-orders-tenancies-and-subscriptions). 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."

```mermaid actions={false} theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#e8ebf4', 'primaryTextColor': '#05195A', 'primaryBorderColor': '#e8ebf4', 'lineColor': '#FF7237', 'secondaryColor': '#e8ebf4', 'tertiaryColor': '#e8ebf4', 'edgeLabelBackground': '#FF7237'}}}%%
graph LR
    Site --> Tenancy
    Tenancy --> Contact
    Tenancy --> UA["Unit Allocation"]
    UA --> Unit
    Unit --> UT["Unit Type"]
```

* 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 |

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.

```mermaid actions={false} theme={null}
%%{init: {'theme': 'base', 'flowchart': {'defaultRenderer': 'elk'}, 'themeVariables': {'primaryColor': '#e8ebf4', 'primaryTextColor': '#05195A', 'primaryBorderColor': '#e8ebf4', 'lineColor': '#FF7237', 'secondaryColor': '#e8ebf4', 'tertiaryColor': '#e8ebf4', 'edgeLabelBackground': '#FF7237'}}}%%
graph TD
    available -->|"&nbsp; reserve &nbsp;"| reserved
    available -->|"&nbsp; grant access &nbsp;"| occupied
    reserved -->|"&nbsp; grant access &nbsp;"| occupied
    reserved -->|"&nbsp; deallocate &nbsp;"| available
    occupied -->|"&nbsp; overlock &nbsp;"| overlocked
    occupied -->|"&nbsp; deallocate &nbsp;"| available
    overlocked -->|"&nbsp; remove overlock &nbsp;"| occupied
    overlocked -->|"&nbsp; deallocate &nbsp;"| available
```

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.

<Note>
  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.
</Note>

### Reserving a unit via the API

To allocate a unit to a tenancy that hasn't started yet, use the reserve endpoint:

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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](#granting-access-via-the-api) 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:

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "unit": {
    "id": "unit_1e36123098e22cf8",
    "status": "occupied",
    "unit_allocation": {
      "id": "alloc_5f7475758314968d"
    }
  }
}
```

Grant access handles two scenarios:

| 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.                              |

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:

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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.

<Note>
  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.
</Note>

### Removing an overlock

To restore access, use the remove overlock endpoint with the same contact ID:

```bash theme={null}
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`:

```bash theme={null}
curl -X POST https://public-api.stora.co/2025-09/units/unit_1e36123098e22cf8/deallocate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```json theme={null}
{
  "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.

<Tip>
  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.
</Tip>

## 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                    |

Webhook payloads include the full unit resource, so you can update your local state directly without an additional API call. See [Webhooks](/2025-09/guides/webhooks) for setup and payload structure.