M3 API Reference

The M3 Inventory API provides endpoints for managing inventory items, locations, stock movements, and alerts.

Base URL

Production: https://m3.inspiringlivingsolutions.com/api
Development: http://localhost:3000/api

Authentication

Requires Clerk session authentication.

Endpoints

Inventory Items

List Items

GET /items

Query Parameters:

Parameter	Type	Description
page	number	Page number
limit	number	Items per page
category	string	Filter by category
propertyId	string	Filter by property
locationId	string	Filter by location
condition	string	Filter by condition
lowStock	boolean	Only low stock items

Response:

{
  "data": [
    {
      "id": "uuid",
      "name": "Bath Towels - White",
      "category": "LINENS",
      "quantity": 24,
      "minStock": 10,
      "condition": "GOOD",
      "property": { "id": "uuid", "name": "Villa Sunrise" },
      "location": { "id": "uuid", "name": "Linen Closet" }
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 500 }
}

Get Item

GET /items/:id

Create Item

POST /items

Body:

{
  "name": "Bath Towels - White",
  "sku": "TWL-BTH-WHT",
  "category": "LINENS",
  "propertyId": "uuid",
  "locationId": "uuid",
  "quantity": 24,
  "unit": "EACH",
  "minStock": 10,
  "maxStock": 50,
  "condition": "NEW",
  "unitCost": 250,
  "currency": "THB"
}

Update Item

PATCH /items/:id

Delete Item

DELETE /items/:id

---

Stock Movements

Record Movement

POST /movements

Body:

{
  "itemId": "uuid",
  "type": "USE",
  "quantity": 5,
  "notes": "Used for turnover",
  "referenceType": "WORK_ORDER",
  "referenceId": "wo-uuid"
}

Movement Types:

• INITIAL
• PURCHASE
• USE
• DAMAGE
• LOSS
• TRANSFER_IN
• TRANSFER_OUT
• ADJUSTMENT
• RETURN

List Movements

GET /movements

Query Parameters:

Parameter	Type	Description
itemId	string	Filter by item
type	string	Filter by type
startDate	string	From date
endDate	string	To date

---

Transfers

Create Transfer

POST /transfers

Body:

{
  "sourceLocationId": "uuid",
  "destinationLocationId": "uuid",
  "items": [
    { "itemId": "uuid", "quantity": 5 },
    { "itemId": "uuid", "quantity": 3 }
  ],
  "notes": "Moving stock to Villa B"
}

Receive Transfer

POST /transfers/:id/receive

Body:

{
  "items": [
    { "itemId": "uuid", "receivedQuantity": 5 },
    { "itemId": "uuid", "receivedQuantity": 2, "notes": "1 damaged" }
  ]
}

---

Locations

List Properties

GET /properties

List Locations

GET /locations

Query Parameters:

Parameter	Type	Description
propertyId	string	Filter by property
parentId	string	Filter by parent
type	string	Filter by type

Create Location

POST /locations

Body:

{
  "name": "Master Bedroom",
  "type": "ROOM",
  "propertyId": "uuid",
  "parentId": "uuid",
  "description": "Main floor master"
}

---

Categories

List Categories

GET /categories

Create Category

POST /categories

Body:

{
  "name": "Pool Equipment",
  "parentId": "uuid",
  "description": "Pool and spa items"
}

---

Alerts

List Alerts

GET /alerts

Query Parameters:

Parameter	Type	Description
status	string	ACTIVE, ACKNOWLEDGED, RESOLVED
type	string	LOW_STOCK, CONDITION, EXPIRY
propertyId	string	Filter by property

Acknowledge Alert

POST /alerts/:id/acknowledge

Resolve Alert

POST /alerts/:id/resolve

Body:

{
  "action": "Ordered 20 units",
  "notes": "PO-12345 created"
}

---

Reports

Stock Report

GET /reports/stock

Movement Report

GET /reports/movements

Valuation Report

GET /reports/valuation

---

Error Responses

{
  "error": {
    "code": "INSUFFICIENT_STOCK",
    "message": "Not enough stock for this movement",
    "details": {
      "available": 5,
      "requested": 10
    }
  }
}