Storage Locations API Reference

This page documents the Storage Locations endpoints in the Core API.

List Storage Locations

Returns all storage locations associated with a specific place.

URL: /v1/places/{placeId}/storage-location

Method: GET

Auth required: Yes

Example Request:

curl -X GET "https://api.uos.example.com/v1/places/place-123/storage-location" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response:

  • Code: 200 OK
  • Content:
{
  "data": [
    {
      "id": "sl-123",
      "place_id": "place-123",
      "name": "Main Ambient Storage",
      "temperature_type": "ambient",
      "description": "Main storage area for non-refrigerated items",
      "created_at": "2023-06-01T10:00:00Z",
      "updated_at": "2023-06-01T10:00:00Z"
    },
    {
      "id": "sl-456",
      "place_id": "place-123",
      "name": "Refrigerated Section A",
      "temperature_type": "cooled",
      "description": "Refrigerated storage for dairy and produce",
      "created_at": "2023-06-01T10:05:00Z",
      "updated_at": "2023-06-01T10:05:00Z"
    },
    {
      "id": "sl-789",
      "place_id": "place-123",
      "name": "Freezer Section",
      "temperature_type": "frozen",
      "description": "Freezer for frozen items",
      "created_at": "2023-06-01T10:10:00Z",
      "updated_at": "2023-06-01T10:10:00Z"
    }
  ],
  "count": 3
}

Error Responses:

  • Code: 403 Forbidden
    • Content: { "error": "No access to the specified channel" }
  • Code: 404 Not Found
    • Content: { "error": "Place not found" }

Get Storage Location

Returns details of a specific storage location.

URL: /v1/places/{placeId}/storage-location/{id}

Method: GET

Auth required: Yes

Example Request:

curl -X GET "https://api.uos.example.com/v1/places/place-123/storage-location/sl-123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response:

  • Code: 200 OK
  • Content:
{
  "id": "sl-123",
  "place_id": "place-123",
  "name": "Main Ambient Storage",
  "temperature_type": "ambient",
  "description": "Main storage area for non-refrigerated items",
  "created_at": "2023-06-01T10:00:00Z",
  "updated_at": "2023-06-01T10:00:00Z"
}

Error Responses:

  • Code: 403 Forbidden
    • Content: { "error": "No access to the specified channel" }
  • Code: 404 Not Found
    • Content: { "error": "Place or storage location not found" }

Create Storage Location

Creates a new storage location for a place.

URL: /v1/places/{placeId}/storage-location

Method: POST

Auth required: Yes

Request Body:

FieldTypeRequiredDescription
namestringYesName of the storage location
temperature_typestringYesTemperature type: "ambient", "cooled", or "frozen"
descriptionstringNoOptional description of the storage location

Example Request:

curl -X POST "https://api.uos.example.com/v1/places/place-123/storage-location" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Back Room Refrigerator",
    "temperature_type": "cooled",
    "description": "Additional refrigerated storage in the back room"
  }'

Success Response:

  • Code: 202 Accepted
  • Content:
{
  "message": "Storage location creation queued",
  "job_id": "job-123456",
  "status": "processing"
}

Error Responses:

  • Code: 400 Bad Request
    • Content: { "error": "Missing required fields or invalid temperature type" }
  • Code: 403 Forbidden
    • Content: { "error": "No access to the specified channel" }
  • Code: 404 Not Found
    • Content: { "error": "Place not found" }
  • Code: 409 Conflict
    • Content: { "error": "A storage location with this name already exists for this place" }

Update Storage Location

Updates an existing storage location.

URL: /v1/places/{placeId}/storage-location/{id}

Method: PATCH

Auth required: Yes

Request Body:

FieldTypeRequiredDescription
namestringNoName of the storage location
temperature_typestringNoTemperature type: "ambient", "cooled", or "frozen"
descriptionstringNoDescription of the storage location

Example Request:

curl -X PATCH "https://api.uos.example.com/v1/places/place-123/storage-location/sl-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Ambient Storage - Updated",
    "description": "Updated description for the main ambient storage area"
  }'

Success Response:

  • Code: 202 Accepted
  • Content:
{
  "message": "Storage location update queued",
  "job_id": "job-123457",
  "status": "processing"
}

Error Responses:

  • Code: 400 Bad Request
    • Content: { "error": "Invalid temperature type" }
  • Code: 403 Forbidden
    • Content: { "error": "No access to the specified channel" }
  • Code: 404 Not Found
    • Content: { "error": "Place or storage location not found" }
  • Code: 409 Conflict
    • Content: { "error": "A storage location with this name already exists for this place" }

Delete Storage Location

Deletes a storage location.

URL: /v1/places/{placeId}/storage-location/{id}

Method: DELETE

Auth required: Yes

Example Request:

curl -X DELETE "https://api.uos.example.com/v1/places/place-123/storage-location/sl-123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response:

  • Code: 202 Accepted
  • Content:
{
  "message": "Storage location deletion queued",
  "job_id": "job-123458",
  "status": "processing"
}

