SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

Warehouses

Warehouse locations, the default warehouse, virtual warehouses, and the warehouse-scoping access model.

Overview

A warehouse is a physical or virtual location that owns stock, documents, numbering sequences, and communication templates. Almost every financial and inventory entity carries a warehouse_id, so warehouses are the anchor for warehouse scoping — the mechanism that limits what a user (or API token) can see and act on.

Warehouses are managed under Admin → Setup → Warehouses (/admin/settings/warehouses). Creating, updating, and deleting a warehouse requires the settings.manage permission; viewing requires settings.view.

The default warehouse

The first warehouse created is automatically flagged as the default (is_default = true) so warehouse scoping always resolves to something. Exactly one warehouse is the default at a time; promote another warehouse with Set as default in the warehouse list (or is_default over the API). The default warehouse cannot be deleted — the delete action rejects it with a validation error.

When a warehouse is created, Signals seeds its per-warehouse document templates and communication templates automatically.

Virtual warehouses

A warehouse flagged is_virtual = true represents a virtual location — a vehicle, a job site, or a sub-hire holding location. A separate flag, include_in_default_queries, controls whether a warehouse participates in warehouse-spanning availability grids:

  • include_in_default_queries = true (default) — the warehouse appears in default availability and warehouse-aggregation queries.
  • include_in_default_queries = false — the warehouse is excluded from those warehouse-spanning grids but remains addressable directly by id, so you can still query or transfer against it explicitly.

Warehouse scoping

Warehouse scoping decides which warehouse-owned rows a user can see. It is resolved from the user's accessible warehouse ids:

  • Owners (the is_owner flag) and users holding any role with the all_warehouses flag are unrestricted — they can access every warehouse.
  • Everyone else is limited to the warehouses assigned to their account, taken from account_warehouses (preferred) or, as a fallback, their memberships. A membership with a null warehouse_id grants access to all warehouses; a user with no assignments has access to none.

Two layers enforce this:

  • WarehouseScope — a global Eloquent scope applied to warehouse-owned models. For a restricted user it constrains queries to their accessible warehouse_id values (directly, or through a relation path for indirectly-owned rows). Unrestricted users and unauthenticated contexts are not filtered. WarehouseScope::withoutScoping() temporarily lifts it when a row must be read regardless of scope.
  • ChecksWarehouseAccess — a policy trait whose canAccessWarehouse() gate confirms a specific model's warehouse is one the user can access. Global entities (no resolvable warehouse_id) are always allowed.

The warehouses catalogue itself is not warehouse-scoped: the Warehouses API and admin screen list all warehouses, gated by the settings.view / settings.manage permissions. Warehouse scoping applies to the entities that reference a warehouse (rentals, invoices, assets, documents, and so on).

Warehouse settings

The Add / Edit Warehouse form at /admin/settings/warehouses covers:

Field Notes
Warehouse Name Required
Street Address, City, County / State, Postcode / ZIP Address
Country Required
Currency Inherit the company base currency, or select another enabled currency
Timezone Rental times for this warehouse are entered and shown in this zone; leave blank to inherit the company timezone

Changing the effective currency, including by clearing a configured currency, is blocked while the warehouse has open rentals or price cards scoped to it in the original currency. Move or remove those price cards first, then run php artisan signals:audit-price-currencies to verify the remaining scopes before retrying.

The Warehouses API also accepts email, phone, tags and custom fields.

Each warehouse also keeps operational settings that are not on the form or the Warehouses API — they keep their defaults unless set by seeding or data import:

  • Currency — the warehouse may inherit the company base currency or select another enabled currency. Changing the effective currency, including by deleting its configured currency, is blocked while the warehouse has open rentals or price cards scoped to it in the original currency. Move or remove those price cards first, then run php artisan signals:audit-price-currencies to verify the remaining scopes before retrying.
  • Shortage policy — the confirmation-gate policy and dispatch-gate policy, plus optional synchronous auto-resolution with an ordered list of preferred resolvers. See Shortages.
  • Tax zone — the seller zone used for tax; when unset it is resolved from the warehouse country. See Tax & Compliance.
  • Branding — a logo, primary/secondary colours, and font family used when rendering the warehouse's documents.
  • Operating hours — per-day-of-week hours used by availability and scheduling.

API

See the Warehouses API for the REST surface, filter[field][operator] filtering, and response shapes. Warehouse lifecycle events (warehouse.created, warehouse.updated, warehouse.deleted) are available on the webhook surface.

Warehouse updates keep the established partial-update convention: a nullable field sent as null, including timezone, is left unchanged. To put a warehouse back on the company clock, send clear_timezone: true without a timezone value. This explicit flag distinguishes clearing the timezone from leaving it unchanged.