Warehouse Locations

4 API calls in this section.

APIs for managing warehouse locations, providing capabilities to organize warehouse space hierarchically (zones, aisles, shelves, bins) for inventory management.

List Warehouse Locations

Warehousing / Warehouse Locations

GET/warehousing/locations

Retrieves warehouse locations with filtering options by warehouse, location type, status, and parent location. Supports pagination and hierarchical data exploration.

• User must have 'view:tenant' or 'manage:operations:tenant' permission

Response

• Returns a paginated list of locations with their hierarchical relationships

• Includes parent location details where applicable

• Provides available location types and statuses for filtering

• Includes pagination information (total count, current page, limit)

Query parameters

Parameter	Type	Description
tenant_id	string	UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant Example: {{tenant_id}}
warehouse_idRequired	string	Legacy: filter by warehouse UUID (optional). Overridden by column_filters.warehouse_id if both present. UUID of the warehouse to filter locations by Legacy: filter by warehouse UUID (optional). Overridden by column_filters.warehouse_id if both present. UUID of the warehouse to filter locations by
location_typeOptional	string	Legacy: filter by location type — zone | aisle | shelf | bin (optional). Overridden by column_filters.location_type if both present. Filter by location type (zone, aisle, shelf, bin) Legacy: filter by location type — zone | aisle | shelf | bin (optional). Overridden by column_filters.location_type if both present. Filter by location type (zone, aisle, shelf, bin)
statusOptional	string	Legacy: filter by status — active | inactive | maintenance (optional). Overridden by column_filters.status if both present. Filter by location status Legacy: filter by status — active | inactive | maintenance (optional). Overridden by column_filters.status if both present. Filter by location status
parent_idOptional	string	Legacy: filter by parent location UUID. Use 'null' for top-level locations (optional). Overridden by column_filters.parent_id if both present. Filter by parent location ID (use 'null' for top-level locations) Legacy: filter by parent location UUID. Use 'null' for top-level locations (optional). Overridden by column_filters.parent_id if both present. Filter by parent location ID (use 'null' for top-level locations)
searchOptional	string	Full-text search across code, name, barcode (optional) Full-text search across code, name, barcode (optional)
sort_byOptional	string	Sort column — code | name | created_at | updated_at (optional, default: updated_at) Sort column — code | name | created_at | updated_at (optional, default: updated_at) Example: updated_at
sort_orderOptional	string	Sort direction — asc | desc (optional, default: desc) Sort direction — asc | desc (optional, default: desc) Example: desc
column_filters	string	JSON object of column filters. Supported keys: warehouse_id (exact), parent_id (exact), location_type (exact), status (exact), code (contains), name (contains), barcode (contains). Takes precedence over legacy standalone params. JSON object of column filters. Supported keys: warehouse_id (exact), parent_id (exact), location_type (exact), status (exact), code (contains), name (contains), barcode (contains). Takes precedence over legacy standalone params.
pageOptional	string	Page number for pagination (optional, default: 1) Page number for pagination (default: 1) Page number for pagination (optional, default: 1) Page number for pagination (default: 1) Example: 1
limitOptional	string	Number of items per page (optional, default: 20) Number of items per page (default: 20) Number of items per page (optional, default: 20) Number of items per page (default: 20) Example: 20
languageOptional	string	Response language (optional, default: en) Response language (optional, default: en) Example: en

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/warehousing/locations?tenant_id=${TENANT_ID}&warehouse_id=&location_type=&status=&parent_id=&search=&sort_by=updated_at&sort_order=desc&column_filters=&page=1&limit=20&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json"

Response examples

200 · Success Response200 · Success Response — with column_filters + sort400 · Error - Warehouse ID Required404 · Error - Warehouse Not Found404 · Error - Tenant Not Found403 · Error - Insufficient Permissions500 · Error - Server Error

200OK

Response body

json

