MIPOS API Documentation

Complete REST API reference for the MIPOS Point of Sale System

Base URL: http://localhost:3000/api

About MIPOS

MIPOS is a comprehensive Point of Sale system designed for retail businesses. It provides inventory management, order processing, customer management, and multi-store support.

Response Format

All API responses are in JSON format with a consistent structure:

{ "success": true, "message": "Operation successful", "data": { ... } }

Authentication

How to authenticate API requests

Bearer Token Authentication

Include the access token in the Authorization header for protected endpoints.

Request Header

Authorization: Bearer <access_token>

User Roles

The API supports role-based access control with the following roles:

Super Admin Admin Manager Cashier Inventory Clerk

Auth

Authentication and account management endpoints

POST /auth/login User login ▼
Request Body
{ "username": "[email protected]", "password": "SecurePassword123" }
Response (200 OK)
{ "success": true, "message": "Login successful", "data": { "user": { "id": 1, "username": "[email protected]", "email": "[email protected]", "is_active": true, "role_id": 2, "last_login": "2026-03-20T10:30:00.000Z", "role": { "id": 2, "name": "Admin" }, "company": { "id": 1, "name": "Acme Corporation", "email": "[email protected]" } }, "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "permissions": [ { "action_key": "products.view" }, { "action_key": "products.create" } ], "access": null } }
POST /auth/logout User logout
Authenticated
▼
Request Headers
Authorization: Bearer <access_token>
Response (200 OK)
{ "success": true, "message": "Logout successful" }
POST /auth/pos/login POS terminal login ▼
Request Body
{ "username": "[email protected]", "password": "CashierPass123" }
Response (200 OK)
{ "success": true, "message": "Login successful", "data": { "user": { "id": 5, "username": "[email protected]", "role": { "id": 4, "name": "Cashier" } }, "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "permissions": [...], "access": { "stores": [{ "id": 1, "name": "Main Store" }], "storages": [{ "id": 1, "name": "Warehouse A" }] } } }
POST /auth/signup User registration ▼
Request Body
{ "type": "email", "email": "[email protected]", "password": "SecurePassword123", "first_name": "John", "last_name": "Doe", "company_name": "My New Company" }
Response (201 Created)
{ "success": true, "message": "Registration successful. Please verify your email.", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "code": "USR-0001", "email": "[email protected]", "first_name": "John", "last_name": "Doe" } }
POST /auth/otp/verify Verify OTP code ▼
Request Body
{ "type": "email", "username": "[email protected]", "otp": "123456" }
Response (200 OK)
{ "success": true, "message": "OTP verified successfully" }
POST /auth/otp/request Request OTP code ▼
Request Body
{ "type": "email", "username": "[email protected]" }
Response (200 OK)
{ "success": true, "message": "OTP sent successfully" }
POST /auth/password/forgot Request password reset ▼
Request Body
{ "type": "email", "username": "[email protected]" }
Response (200 OK)
{ "success": true, "message": "Password reset OTP sent" }

Lookups

Dropdown and autocomplete data endpoints

POST /lookup/companies Search companies
Super Admin
▼
Request Body
{ "search": "acme", "filters": { "is_deleted": false } }
Response (200 OK)
{ "success": true, "data": [ { "id": 1, "name": "Acme Corporation" }, { "id": 2, "name": "Acme Retail" } ] }
POST /lookup/roles Search roles
Super Admin Admin Manager
▼
Request Body
{ "search": "" }
Response (200 OK)
{ "success": true, "data": [ { "id": 2, "name": "Admin" }, { "id": 3, "name": "Manager" }, { "id": 4, "name": "Cashier" }, { "id": 5, "name": "Inventory Clerk" } ] }
POST /lookup/stores Search stores
Super Admin Admin Manager
▼
Request Body
{ "search": "main", "filters": { "company_id": 1 } }
Response (200 OK)
{ "success": true, "data": [ { "id": 1, "name": "Main Store" }, { "id": 3, "name": "Main Branch" } ] }
POST /lookup/storages Search storages
Super Admin Admin Manager Cashier Inventory
▼
Request Body
{ "search": "warehouse", "filters": { "store_id": 1 } }
Response (200 OK)
{ "success": true, "data": [ { "id": 1, "name": "Main Warehouse" }, { "id": 2, "name": "Warehouse B" } ] }
POST /lookup/categories Search categories
Super Admin Admin Manager Cashier Inventory
▼
Request Body
{ "search": "electronics" }
Response (200 OK)
{ "success": true, "data": [ { "id": 1, "name": "Electronics" }, { "id": 5, "name": "Consumer Electronics" } ] }
POST /lookup/brands Search brands
Super Admin Admin Manager Cashier Inventory
▼
Request Body
{ "search": "apple" }
Response (200 OK)
{ "success": true, "data": [ { "id": 1, "name": "Apple" } ] }

Dashboard

Dashboard statistics endpoints

GET /admin/dashboard/super-admin Super Admin dashboard stats
Super Admin
▼
Response (200 OK)
{ "success": true, "data": { "total_companies": 150, "total_stores": 450, "total_users": 2500, "total_products": 15000, "total_orders": 50000, "revenue_today": 125000.00 } }
GET /admin/dashboard/admin Admin dashboard stats
Admin
▼
Response (200 OK)
{ "success": true, "data": { "total_stores": 5, "total_products": 500, "total_orders": 1200, "revenue_today": 8500.00, "low_stock_items": 25 } }
GET /admin/dashboard/manager Manager dashboard stats
Manager
▼
Response (200 OK)
{ "success": true, "data": { "store_name": "Main Store", "orders_today": 45, "revenue_today": 3500.00, "low_stock_items": 8, "pending_orders": 3 } }
GET /admin/dashboard/cashier Cashier dashboard stats
Cashier
▼
Response (200 OK)
{ "success": true, "data": { "my_orders_today": 12, "my_sales_today": 850.00, "store_status": "open" } }

Companies

Company management endpoints (Admin)

POST /admin/companies/search Search companies
Super Admin
▼
Request Body
{ "search": "acme", "page": 1, "limit": 10, "filters": { "is_deleted": false } }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": 1, "name": "Acme Corporation", "email": "[email protected]", "phone": "+1234567890", "address": "123 Business St", "logo": "https://cdn.example.com/logo.png", "created_at": "2026-01-15T08:00:00.000Z" } ], "pagination": { "total": 1, "page": 1, "limit": 10, "totalPages": 1 } } }
GET /admin/companies/:id Get company by ID
Super Admin
▼
URL Parameters
id: 1 // Company ID
Response (200 OK)
{ "success": true, "data": { "id": 1, "name": "Acme Corporation", "email": "[email protected]", "phone": "+1234567890", "address": "123 Business St", "logo": "https://cdn.example.com/logo.png", "created_at": "2026-01-15T08:00:00.000Z", "updated_at": "2026-03-10T14:30:00.000Z" } }
POST /admin/companies Create company
Super Admin
▼
Request Body
{ "name": "New Company Inc", "email": "[email protected]", "phone": "+1987654321", "address": "456 Corporate Ave", "logo": "https://cdn.example.com/newlogo.png", "owner_email": "[email protected]", "owner_name": "John Smith" }
Response (201 Created)
{ "success": true, "message": "Company created successfully", "data": { "id": 2, "name": "New Company Inc", "email": "[email protected]" } }
PUT /admin/companies/:id Update company
Super Admin
▼
Request Body
{ "name": "Updated Company Name", "email": "[email protected]", "phone": "+1555555555", "address": "789 New Address" }
Response (200 OK)
{ "success": true, "message": "Company updated successfully", "data": { "id": 1, "name": "Updated Company Name" } }
DELETE /admin/companies/:id Delete company
Super Admin
▼
URL Parameters
id: 1 // Company ID to delete
Response (200 OK)
{ "success": true, "message": "Company deleted successfully" }

Packages

Subscription package management (Super Admin)

POST /admin/packages Search packages
Super Admin
▼
Request Body
{ "search": "premium", "page": 1, "limit": 10 }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": "uuid", "name": "Premium", "price": 99.99, "max_stores": 10, "max_products": 10000, "max_users": 50, "is_active": true } ] } }
GET /admin/packages/:id Get package details
Super Admin
▼
Response (200 OK)
{ "success": true, "data": { "id": "uuid", "name": "Premium", "description": "Premium plan with advanced features", "price": 99.99, "billing_cycle": "monthly", "features": { ... } } }
POST /admin/packages/create Create package
Super Admin
▼
Request Body
{ "name": "Enterprise", "price": 299.99, "billing_cycle": "monthly", "max_stores": 100, "max_products": 100000, "max_users": 500 }
PUT /admin/packages/:id Update package
Super Admin
▼
Request Body
{ "name": "Enterprise Pro", "price": 349.99 }
PUT /admin/packages/:id/activate Activate package
Super Admin
▼
Response (200 OK)
{ "success": true, "message": "Package activated" }
PUT /admin/packages/:id/deactivate Deactivate package
Super Admin
▼
Response (200 OK)
{ "success": true, "message": "Package deactivated" }

Stores

Store management endpoints (Admin)

POST /admin/stores/search Search stores
Super Admin Admin
▼
Request Body
{ "search": "main", "page": 1, "limit": 10, "filters": { "company_id": 1, "is_deleted": false } }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": 1, "name": "Main Store", "address": "123 Main St", "phone": "+1234567890", "company_id": 1, "is_active": true } ], "pagination": { "total": 1, "page": 1, "limit": 10, "totalPages": 1 } } }
GET /admin/stores/:id Get store by ID
Super Admin Admin
▼
Response (200 OK)
{ "success": true, "data": { "id": 1, "name": "Main Store", "address": "123 Main St", "phone": "+1234567890", "company_id": 1, "is_active": true, "settings": { "tax_rate": 10, "currency": "USD" } } }
POST /admin/stores Create store
Super Admin
▼
Request Body
{ "name": "New Branch Store", "address": "456 Branch Ave", "phone": "+1987654321", "company_id": 1 }
Response (201 Created)
{ "success": true, "message": "Store created successfully", "data": { "id": 2, "name": "New Branch Store" } }
PUT /admin/stores/:id Update store
Super Admin
▼
Request Body
{ "name": "Updated Store Name", "address": "789 Updated St", "is_active": true }
Response (200 OK)
{ "success": true, "message": "Store updated successfully" }
DELETE /admin/stores/:id Delete store
Super Admin
▼
Response (200 OK)
{ "success": true, "message": "Store deleted successfully" }

Storages

Storage/Warehouse management endpoints (Admin)

POST /admin/storages/search Search storages
Super Admin Admin Manager
▼
Request Body
{ "search": "warehouse", "page": 1, "limit": 10, "filters": { "is_deleted": false } }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": 1, "name": "Main Warehouse", "address": "100 Storage Blvd", "store_id": 1, "is_active": true } ], "pagination": { "total": 1, "page": 1, "limit": 10, "totalPages": 1 } } }
POST /admin/storages Create storage
Super Admin
▼
Request Body
{ "name": "New Warehouse", "address": "200 Industrial Park", "store_id": 1 }
Response (201 Created)
{ "success": true, "message": "Storage created successfully", "data": { "id": 2, "name": "New Warehouse" } }
PUT /admin/storages/:id Update storage
Super Admin
▼
Request Body
{ "name": "Updated Warehouse Name", "address": "300 New Location", "is_active": true }
Response (200 OK)
{ "success": true, "message": "Storage updated successfully" }

Products

Product management endpoints (Admin)

POST /admin/products/all-products/search Search products
Admin Manager Inventory
▼
Request Body
{ "search": "iPhone", "page": 1, "limit": 10, "filters": { "category_id": 1, "brand_id": 2, "storage_id": "1", "status": "active", "is_deleted": false } }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "iPhone 15 Pro", "description": "Latest Apple smartphone", "category": { "id": 1, "name": "Electronics" }, "brand": { "id": 2, "name": "Apple" }, "variants": [ { "id": 1, "sku": "IPH15PRO-128-BLK", "price": 999.99, "stock": 50 } ] } ], "pagination": { "total": 1, "page": 1, "limit": 10, "totalPages": 1 } } }
GET /admin/products/all-products/:id Get product by ID
Admin Manager Inventory
▼
Response (200 OK)
{ "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "iPhone 15 Pro", "description": "Latest Apple smartphone", "category_id": 1, "brand_id": 2, "storage_id": 1, "variants": [ { "id": 1, "sku": "IPH15PRO-128-BLK", "price": 999.99, "cost": 800.00, "stock": 50, "options": [ { "type": "Color", "value": "Black" }, { "type": "Storage", "value": "128GB" } ] } ], "images": [ { "id": "img-001", "url": "https://cdn.example.com/iphone.jpg", "is_thumbnail": true } ] } }
POST /admin/products Create product
Admin Manager Inventory
▼
Request Body
{ "name": "Samsung Galaxy S24", "description": "Latest Samsung flagship phone", "storage_id": 1, "category_id": 1, "brand_id": 3, "company_id": 1 }
Response (201 Created)
{ "success": true, "message": "Product created successfully", "data": { "id": "660e8400-e29b-41d4-a716-446655440001", "name": "Samsung Galaxy S24" } }
PUT /admin/products/:id Update product
Admin Manager Inventory
▼
Request Body
{ "name": "Updated Product Name", "description": "Updated description", "category_id": 2 }
Response (200 OK)
{ "success": true, "message": "Product updated successfully" }
POST /admin/products/copy Copy products
Admin Manager Inventory
▼
Request Body
{ "product_id": "550e8400-e29b-41d4-a716-446655440000" }
Response (200 OK)
{ "success": true, "message": "Product copied successfully" }
POST /admin/products/upload Bulk upload products (10MB max)
Admin Manager Inventory
▼
Request Body (multipart/form-data)
{ "storage_id": 1, "company_id": 1, "store_id": 1, "file": <CSV file> }
Response (200 OK)
{ "success": true, "message": "Upload completed", "data": { "success": 98, "failed": 2, "errors": [ { "row": 15, "error": "Invalid category_id" }, { "row": 42, "error": "Duplicate SKU" } ] } }

Customers

Customer management endpoints (Admin)

POST /admin/customers/search Search customers
Super Admin Admin Manager
▼
Request Body
{ "search": "john", "page": 1, "limit": 10, "filters": { "company_id": 1, "is_deleted": false } }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": "cust-001", "name": "John Smith", "email": "[email protected]", "phone": "+1234567890", "total_orders": 15, "total_spent": 2500.00 } ], "pagination": { "total": 1, "page": 1, "limit": 10, "totalPages": 1 } } }
GET /admin/customers/:id Get customer by ID
Super Admin
▼
Response (200 OK)
{ "success": true, "data": { "id": "cust-001", "name": "John Smith", "email": "[email protected]", "phone": "+1234567890", "company_id": 1, "created_at": "2026-01-10T09:00:00.000Z", "orders": [ { "id": "ord-001", "total": 150.00, "date": "2026-03-15" } ] } }
POST /admin/customers Create customer
Super Admin
▼
Request Body
{ "name": "Jane Doe", "email": "[email protected]", "phone": "+1987654321", "company_id": 1 }
Response (201 Created)
{ "success": true, "message": "Customer created successfully", "data": { "id": "cust-002", "name": "Jane Doe" } }
PUT /admin/customers/:id Update customer
Super Admin
▼
Request Body
{ "name": "Jane Smith", "email": "[email protected]", "phone": "+1555555555" }
Response (200 OK)
{ "success": true, "message": "Customer updated successfully" }
DELETE /admin/customers/:id Delete customer
Super Admin
▼
Response (200 OK)
{ "success": true, "message": "Customer deleted successfully" }

Orders

Order management endpoints (Admin)

POST /admin/orders/all/search Search all orders
Super Admin Admin Manager Inventory
▼
Request Body
{ "search": "ORD-2026", "page": 1, "limit": 10, "filters": { "store_id": 1, "is_deleted": false } }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": "ord-001", "code": "ORD-2026-0001", "total": 299.99, "status": "completed", "payment_method": "cash", "customer": { "name": "John Smith" }, "cashier": { "name": "Jane Doe" }, "created_at": "2026-03-20T10:30:00.000Z" } ], "pagination": { "total": 150, "page": 1, "limit": 10, "totalPages": 15 } } }
POST /admin/orders/pre/search Search pre-orders
Super Admin Admin Manager Inventory
▼
Request Body
{ "search": "", "page": 1, "limit": 10, "filters": { "is_pre_order": true, "store_id": 1 } }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": "pre-001", "code": "PRE-2026-0001", "total": 500.00, "status": "pending", "scheduled_at": "2026-03-25T14:00:00.000Z", "customer": { "name": "Alice Johnson" } } ], "pagination": { "total": 5, "page": 1, "limit": 10, "totalPages": 1 } } }
GET /admin/orders/:id Get order by ID
Super Admin Admin Manager Inventory
▼
Response (200 OK)
{ "success": true, "data": { "id": "ord-001", "code": "ORD-2026-0001", "subtotal": 270.00, "tax": 29.99, "discount": 0, "total": 299.99, "amount_paid": 300.00, "change": 0.01, "payment_method": "cash", "status": "completed", "customer": { "id": "cust-001", "name": "John Smith" }, "items": [ { "product_name": "iPhone 15 Pro", "variant": "128GB - Black", "quantity": 1, "price": 270.00 } ], "created_at": "2026-03-20T10:30:00.000Z" } }
POST /admin/orders Create order
Super Admin
▼
Request Body
{ "customer_id": "cust-001", "payment_method": "card", "amount_paid": 150.00, "discount_type": "percentage", "discount_rate": 10, "items": [ { "variant_id": 1, "quantity": 2 } ], "company_id": 1, "store_id": 1, "cashier_id": "user-001" }
Response (201 Created)
{ "success": true, "message": "Order created successfully", "data": { "id": "ord-002", "code": "ORD-2026-0002", "total": 150.00 } }
PUT /admin/orders/:id Update order
Super Admin
▼
Request Body
{ "status": "completed" }
Response (200 OK)
{ "success": true, "message": "Order updated successfully" }
DELETE /admin/orders/:id Delete order
Super Admin
▼
Response (200 OK)
{ "success": true, "message": "Order deleted successfully" }

Inventory

Inventory management endpoints (Admin)

POST /admin/inventory/search Search inventory/stocks
Super Admin Admin Manager Inventory
▼
Request Body
{ "search": "iPhone", "page": 1, "limit": 10, "filters": { "store_id": 1, "storage_id": 1, "status": "low_stock", "is_deleted": false } }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": 1, "product": { "id": "prod-001", "name": "iPhone 15 Pro" }, "variant": { "sku": "IPH15PRO-128-BLK", "options": "128GB - Black" }, "storage": { "name": "Main Warehouse" }, "quantity": 5, "reorder_level": 10, "status": "low_stock" } ], "pagination": { "total": 25, "page": 1, "limit": 10, "totalPages": 3 } } }
GET /admin/inventory/:id Get inventory details
Super Admin Admin Manager Inventory
▼
Response (200 OK)
{ "success": true, "data": { "id": 1, "product": { "id": "prod-001", "name": "iPhone 15 Pro", "brand": "Apple", "category": "Electronics" }, "variant": { "id": 1, "sku": "IPH15PRO-128-BLK", "price": 999.99, "cost": 800.00 }, "quantity": 5, "reorder_level": 10, "storage": { "id": 1, "name": "Main Warehouse" }, "history": [ { "type": "sale", "quantity": -2, "date": "2026-03-19T15:00:00.000Z" }, { "type": "restock", "quantity": 20, "date": "2026-03-15T09:00:00.000Z" } ] } }

Settings: Company

Company settings for the authenticated user's company

GET /admin/settings/company Get company details
Admin
▼
Response (200 OK)
{ "success": true, "data": { "id": 1, "name": "Acme Corporation", "email": "[email protected]", "phone": "+1234567890", "address": "123 Business St, Suite 100", "logo": "https://cdn.example.com/acme-logo.png", "created_at": "2026-01-15T08:00:00.000Z" } }
PUT /admin/settings/company Update company details
Super Admin Admin
▼
Request Body
{ "name": "Acme Corporation Ltd", "address": "456 New Business Ave", "phone": "+1987654321", "email": "[email protected]" }
Response (200 OK)
{ "success": true, "message": "Company updated successfully" }

Settings: Users

User management within company

POST /admin/settings/users/search Search users
Admin Manager
▼
Request Body
{ "search": "john", "page": 1, "limit": 10, "filters": { "role": "Cashier", "is_deleted": false } }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": "user-001", "code": "USR-0001", "email": "[email protected]", "first_name": "John", "last_name": "Doe", "role": { "id": 4, "name": "Cashier" }, "is_active": true, "last_login": "2026-03-20T08:00:00.000Z" } ], "pagination": { "total": 1, "page": 1, "limit": 10, "totalPages": 1 } } }
GET /admin/settings/users/:id Get user by ID
Admin Manager
▼
Response (200 OK)
{ "success": true, "data": { "id": "user-001", "code": "USR-0001", "email": "[email protected]", "first_name": "John", "last_name": "Doe", "role": { "id": 4, "name": "Cashier" }, "is_active": true, "access": { "stores": [{ "id": 1, "name": "Main Store" }], "storages": [{ "id": 1, "name": "Main Warehouse" }] }, "created_at": "2026-02-01T09:00:00.000Z" } }
POST /admin/settings/users Create user
Admin Manager
▼
Request Body
{ "email": "[email protected]", "password": "SecurePass123", "first_name": "New", "last_name": "User", "role_id": 4, "store_ids": [1], "storage_ids": [1, 2] }
Response (201 Created)
{ "success": true, "message": "User created successfully", "data": { "id": "user-002", "code": "USR-0002", "email": "[email protected]" } }
PUT /admin/settings/users/:id Update user
Admin Manager
▼
Request Body
{ "first_name": "Updated", "last_name": "Name", "role_id": 3, "is_active": true }
Response (200 OK)
{ "success": true, "message": "User updated successfully" }
DELETE /admin/settings/users/:id Delete user
Admin Manager
▼
Response (200 OK)
{ "success": true, "message": "User deleted successfully" }

Settings: Suppliers

Supplier management

POST /admin/settings/suppliers/search Search suppliers
Admin Manager Inventory
▼
Request Body
{ "search": "tech", "page": 1, "limit": 10, "filters": { "is_deleted": false } }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": 1, "name": "Tech Supplies Co", "email": "[email protected]", "phone": "+1234567890", "address": "123 Supplier St" } ], "pagination": { "total": 1, "page": 1, "limit": 10, "totalPages": 1 } } }
GET /admin/settings/suppliers/:id Get supplier by ID
Admin
▼
Response (200 OK)
{ "success": true, "data": { "id": 1, "name": "Tech Supplies Co", "email": "[email protected]", "phone": "+1234567890", "address": "123 Supplier St", "contact_person": "John Manager", "created_at": "2026-01-10T09:00:00.000Z" } }
POST /admin/settings/suppliers Create supplier
Admin
▼
Request Body
{ "name": "New Supplier Inc", "email": "[email protected]", "phone": "+1987654321", "address": "456 Vendor Ave", "contact_person": "Jane Contact" }
Response (201 Created)
{ "success": true, "message": "Supplier created successfully", "data": { "id": 2, "name": "New Supplier Inc" } }
PUT /admin/settings/suppliers/:id Update supplier
Admin
▼
Request Body
{ "name": "Updated Supplier Name", "phone": "+1555555555" }
Response (200 OK)
{ "success": true, "message": "Supplier updated successfully" }
DELETE /admin/settings/suppliers/:id Delete supplier
Super Admin
▼
Response (200 OK)
{ "success": true, "message": "Supplier deleted successfully" }

Settings: Brands

Brand management

POST /admin/settings/brands/search Search brands
Admin Manager Inventory
▼
Request Body
{ "search": "apple", "page": 1, "limit": 10, "filters": { "is_deleted": false } }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": 1, "name": "Apple", "description": "Premium tech brand", "logo": "https://cdn.example.com/apple.png" } ], "pagination": { "total": 1, "page": 1, "limit": 10, "totalPages": 1 } } }
GET /admin/settings/brands/:id Get brand by ID
Admin
▼
Response (200 OK)
{ "success": true, "data": { "id": 1, "name": "Apple", "description": "Premium tech brand", "logo": "https://cdn.example.com/apple.png", "created_at": "2026-01-05T09:00:00.000Z" } }
POST /admin/settings/brands Create brand
Admin
▼
Request Body
{ "name": "Samsung", "description": "Leading electronics brand", "logo": "https://cdn.example.com/samsung.png" }
Response (201 Created)
{ "success": true, "message": "Brand created successfully", "data": { "id": 2, "name": "Samsung" } }
PUT /admin/settings/brands/:id Update brand
Admin
▼
Request Body
{ "name": "Samsung Electronics", "description": "Updated description" }
Response (200 OK)
{ "success": true, "message": "Brand updated successfully" }
DELETE /admin/settings/brands/:id Delete brand
Super Admin
▼
Response (200 OK)
{ "success": true, "message": "Brand deleted successfully" }

Settings: Categories

Category management

POST /admin/settings/categories/search Search categories
Admin Manager Inventory
▼
Request Body
{ "search": "electronics", "page": 1, "limit": 10, "filters": { "is_deleted": false } }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": 1, "name": "Electronics", "description": "Electronic devices and accessories", "parent_id": null }, { "id": 2, "name": "Smartphones", "description": "Mobile phones and tablets", "parent_id": 1 } ], "pagination": { "total": 2, "page": 1, "limit": 10, "totalPages": 1 } } }
GET /admin/settings/categories/:id Get category by ID
Admin
▼
Response (200 OK)
{ "success": true, "data": { "id": 1, "name": "Electronics", "description": "Electronic devices and accessories", "parent_id": null, "children": [ { "id": 2, "name": "Smartphones" }, { "id": 3, "name": "Laptops" } ] } }
POST /admin/settings/categories Create category
Admin
▼
Request Body
{ "name": "Accessories", "description": "Phone and computer accessories", "parent_id": 1 }
Response (201 Created)
{ "success": true, "message": "Category created successfully", "data": { "id": 4, "name": "Accessories" } }
PUT /admin/settings/categories/:id Update category
Super Admin
▼
Request Body
{ "name": "Updated Category Name", "description": "Updated description" }
Response (200 OK)
{ "success": true, "message": "Category updated successfully" }
DELETE /admin/settings/categories/:id Delete category
Super Admin
▼
Response (200 OK)
{ "success": true, "message": "Category deleted successfully" }

Settings: Units

Unit of measurement management

POST /admin/settings/units/search Search units
Admin Manager Inventory
▼
Request Body
{ "search": "", "page": 1, "limit": 10, "filters": { "type": "weight", "is_deleted": false } }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": 1, "name": "Kilogram", "symbol": "kg", "type": "weight" }, { "id": 2, "name": "Gram", "symbol": "g", "type": "weight" }, { "id": 3, "name": "Pound", "symbol": "lb", "type": "weight" } ], "pagination": { "total": 3, "page": 1, "limit": 10, "totalPages": 1 } } }
GET /admin/settings/units/:id Get unit by ID
Admin
▼
Response (200 OK)
{ "success": true, "data": { "id": 1, "name": "Kilogram", "symbol": "kg", "type": "weight" } }
POST /admin/settings/units Create unit
Admin
▼
Request Body
{ "name": "Liter", "symbol": "L", "type": "volume" }
Response (201 Created)
{ "success": true, "message": "Unit created successfully", "data": { "id": 4, "name": "Liter" } }
PUT /admin/settings/units/:id Update unit
Admin
▼
Request Body
{ "name": "Litre", "symbol": "l" }
Response (200 OK)
{ "success": true, "message": "Unit updated successfully" }
DELETE /admin/settings/units/:id Delete unit
Admin
▼
Response (200 OK)
{ "success": true, "message": "Unit deleted successfully" }

Settings: Variant Types

Product variant type management (Size, Color, etc.)

POST /admin/settings/variant-types/search Search variant types
Admin Manager Inventory
▼
Request Body
{ "search": "color", "page": 1, "limit": 10, "filters": { "is_deleted": false } }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": 1, "name": "Color", "values": ["Red", "Blue", "Green"] }, { "id": 2, "name": "Size", "values": ["S", "M", "L", "XL"] } ], "pagination": { "total": 2, "page": 1, "limit": 10, "totalPages": 1 } } }
GET /admin/settings/variant-types/:id Get variant type by ID
Admin
▼
Response (200 OK)
{ "success": true, "data": { "id": 1, "name": "Color", "values": ["Red", "Blue", "Green", "Yellow"] } }
POST /admin/settings/variant-types Create variant type
Admin
▼
Request Body
{ "name": "Material", "values": ["Cotton", "Polyester", "Leather"] }
Response (201 Created)
{ "success": true, "message": "Variant type created successfully", "data": { "id": 3, "name": "Material" } }
PUT /admin/settings/variant-types/:id Update variant type
Admin
▼
Request Body
{ "name": "Material Type", "values": ["Cotton", "Polyester", "Leather", "Wool"] }
Response (200 OK)
{ "success": true, "message": "Variant type updated successfully" }
DELETE /admin/settings/variant-types/:id Delete variant type
Admin
▼
Response (200 OK)
{ "success": true, "message": "Variant type deleted successfully" }

POS

Point of Sale operations for cashiers

POST /cashier/pos/products/search Search products for POS
Admin Manager Cashier
▼
Request Body
{ "search": "coffee", "page": 1, "limit": 20 }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": "abc-123", "name": "Premium Coffee", "sku": "COF-001", "price": 12.99, "stock_quantity": 150 } ] } }
POST /cashier/pos/customers/search Search customers at POS
Super Admin Admin Manager Cashier Inventory
▼
Request Body
{ "search": "john", "page": 1, "limit": 10 }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": "cust-456", "name": "John Doe", "email": "[email protected]", "phone": "+1234567890" } ] } }
POST /cashier/pos/customers Create customer at POS
Super Admin Admin Manager Cashier Inventory
▼
Request Body
{ "name": "Jane Smith", "email": "[email protected]", "phone": "+1234567890" }
Response (201 Created)
{ "success": true, "message": "Customer created successfully", "data": { "id": "cust-789", "name": "Jane Smith" } }
POST /cashier/pos/orders Create order/sale
Super Admin Admin Manager Cashier
▼
Request Body
{ "customer_id": "cust-456", "order_type": "completed", "items": [ { "product_id": "abc-123", "variant_id": "var-001", "quantity": 2, "price": 12.99, "discount_percent": 10, "note": "Extra sugar" } ], "payment_method": "cash", "discount_percent": 5, "tax_percent": 8, "note": "Rush order" }
Response (201 Created)
{ "success": true, "message": "Order created successfully", "data": { "id": "ord-123456", "order_number": "ORD-2025-001", "subtotal": 23.38, "discount": 1.17, "tax": 1.78, "total": 23.99, "status": "completed" } }

Cashier Orders

Order viewing for cashiers

POST /cashier/orders/search Search orders
Super Admin Admin Manager Cashier Inventory
▼
Request Body
{ "search": "ORD-2025", "page": 1, "limit": 10, "filters": { "status": "completed", "start_date": "2025-01-01", "end_date": "2025-01-31" } }
Response (200 OK)
{ "success": true, "data": { "items": [ { "id": "ord-123", "order_number": "ORD-2025-001", "customer_name": "John Doe", "total": 45.99, "status": "completed", "created_at": "2025-01-15T10:30:00Z" } ], "pagination": { "total": 1, "page": 1, "limit": 10, "totalPages": 1 } } }
GET /cashier/orders/:id Get order by ID
Super Admin Admin Manager Cashier Inventory
▼
Response (200 OK)
{ "success": true, "data": { "id": "ord-123", "order_number": "ORD-2025-001", "customer": { "id": "cust-456", "name": "John Doe" }, "items": [ { "product_name": "Premium Coffee", "quantity": 2, "price": 12.99, "subtotal": 25.98 } ], "subtotal": 25.98, "discount": 2.60, "tax": 1.87, "total": 25.25, "payment_method": "cash", "status": "completed", "created_at": "2025-01-15T10:30:00Z" } }

Cashier Store

Store information for cashier staff

GET /cashier/store Get assigned store details
Cashier Manager Admin
▼
Response (200 OK)
{ "success": true, "data": { "id": "uuid", "name": "Main Store", "address": "123 Main St", "phone": "+1234567890", "status": "open", "settings": { "receipt_header": "Welcome!", "receipt_footer": "Thank you!", "tax_rate": 10 } } }
PUT /cashier/store Update store settings
Manager Admin
▼
Request Body
{ "settings": { "receipt_header": "Updated header" } }
Response (200 OK)
{ "success": true, "message": "Store settings updated" }

Images

Image retrieval endpoint (Public)

GET /images/:id Get image by ID
Public
▼
Parameters
ParameterTypeDescription
idstringImage UUID
Response
Binary image data with appropriate Content-Type header

Dev Tools

Development and debugging endpoints (Super Admin only)

GET /dev/logs Get application logs
Super Admin
▼
Query Parameters
ParameterTypeDescription
levelstringFilter by log level (error, warn, info, debug)
fromstringStart date (ISO format)
tostringEnd date (ISO format)
Response (200 OK)
{ "success": true, "data": { "logs": [ { "timestamp": "2025-01-15T10:30:00Z", "level": "error", "message": "Database connection timeout" } ] } }
POST /dev/sync Sync database/cache
Super Admin
▼
Request Body
{ "target": "cache" }
Response (200 OK)
{ "success": true, "message": "Sync completed successfully" }

Product Status Views

Read-only endpoints by product lifecycle status

Draft

POST /admin/products/draft/search Search draft products ▼
Request Body
{ "keyword": "", "page": 1, "limit": 10 }
GET /admin/products/draft/:id Get draft product
GET /admin/products/draft/:id/detailed Get draft product detailed view

Archived / Discontinued / Coming Soon

Each status module provides the same 3 endpoints:

POST /admin/products/{status}/search GET /admin/products/{status}/:id GET /admin/products/{status}/:id/detailed

Available statuses: archived, discontinued, coming-soon.

Analytics

Advanced analytics endpoints for admin users

Market Basket

POST /admin/analytics/market-basket/analyze Analyze product co-purchases
Admin Manager
▼
Request Body
{ "start_date": "2026-01-01", "end_date": "2026-01-31", "min_support": 2 }

Reports

Reporting modules for sales, inventory, finance, and exports

Sales Summary

Base: /admin/reports/sales-summary

GET /stats GET /daily-sales GET /top-products GET /payment-method-breakdown GET /discount-summary POST /export-pdf

Inventory Report

Base: /admin/reports/inventory-report

GET /stats GET /stock-in-vs-out GET /top-fast-moving GET /inventory-by-category POST /export-pdf

Financial Report

Base: /admin/reports/financial-report

GET /stats GET /revenue-vs-expenses GET /expense-breakdown GET /revenue-streams POST /export-pdf

Exports

POST /admin/reports/exports/search Search export history
Super Admin Admin Manager
▼
Request Body
{ "page": 1, "limit": 10, "filters": { "type": "Sales Summary", "status": "Completed" } }