Warehouse API: Locations, Bins, and Setup Status

The Warehouse API provides the foundation for physical space management in Dragon Guard WMS. The warehouse is organized into a two-level hierarchy: locations (zones or areas within the warehouse) and bins (individual storage positions within a location). The setup status endpoint gives administrators a quick overview of whether the warehouse has been configured with the minimum required structure. All lifecycle operations — activate, deactivate, and set-as-default — are available as dedicated action endpoints for both locations and bins.

Endpoints overview

Setup Status
Locations
Bins

Method	Path	Description
`GET`	`/api/warehouse/setup-status`	Check warehouse configuration completeness

Method	Path	Description
`GET`	`/api/warehouse/locations`	List all warehouse locations
`POST`	`/api/warehouse/locations`	Create a new warehouse location
`PUT`	`/api/warehouse/locations/{id}`	Update a warehouse location
`PUT`	`/api/warehouse/locations/{id}/activate`	Activate a warehouse location
`PUT`	`/api/warehouse/locations/{id}/deactivate`	Deactivate a warehouse location
`PUT`	`/api/warehouse/locations/{id}/default`	Set a location as the default

Method	Path	Description
`GET`	`/api/warehouse/locations/{locationId}/bins`	List all bins within a location
`POST`	`/api/warehouse/locations/{locationId}/bins`	Create a new bin in a location
`PUT`	`/api/warehouse/bins/{id}`	Update a bin
`PUT`	`/api/warehouse/bins/{id}/activate`	Activate a bin
`PUT`	`/api/warehouse/bins/{id}/deactivate`	Deactivate a bin
`PUT`	`/api/warehouse/bins/{id}/default`	Set a bin as the default for its location

Setup status

GET /api/warehouse/setup-status
Authorization: Bearer {token}

Returns a summary of the current warehouse configuration state. The frontend uses this to determine whether to display setup prompts or allow normal warehouse operations. Example response

{
  "hasLocations": true,
  "hasActiveBins": true,
  "hasDefaultLocation": true,
  "hasDefaultBin": false,
  "isSetupComplete": false,
  "warnings": ["No default bin has been assigned."]
}

hasLocations

boolean

true if at least one location has been created.

hasActiveBins

boolean

true if at least one active bin exists across all locations.

hasDefaultLocation

boolean

true if a location has been marked as default.

hasDefaultBin

boolean

true if a bin has been marked as default within the default location.

isSetupComplete

boolean

true only when all prerequisite setup conditions are met.

warnings

array

Human-readable messages describing any incomplete setup conditions.

Location management

List locations

GET /api/warehouse/locations
Authorization: Bearer {token}

Returns all warehouse locations for the active company. Example response

[
  {
    "id": 3,
    "code": "ALM-CENTRAL",
    "name": "Almacén Central",
    "isActive": true,
    "isDefault": true,
    "companyId": 7
  }
]

Create a location

POST /api/warehouse/locations
Authorization: Bearer {token}
Content-Type: application/json

companyId

number

required

The ID of the company that owns this location.

code

string

required

Unique alphanumeric code for the location within the company (e.g., ALM-01, ZONA-FRIO).

name

string

required

Descriptive name for the location displayed in the UI.

isActive

boolean

Initial active state. Defaults to true.

Example request

{
  "companyId": 7,
  "code": "ALM-02",
  "name": "Almacén Secundario",
  "isActive": true
}

Example response — 201 Created

{
  "id": 4,
  "code": "ALM-02",
  "name": "Almacén Secundario",
  "isActive": true,
  "isDefault": false,
  "companyId": 7,
  "createdAt": "2024-07-12T15:00:00Z"
}

Update a location

PUT /api/warehouse/locations/{id}
Authorization: Bearer {token}
Content-Type: application/json

number

required

The ID of the location to update.

name

string

Updated display name.

Activate a location

PUT /api/warehouse/locations/{id}/activate
Authorization: Bearer {token}

number

required

The ID of the location to activate.

Sets isActive: true. Active locations appear in creation forms for receipts and shipments.

Deactivate a location

PUT /api/warehouse/locations/{id}/deactivate
Authorization: Bearer {token}

number

required

The ID of the location to deactivate.

Sets isActive: false. Deactivated locations are hidden from creation forms but remain visible in historical documents and stock queries.

Deactivating a location that contains active bins with current stock will not automatically deactivate those bins or move that stock. Ensure the location is empty and all bins are deactivated before deactivating the parent location.