1{2  "success": true,3  "message": "Warehouse locations retrieved successfully",4  "locations": [5    {6      "id": "location-uuid-1",7      "location_type": "zone",8      "code": "Z-001",9      "barcode": null,10      "label_url": null,11      "name": "North Zone",12      "status": "active",13      "default_receiving_location": false,14      "position": {15        "area": "North",16        "floor": "1"17      },18      "warehouse": {19        "id": "warehouse-uuid",20        "code": "WH-01",21        "name": "Main Warehouse"22      },23      "parent": null24    },25    {26      "id": "location-uuid-2",27      "location_type": "aisle",28      "code": "A-101",29      "barcode": "BC-A101",30      "label_url": null,31      "name": "Aisle 101",32      "status": "active",33      "default_receiving_location": true,34      "position": {35        "number": "101",36        "section": "A"37      },38      "warehouse": {39        "id": "warehouse-uuid",40        "code": "WH-01",41        "name": "Main Warehouse"42      },43      "parent": {44        "id": "location-uuid-1",45        "code": "Z-001",46        "name": "North Zone",47        "location_type": "zone"48      }49    }50  ],51  "page": 1,52  "limit": 20,53  "total": 60,54  "stats": {55    "total": 60,56    "active": 50,57    "inactive": 5,58    "maintenance": 559  }60}

Create Warehouse Location

Warehousing / Warehouse Locations

POST/warehousing/locations

Creates a new warehouse location with hierarchical organization. Supports different location types (zone, aisle, shelf, bin) with appropriate parent-child relationships.

• User must have 'manage:operations:tenant' permission

Business rules

• Only one active, non-deleted location per warehouse can have default_receiving_location=true.

• Setting this flag to true clears the previous default receiving location in the same warehouse.

System-generated fields

• code is auto-generated from location_type and warehouse sequence

• barcode is auto-generated from warehouse code + location code

• label_url is generated asynchronously after the label job completes

Location Hierarchy Rules

• zone → aisle → shelf → bin (parent-child relationship)

Query parameters

Parameter	Type	Description
tenant_id	string	UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant Example: {{tenant_id}}

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
warehouse_id	string	—
location_type	string	—
name	string	—
parent_id	string	—
position	object	—
position.position	string	—
position.sequence	number	—
capacity	object	—
capacity.max_weight	number	—
capacity.max_volume	number	—
capacity.dimensions	object	—
capacity.dimensions.length	number	—

Show 13 more body fields

Additional body parameters

Parameter	Type	Description
capacity.dimensions.width	number	—
capacity.dimensions.height	number	—
capacity.item_limit	number	—
status	string	—
default_receiving_location	boolean	—
metadata	object	—
metadata.temperature_range	object	—
metadata.temperature_range.min	number	—
metadata.temperature_range.max	number	—
metadata.special_handling	array<string>	—
metadata.security_level	string	—
metadata.access_restrictions	array<string>	—
metadata.notes	string	—

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/warehousing/locations?tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "warehouse_id": "{{warehouse_id}}",6  "location_type": "bin",7  "name": "Storage Bin 1001",8  "parent_id": "{{parent_location_id}}",9  "position": {10    "position": "front",11    "sequence": 112  },13  "capacity": {14    "max_weight": 100,15    "max_volume": 50,16    "dimensions": {17      "length": 30,18      "width": 40,19      "height": 2020    },21    "item_limit": 2022  },23  "status": "active",24  "default_receiving_location": true,25  "metadata": {26    "temperature_range": {27      "min": 15,28      "max": 2529    },30    "special_handling": [31      "fragile",32      "dust-free"33    ],34    "security_level": "high",35    "access_restrictions": [36      "key-card",37      "supervisor"38    ],39    "notes": "For high-value items only"40  }41}'

Replace {{placeholders}} with your own values before sending.

Other request examples (1)

Request example 1

text

