The big picture
Stora models a self-storage business. At the top level, an operator runs one or more sites (physical locations). Each site has unit types (storage categories) containing individual units (bookable spaces). Contacts rent units through orders, which create tenancies (the storage agreement) and subscriptions (the billing agreement).Sites, unit types, and units
These three resources represent the physical world of a storage facility.Site
A single physical self-storage location. It’s the container for everything at that location: units, pricing, access control, and reporting. A site has an address, access hours, and contact details.Unit type
A standardised storage offering at a site — for example “50 sq ft indoor” or “20 ft container.” Unit types define the size, features, and pricing that apply to all units of that type.Unit
A specific, bookable storage space — for example “Unit A-012” of a given unit type. Each unit tracks its own status as it moves through the rental lifecycle. Unit states:| State | Meaning |
|---|---|
available | Ready to be rented |
reserved | Allocated to a tenancy that hasn’t started yet |
occupied | Allocated and the tenancy is active |
overlocked | Access restricted, typically due to non-payment |
repossessed | Contents repossessed after prolonged non-payment |
unavailable | Taken offline by staff (maintenance, etc.) |
available → reserved → occupied → available (when the tenant moves out). Overlocking and repossession are exception paths for non-payment.
Contacts
A contact is the end user of a storage business — an individual or company that inquires, books, and pays for storage. Contacts exist at the operator level (not per-site), so the same person can rent at multiple locations. Contacts support metadata for attaching your own external identifiers.The rental lifecycle: orders, tenancies, and subscriptions
This is the most important relationship in the API. Three resources represent different views of a rental:Order
An order captures a contact’s intent to rent storage. It includes the selected site, unit type, move-in date, pricing, and optional add-ons (protection, products, services). Order states:| State | Meaning |
|---|---|
draft | Being assembled — line items can be added or changed |
finalized | Locked in — validated and ready for completion |
completed | Done — a tenancy and subscription have been created |
abandoned | Cancelled before completion |
Tenancy
A tenancy represents the ongoing storage agreement between a contact and an operator. It answers the questions: who has which unit, at which site, from when to when? A tenancy is created when an order completes. It links to:- The order that created it
- The subscription that bills for it
- The unit allocations — which specific units are assigned
- The site and contact
Subscription
A subscription is the billing side of the same rental. It represents the recurring payment agreement — billing period, prices, discounts, and taxes. Subscriptions generate invoices on each billing cycle.How they fit together
When an order completes, Stora creates both a tenancy and a subscription. They represent the same rental from two different angles:- Tenancy = the physical/logistical view (“who is storing what, where”)
- Subscription = the financial view (“what are they paying, and when”)
expand parameter to include related resources inline.
Billing: invoices and credit notes
Invoices
A subscription generates invoices on each billing cycle. Invoices are also created for one-off charges and security deposits. Invoice states:| State | Meaning |
|---|---|
draft | Being prepared — not yet issued |
open | Issued — awaiting payment |
paid | Settled |
uncollectible | Payment failed and won’t be retried |
void | Cancelled |
Accept header.
Credit notes
A credit note reduces or reverses part or all of a previously issued invoice. It references the original invoice and specifies the corrected amounts.Deals
A deal is a pre-sale CRM record representing a potential order. Where an order captures firm intent with agreed pricing, a deal tracks the early-stage sales process — an inquiry that may or may not convert. Deal states:open → won or lost
A deal links to a contact, and optionally a site and unit type. When a deal is won, it typically leads to an order being created.
Supporting resources
Contracts
A contract is a document generated from a contract template for a specific contact and tenancy. It tracks the signing lifecycle:pending → signed, voided, declined, or deleted.
Notes
A text annotation attached to a resource — a contact, unit, subscription, or task. Notes capture observations, reminders, or context added by staff or integrations.Tasks
A piece of work, optionally linked to a resource (a unit, subscription, or contact). Tasks are eitheropen or completed, and can be assigned to staff.
Products and protection levels
Products are sellable items or services (e.g. padlocks, insurance, admin fees). Protection levels are optional add-ons that protect a contact’s stored goods up to a chosen coverage amount. Both can appear as line items on an order.Coupons
Reusable promotions that reduce the price a contact pays, by a percentage or fixed amount. Coupons can be scoped to specific charge types and limited by duration or number of uses.Unit allocations
A unit allocation joins a specific unit to a tenancy. It tracks when the unit was reserved, when access was granted, and by whom. This is what drives the unit’s status — allocating a unit moves it fromavailable to reserved or occupied.
For a full walkthrough of the allocation lifecycle, auto-reservation, access control sync, and the API endpoints for managing unit access, see Allocations and access.
Resource IDs
All resources use prefixed string IDs. The prefix tells you the resource type at a glance:| Prefix | Resource |
|---|---|
site_ | Site |
ut_ | Unit Type |
unit_ | Unit |
con_ | Contact |
ord_ | Order |
ten_ | Tenancy |
sub_ | Subscription |
inv_ | Invoice |
cn_ | Credit Note |
deal_ | Deal |
task_ | Task |
we_ | Webhook Endpoint |
Scopes
Every API endpoint (except OAuth 2) requires at least one scope. Scopes follow the format:public.contact:read, public.order:write, public.site:read.
When expanding related resources in a response, your token needs the read scope for each expanded resource. For example, expanding site on a subscription requires public.site:read in addition to public.subscription:read.