Set default location

PUT /api/warehouse/locations/{id}/default
Authorization: Bearer {token}

number

required

The ID of the location to set as default.

Designates this location as the company’s default warehouse location. Only one location can be default at a time; calling this endpoint clears the default flag from any previously designated location.

Bin management

Bins are individual storage positions within a location. They form the lowest level of the warehouse hierarchy and are referenced by handheld devices during receiving and picking operations.

List bins for a location

GET /api/warehouse/locations/{locationId}/bins
Authorization: Bearer {token}

locationId

number

required

The ID of the parent location.

Example response

[
  {
    "id": 14,
    "code": "A-01-03",
    "description": "Rack A, Row 1, Shelf 3",
    "isActive": true,
    "isDefault": true,
    "locationId": 3
  }
]

Create a bin

POST /api/warehouse/locations/{locationId}/bins
Authorization: Bearer {token}
Content-Type: application/json

locationId

number

required

The ID of the parent location where this bin is created.

code

string

required

Unique bin code within the parent location (e.g., A-01-03, DOCK-B).

description

string

Optional human-readable description of the bin’s physical position.

isActive

boolean

Initial active state. Defaults to true.

Example request

{
  "code": "A-02-01",
  "description": "Rack A, Row 2, Shelf 1",
  "isActive": true
}

Example response — 201 Created

{
  "id": 15,
  "code": "A-02-01",
  "description": "Rack A, Row 2, Shelf 1",
  "isActive": true,
  "isDefault": false,
  "locationId": 3,
  "createdAt": "2024-07-12T15:30:00Z"
}

Update a bin

PUT /api/warehouse/bins/{id}
Authorization: Bearer {token}
Content-Type: application/json

number

required

The ID of the bin to update.

description

string

Updated description for the bin’s physical position.

Activate a bin

PUT /api/warehouse/bins/{id}/activate
Authorization: Bearer {token}

number

required

The ID of the bin to activate.

Deactivate a bin

PUT /api/warehouse/bins/{id}/deactivate
Authorization: Bearer {token}

number

required

The ID of the bin to deactivate.

Deactivated bins are hidden from handheld device selection and from creation forms on the web. Existing stock at the bin is not affected; a warehouse adjustment must be performed to move or clear the stock before permanent removal.

Set default bin

PUT /api/warehouse/bins/{id}/default
Authorization: Bearer {token}

number

required

The ID of the bin to set as default for its parent location.

Designates this bin as the default storage position within its location. Useful for bulk receiving operations where a specific bin is used as the primary staging area. Only one bin per location can be set as default at a time.

Business rules

Location codes and bin codes must be unique within their respective scopes (company for locations, parent location for bins). Attempting to create a duplicate code returns a 400 validation error.

A location must be active before bins can be created within it.
A location must have at least one active bin before it can serve as a valid stock destination in receiving or picking operations.
The isDefault flag for both locations and bins is mutually exclusive — setting a new default clears the flag from the previously designated record.
Bin codes must be scannable by handheld devices; avoid special characters that cannot be encoded in standard barcodes.

Error codes

HTTP Status	Meaning
`400`	Validation error — duplicate code, missing required fields, inactive parent location
`401`	Missing or expired JWT token
`500`	Internal server error

Authentication

Inventory

Commercial

Admin

Warehouse API: Locations, Bins, and Setup Status

Endpoints overview

Setup status

Location management

List locations

Create a location

Update a location

Activate a location

Deactivate a location

Set default location

Bin management

List bins for a location

Create a bin

Update a bin

Activate a bin

Deactivate a bin

Set default bin

Business rules

Error codes

Build docs developers (and LLMs) love

Authentication

Inventory

Commercial

Admin

Documentation Index

​Endpoints overview

​Setup status

​Location management

​List locations

​Create a location

​Update a location

​Activate a location

​Deactivate a location

​Set default location

​Bin management

​List bins for a location

​Create a bin

​Update a bin

​Activate a bin

​Deactivate a bin

​Set default bin

​Business rules

​Error codes

Build docs developers (and LLMs) love

Endpoints overview

Setup status

Location management

List locations

Create a location

Update a location

Activate a location

Deactivate a location

Set default location

Bin management

List bins for a location

Create a bin

Update a bin

Activate a bin

Deactivate a bin

Set default bin

Business rules

Error codes