1{2  "warehouse_id": "uuid", // required3  "location_type": "string", // required (zone, aisle, shelf, bin)4  "name": "string", // optional, human-readable name5  "parent_id": "uuid", // optional, reference to parent location6  "position": {}, // required, position information based on location type7  "capacity": {}, // optional, storage capacity details8  "status": "string", // optional, defaults to "active"9  "default_receiving_location": true, // optional; warehouse fallback receiving location10  "metadata": {} // optional, additional location metadata11}

Response examples

201 · Success Response400 · Error - Missing Required Field400 · Error - Invalid Location Type400 · Error - Invalid Location Hierarchy400 · Error - Invalid Location Hierarchy404 · Error - Warehouse Not Found404 · Error - Parent Location Not Found404 · Error - Tenant Not Found403 · Error - Insufficient Permissions

201Success Response

Response body

json

1{2  "success": true,3  "message": "Warehouse location created successfully",4  "location": {5    "id": "new-location-uuid",6    "tenant_id": "tenant-uuid",7    "warehouse_id": "warehouse-uuid",8    "parent_id": "parent-location-uuid",9    "location_type": "bin",10    "code": "B-1001",11    "name": "Storage Bin 1001",12    "position": {13      "position": "front",14      "sequence": 115    },16    "capacity": {17      "max_weight": 100,18      "max_volume": 50,19      "dimensions": {20        "length": 30,21        "width": 40,22        "height": 2023      },24      "item_limit": 2025    },26    "status": "active",27    "default_receiving_location": true,28    "metadata": {29      "temperature_range": {30        "min": 15,31        "max": 2532      },33      "special_handling": [34        "fragile",35        "dust-free"36      ],37      "security_level": "high",38      "access_restrictions": [39        "key-card",40        "supervisor"41      ],42      "notes": "For high-value items only"43    },44    "created_at": "2023-06-01T10:00:00Z",45    "updated_at": "2023-06-01T10:00:00Z",46    "deleted_at": null47  }48}

Get Warehouse Location

Warehousing / Warehouse Locations

GET/warehousing/locations/:id

Retrieves detailed information about a specific warehouse location by its ID or barcode, including parent location and warehouse details.

• User must have 'view:tenant' or 'manage:operations:tenant' permission

Frontend integration contract

• For location barcode scans in receiving, call GET /warehousing/locations/:barcode?search_type=barcode&warehouse_id={{warehouse_id}}.

• On success, replace the currently selected receiving location with location.id.

• Handle HTTP 404 as an invalid or wrong-warehouse location scan.

Response

• Returns detailed location information

• Includes default_receiving_location to indicate whether this is the warehouse fallback receiving location

• Includes parent location data (if applicable)

• Includes warehouse information

Path parameters

Parameter	Type	Description
idRequired	string	UUID of the location to retrieve (required) UUID of the location to retrieve, or barcode when search_type=barcode UUID of the location to retrieve (required) UUID of the location to retrieve, or barcode when search_type=barcode

Query parameters

Parameter	Type	Description
tenant_id	string	UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant Example: {{tenant_id}}
search_typeOptional	string	Optional. Set to 'barcode' to treat :id as barcode Set to barcode to treat :id as a location barcode Optional. Set to 'barcode' to treat :id as barcode Set to barcode to treat :id as a location barcode
warehouse_idOptional	string	Optional. Restricts the lookup to one warehouse. Use this when scanning a location barcode from a receiving flow. Restrict lookup to a warehouse. Frontend should pass this during receiving location scans so a scanned location from another warehouse returns 404. Optional. Restricts the lookup to one warehouse. Use this when scanning a location barcode from a receiving flow. Restrict lookup to a warehouse. Frontend should pass this during receiving location scans so a scanned location from another warehouse returns 404.

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/warehousing/locations/${ID}?tenant_id=${TENANT_ID}&search_type=&warehouse_id=" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json"

Response examples

200 · Success Response400 · Error - Location ID Required404 · Error - Location Not Found404 · Error - Tenant Not Found403 · Error - Insufficient Permissions

200Success Response

Response body

json

1{2  "success": true,3  "message": "Location retrieved successfully",4  "location": {5    "id": "location-uuid",6    "tenant_id": "tenant-uuid",7    "warehouse_id": "warehouse-uuid",8    "parent_id": "parent-location-uuid",9    "location_type": "bin",10    "code": "B-1001",11    "name": "Storage Bin 1001",12    "position": {13      "position": "front",14      "sequence": 115    },16    "capacity": {17      "max_weight": 100,18      "max_volume": 50,19      "dimensions": {20        "length": 30,21        "width": 40,22        "height": 2023      },24      "item_limit": 2025    },26    "status": "active",27    "default_receiving_location": true,28    "metadata": {29      "temperature_range": {30        "min": 15,31        "max": 2532      },33      "special_handling": [34        "fragile",35        "dust-free"36      ],37      "security_level": "high",38      "access_restrictions": [39        "key-card",40        "supervisor"41      ],42      "notes": "For high-value items only"43    },44    "created_at": "2023-06-01T10:00:00Z",45    "updated_at": "2023-06-01T10:00:00Z",46    "deleted_at": null,47    "parent": {48      "id": "parent-location-uuid",49      "location_type": "shelf",50      "code": "S-101",51      "name": "Shelf 101"52    },53    "warehouse": {54      "id": "warehouse-uuid",55      "name": "Main Warehouse",56      "code": "WH-001"57    }58  }59}

Update Warehouse Location

Warehousing / Warehouse Locations

PUT/warehousing/locations/:id

Updates an existing warehouse location with new information. Only specified fields will be updated.

• User must have 'manage:operations:tenant' permission

Business rules

• Only one active, non-deleted location per warehouse can have default_receiving_location=true.

Note

• Only specified fields are updated and warehouse_id cannot be changed.

Path parameters

Parameter	Type	Description
idRequired	string	UUID of the location to update (required) UUID of the location to update (required)

Query parameters

Parameter	Type	Description
tenant_id	string	UUID of the tenant (required if not in auth) UUID of the tenant (required if not in auth) Example: {{tenant_id}}

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
name	string	—
location_type	string	—
parent_id	string	—
status	string	—
default_receiving_location	boolean	—
position	object	—
position.position	string	—
position.sequence	number	—
capacity	object	—
capacity.max_weight	number	—
capacity.item_limit	number	—
metadata	object	—

Show 2 more body fields

Additional body parameters

Parameter	Type	Description
metadata.notes	string	—
metadata.security_level	string	—

Staging

Request

curl

1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/warehousing/locations/${ID}?tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "name": "Updated Location Name",6  "location_type": "bin",7  "parent_id": "{{parent_location_id}}",8  "status": "active",9  "default_receiving_location": true,10  "position": {11    "position": "back",12    "sequence": 213  },14  "capacity": {15    "max_weight": 150,16    "item_limit": 2517  },18  "metadata": {19    "notes": "Updated location notes",20    "security_level": "medium"21  }22}'

