Skip to main content

​
Overview

The Locations API enables management of hierarchical location structures within containers. Locations can be nested to create organizational hierarchies, allowing for precise tracking of where inventory items are stored.

​
Endpoints

​
Get Locations

Retrieves all locations associated with a specific container. 
GET /containers/{containerId}/locations

​
Path Parameters

​
containerId
integer
required
The ID of the container whose locations to retrieve

​
Response

​
data
Location[]
Array of location objects

​
Example Request

const response = await fetch('/containers/42/locations', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

const { data } = await response.json();

​
Example Response

{
  "data": [
    {
      "id": 1,
      "name": "Warehouse A",
      "description": "Main warehouse facility",
      "containerId": 42,
      "parentId": null,
      "children": [
        {
          "id": 2,
          "name": "Shelf 1",
          "description": "First shelf in warehouse",
          "containerId": 42,
          "parentId": 1,
          "children": []
        }
      ]
    }
  ]
}

​
Error Responses

​
401
error
Unauthorized - Authentication required or token invalid
​
404
error
Container not found

​
Create Location

Creates a new location within a container. 
POST /locations

​
Request Body

​
container_id
integer
required
ID of the container to create the location in
​
name
string
required
Name of the location
​
description
string
Optional description of the location
​
parent_id
integer
ID of the parent location (omit for root-level location)

​
Response

​
data
Location
The newly created location object

​
Example Request

const response = await fetch('/locations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    container_id: 42,
    name: 'Warehouse B',
    description: 'Secondary storage facility',
    parent_id: null
  })
});

const { data } = await response.json();

​
Example Response

{
  "data": {
    "id": 5,
    "name": "Warehouse B",
    "description": "Secondary storage facility",
    "containerId": 42,
    "parentId": null
  }
}

​
Error Responses

​
201
success
Location created successfully
​
401
error
Unauthorized - Invalid or missing authentication token
​
400
error
Bad request - Invalid parent_id or missing required fields

​
Update Location

Updates an existing location’s details. 
PATCH /locations/{locationId}

​
Path Parameters

​
locationId
integer
required
The ID of the location to update

​
Request Body

​
name
string
required
Updated name of the location
​
description
string
Updated description
​
parent_id
integer
Updated parent location ID (use null to make it a root location)

​
Response

​
data
Location
The updated location object

​
Example Request

const response = await fetch('/locations/5', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Warehouse B - Expanded',
    description: 'Expanded secondary storage facility',
    parent_id: null
  })
});

const { data } = await response.json();

​
Example Response

{
  "data": {
    "id": 5,
    "name": "Warehouse B - Expanded",
    "description": "Expanded secondary storage facility",
    "containerId": 42,
    "parentId": null
  }
}

​
Error Responses

​
200
success
Location updated successfully
​
401
error
Unauthorized - Authentication required
​
404
error
Location not found
​
400
error
Bad request - Invalid parent_id (would create circular hierarchy)

​
Delete Location

Deletes a location from the system. 
DELETE /locations/{locationId}

​
Path Parameters

​
locationId
integer
required
The ID of the location to delete

​
Response

Returns status code 204 (No Content) or 200 (OK) on successful deletion.

​
Example Request

const response = await fetch('/locations/5', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

if (response.status === 204) {
  console.log('Location deleted successfully');
}

​
Error Responses

​
204
success
Location deleted successfully (no content returned)
​
200
success
Location deleted successfully
​
401
error
Unauthorized - Authentication required
​
404
error
Location not found
​
409
error
Conflict - Cannot delete location with child locations or assigned items

​
Business Logic Notes

​
Hierarchical Structure

  • Locations support unlimited nesting depth through the parent_id field
  • The children array is populated recursively when retrieving locations
  • Root-level locations have parent_id set to null

​
Deletion Rules

  • Locations with child locations must have children removed first
  • Locations with assigned inventory items cannot be deleted until items are reassigned
  • Consider implementing soft deletes for audit trail purposes

​
Performance Considerations

  • The children array is not included in toJson() to prevent circular serialization issues
  • For deep hierarchies, consider implementing pagination or lazy loading of child locations
  • The getLocationsCount() method fetches all locations and returns the count - consider server-side counting for large datasets

​
Access Control

  • All location operations require valid JWT authentication
  • Users can only access locations within containers they have permission to view
  • Container ownership determines location management permissions

Build docs developers (and LLMs) love

Get started for freeTalk to us