> ## 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. # Core concepts > Understand Stora's domain model, key resources, how they relate, and the lifecycles that drive the system. Before diving into specific endpoints, it helps to understand how Stora's domain model fits together. This guide covers the key resources, how they relate, and the lifecycles that drive the system. ## 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). ```mermaid actions={false} theme={null} %%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#e8ebf4', 'primaryTextColor': '#05195A', 'primaryBorderColor': '#e8ebf4', 'lineColor': '#FF7237', 'secondaryColor': '#e8ebf4', 'tertiaryColor': '#e8ebf4', 'edgeLabelBackground': '#FF7237'}}}%% graph TD Site --> UT["Unit Type"] --> Unit Contact -->|"  creates  "| Order Order -->|"  completes  "| Tenancy Order -->|"  completes  "| Subscription Tenancy --> UA["Unit Allocations"] Subscription --> Invoices ``` ## 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.) | The typical happy path is: `available` → `reserved` → `occupied` → `available` (when the tenant moves out). Overlocking and repossession are exception paths for non-payment. ```mermaid actions={false} theme={null} %%{init: {'theme': 'base', 'flowchart': {'defaultRenderer': 'elk'}, 'themeVariables': {'primaryColor': '#e8ebf4', 'primaryTextColor': '#05195A', 'primaryBorderColor': '#e8ebf4', 'lineColor': '#FF7237', 'secondaryColor': '#e8ebf4', 'tertiaryColor': '#e8ebf4'}}}%% graph LR available --> reserved --> occupied --> available occupied --> overlocked occupied --> repossessed unavailable <--> available ``` ## 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](/2025-09/guides/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 | An order contains **line items** — the individual charges that make up the rental (unit rent, protection, products, fees). ### 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") ```mermaid actions={false} theme={null} %%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#e8ebf4', 'primaryTextColor': '#05195A', 'primaryBorderColor': '#e8ebf4', 'lineColor': '#FF7237', 'secondaryColor': '#e8ebf4', 'tertiaryColor': '#e8ebf4', 'edgeLabelBackground': '#FF7237'}}}%% graph TD Order -->|"  the storage agreement  "| Tenancy Order -->|"  the billing agreement  "| Subscription Tenancy --> UA["Unit Allocations"] Subscription --> Invoices ``` You can navigate between them: an order references its tenancy and subscription. A tenancy references its order and subscription. A subscription references its tenancy and order. Use the `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 | Invoices are available in JSON, CSV, and PDF formats via the `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 either `open` 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 from `available` 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](/2025-09/guides/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.: ``` For example: `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`. {/* ## What's next - Build a custom booking flow → Creating a Booking - Sync unit availability → Managing Inventory - React to events in real time → Webhooks */}