Replace {{placeholders}} with your own values before sending.

Other request examples (1)

Request example 1

json

1{2  "name": "string",3  "status": "string",4  "default_receiving_location": true,5  "position": {},6  "capacity": {},7  "metadata": {}8}

Response examples

200 · Success Response400 · Error - Location ID Required400 · Error - Invalid Position Structure404 · Error - Location Not Found404 · Error - Tenant Not Found403 · Error - Insufficient Permissions400 · Error - Invalid Request Body

200Success Response

Response body

json

1{2  "success": true,3  "message": "Location updated successfully",4  "location": {5    "id": "location-uuid",6    "tenant_id": "tenant-uuid",7    "warehouse_id": "warehouse-uuid",8    "parent_id": "parent-location-uuid",9    "location_type": "bin",10    "code": "B001",11    "barcode": "WLCWH001B001",12    "label_url": null,13    "name": "Updated Location Name",14    "position": {15      "position": "back",16      "sequence": 217    },18    "capacity": {19      "max_weight": 150,20      "item_limit": 2521    },22    "status": "active",23    "default_receiving_location": true,24    "metadata": {25      "notes": "Updated location notes",26      "security_level": "medium"27    },28    "created_at": "2023-06-01T10:00:00Z",29    "updated_at": "2023-06-02T10:00:00Z",30    "deleted_at": null31  }32}