SIGNALS Documentation
API Reference

Warehouses

CRUD endpoints for warehouse locations — the anchor for stock, documents, and warehouse scoping.

Warehouses API

CRUD endpoints for managing warehouses — the physical or virtual locations that own stock, documents, and numbering sequences. Every financial and inventory entity carries a warehouse_id, so warehouses are the anchor for warehouse scoping across the platform.

Endpoints

Method URL Description
GET /api/v1/warehouses List warehouses
GET /api/v1/warehouses/{id} Show a warehouse
POST /api/v1/warehouses Create a warehouse
PUT/PATCH /api/v1/warehouses/{id} Update a warehouse
DELETE /api/v1/warehouses/{id} Delete a warehouse

Authentication

Requires a Sanctum bearer token with warehouses:read (GET) or warehouses:write (POST/PUT/PATCH/DELETE) ability, plus the settings.view (read) or settings.manage (write) permission.

List Warehouses

GET /api/v1/warehouses

Filters

Ransack-compatible predicates on the q parameter. id is always filterable.

Parameter Description
q[name_cont]=warehouse Name contains
q[name_eq]=Main Warehouse Name equals
q[id_eq]=3 Filter by id
q[city_eq]=London City equals
q[country_code_eq]=GB Country code equals
q[country_id_eq]=1 Filter by country
q[tax_zone_id_eq]=2 Filter by tax zone
q[is_default_true]=1 Only the default warehouse

Sorts

Parameter Description
sort=name Sort by name (ascending)
sort=-name Sort by name (descending)
sort=city Sort by city
sort=created_at Sort by creation date

Includes

Eager-load relationships with ?include=country,taxZone,customFieldValues. customFieldValues is always loaded so custom_fields is present in every response.

Response

{
    "warehouses": [
        {
            "id": 1,
            "name": "Main Warehouse",
            "street": "12 Depot Road",
            "city": "London",
            "county": "Greater London",
            "postcode": "E1 6AN",
            "country_code": "GB",
            "country_id": 1,
            "tax_zone_id": 1,
            "phone": "+44 20 7946 0000",
            "email": "warehouse@example.com",
            "timezone": "Europe/London",
            "is_default": true,
            "is_virtual": false,
            "include_in_default_queries": true,
            "tag_list": ["primary"],
            "custom_fields": {},
            "created_at": "2026-01-15T14:30:00.000Z",
            "updated_at": "2026-01-15T14:30:00.000Z"
        }
    ],
    "meta": {
        "total": 1,
        "per_page": 20,
        "page": 1
    }
}

Show Warehouse

GET /api/v1/warehouses/{id}

Response with includes

Request: GET /api/v1/warehouses/1?include=country,taxZone

{
    "warehouse": {
        "id": 1,
        "name": "Main Warehouse",
        "country_id": 1,
        "tax_zone_id": 1,
        "custom_fields": {},
        "created_at": "2026-01-15T14:30:00.000Z",
        "updated_at": "2026-01-15T14:30:00.000Z",
        "country": {
            "id": 1,
            "name": "United Kingdom"
        },
        "tax_zone": {
            "id": 1,
            "name": "UK"
        }
    }
}

country and tax_zone are omitted from the response unless the matching include is requested. When the include is requested but the warehouse has no country / tax zone set, the key is present with a null value.

Create Warehouse

POST /api/v1/warehouses

{
    "name": "North Depot",
    "street": "5 Industrial Way",
    "city": "Manchester",
    "postcode": "M1 1AA",
    "country_code": "GB",
    "country_id": 1,
    "email": "north@example.com"
}

Returns 201 Created.

The first warehouse created is automatically flagged as the default (is_default: true) so warehouse scoping always resolves. Pass is_default: true explicitly to promote a later warehouse to default.

Update Warehouse

PUT/PATCH /api/v1/warehouses/{id}

Standard update pattern — returns 200 OK with the updated warehouse in a warehouse key.

Clearing nullable fields: Omitting a field or sending null leaves it unchanged. Only non-null fields in the update payload are applied.

Delete Warehouse

DELETE /api/v1/warehouses/{id}

Standard delete pattern — returns 204 No Content.

Default warehouse guard: The default warehouse cannot be deleted. DELETE against it returns 422 Unprocessable Entity:

{
    "message": "The default warehouse cannot be deleted.",
    "errors": { "warehouse": ["The default warehouse cannot be deleted."] }
}

Webhooks

Warehouse lifecycle events (warehouse.created, warehouse.updated, warehouse.deleted) are dispatched to subscribed endpoints — see Webhooks.

Warehouse scoping

Warehouse-restricted API tokens only ever return warehouse-owned rows for the warehouses their user can access. The warehouses catalogue itself is not warehouse-scoped; see Warehouses for the warehouse-scoping model.