Error Responses:

  • Code: 403 Forbidden
    • Content: { "error": "No access to the specified channel" }
  • Code: 404 Not Found
    • Content: { "error": "Place or storage location not found" }
  • Code: 409 Conflict
    • Content: { "error": "Storage location is currently in use and cannot be deleted" }

Assign Storage Location to Order Items

Assigns a storage location to items in an order.

URL: /v1/orders/{orderId}/items/storage-locations

Method: POST

Auth required: Yes

Request Body:

FieldTypeRequiredDescription
itemsarrayYesArray of items with storage location assignments

Example Request:

curl -X POST "https://api.uos.example.com/v1/orders/order-123/items/storage-locations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "item_id": "item-123",
        "storage_location_id": "sl-123"
      },
      {
        "item_id": "item-456",
        "storage_location_id": "sl-456"
      }
    ]
  }'

Success Response:

  • Code: 200 OK
  • Content:
{
  "success": true,
  "message": "Storage locations assigned to order items",
  "order_id": "order-123",
  "assignments": [
    {
      "item_id": "item-123",
      "storage_location_id": "sl-123",
      "storage_location_name": "Main Ambient Storage"
    },
    {
      "item_id": "item-456",
      "storage_location_id": "sl-456",
      "storage_location_name": "Refrigerated Section A"
    }
  ]
}

Error Responses:

  • Code: 400 Bad Request
    • Content: { "error": "Invalid request data" }
  • Code: 403 Forbidden
    • Content: { "error": "No access to the specified order" }
  • Code: 404 Not Found
    • Content: { "error": "Order, item, or storage location not found" }
  • Code: 409 Conflict
    • Content: { "error": "Order status does not allow storage location assignment" }

Bulk Import Storage Locations (CSV)

Import storage locations from a CSV file. This operation will clear all existing storage locations for the specified place and import new locations from the CSV.

URL: /v1/places/{placeId}/storage-location/import

Method: POST

Auth required: Yes (Admin access required)

Content-Type: multipart/form-data

File Limit: 10MB maximum

CSV Format Requirements:

Required Columns

  • name - The storage location identifier (must be unique per place)

Optional Columns

  • sub_type - Temperature type code (0,2=ambient, 1=frozen, 3=cooled)
  • description - Location description
  • code - Location code
  • abbreviation - Location abbreviation
  • id - Original ID (stored in metadata)

Temperature Type Mapping

  • sub_type: 0 → ambient (default/unknown)
  • sub_type: 1 → frozen
  • sub_type: 2 → ambient
  • sub_type: 3 → cooled

Example CSV Format:

id,name,sub_type,description,code,abbreviation
1,Ambient Storage,2,Main ambient storage area,AMB,AMB
2,Freezer A01,1,Freezer section A01,FRZ-A01,FA01
3,Cooler B01,3,Refrigerated section B01,COOL-B01,CB01

Example Request:

curl -X POST "https://api.uos.example.com/v1/places/place-123/storage-location/import" \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -F "file=@storage_locations.csv"

Success Response:

  • Code: 200 OK
  • Content:
{
  "success": true,
  "message": "Storage locations imported successfully",
  "results": {
    "total_processed": 25,
    "created": 23,
    "updated": 0,
    "skipped": 2,
    "errors": []
  },
  "details": {
    "skipped_items": [
      {
        "row": 5,
        "name": "Duplicate Location",
        "reason": "Duplicate name in CSV"
      }
    ]
  }
}

Error Responses:

  • Code: 400 Bad Request

    • Content:
    {
  "error": "Bad Request",
  "message": "CSV file is required",
  "format_requirements": {
    "required_columns": ["name"],
    "optional_columns": ["sub_type", "description", "code", "abbreviation", "id"],
    "temperature_mapping": {
      "0": "ambient",
      "1": "frozen",
      "2": "ambient",
      "3": "cooled"
    }
  }
}

  • Code: 400 Bad Request (Invalid CSV)

    • Content:
    {
  "error": "Bad Request",
  "message": "CSV validation failed",
  "validation_errors": [
    "Missing required column: name",
    "Invalid sub_type value at row 3: 'invalid'"
  ],
  "validation_warnings": [
    "Empty description at row 5"
  ],
  "format_requirements": { ... }
}

  • Code: 403 Forbidden

    • Content: { "error": "Admin access required" }

  • Code: 404 Not Found

    • Content: { "error": "Place not found" }

Important Notes:

  • ⚠️ This operation clears ALL existing storage locations for the place before importing
  • Duplicate names within the CSV file will result in skipped rows (only the first occurrence is imported)
  • The import operation is atomic - if critical errors occur, no changes are made
  • Maximum file size is 10MB
  • Only CSV files are accepted (MIME types: text/csv, application/csv or .csv extension)
Last Updated: