POSVelo
POSVeloDocs

API Reference

Endpoints, authentication, and response format

Dev Only

Connection Details

PropertyDevelopmentProduction
Base URLhttp://localhost:5000/apihttps://api.yourdomain.com/api
Socket.IO URLhttp://localhost:5000https://api.yourdomain.com
Auth HeaderAuthorization: Bearer <token>Authorization: Bearer <token>
Content-Typeapplication/jsonapplication/json
Access Token Lifespan15 minutes15 minutes
Refresh Token Lifespan7 days7 days

Authentication Endpoints

MethodPathDescriptionAuth
POST/auth/loginLogin — returns access + refresh tokensNo
POST/auth/refreshExchange refresh token for new access tokenNo
POST/auth/logoutRevoke the current refresh tokenYes
POST/auth/logout-allRevoke all sessions for this accountYes
GET/auth/meGet the authenticated user's profileYes
PATCH/auth/change-passwordChange password — revokes all active sessionsYes

Resource Endpoints by Module

Products — /api/v1/products

MethodEndpointPermissionDescription
GET/product:readList products (paginated)
POST/product:writeCreate product
POST/bulk-importproduct:writeBulk import products
GET/lookup/barcode/:barcodeproduct:readBarcode lookup
GET/:idproduct:readGet product detail
PATCH/:idproduct:writeUpdate product
DELETE/:idproduct:writeSoft-delete product
POST/:id/variantsproduct:writeAdd variant
PATCH/:id/variants/:variantIdproduct:writeUpdate variant
DELETE/:id/variants/:variantIdproduct:writeSoft-delete variant

Categories — /api/v1/products/categories

MethodEndpointPermissionDescription
GET/categoriescategory:readList categories (tree/flat)
POST/categoriescategory:writeCreate category
GET/categories/:idcategory:readGet category
PATCH/categories/:idcategory:writeUpdate category
DELETE/categories/:idcategory:writeSoft-delete category

Inventory — /api/v1/inventory

MethodEndpointPermissionDescription
GET/stockinventory:readPaginated stock list
GET/stock/lowinventory:readLow stock items
POST/stock/adjustinventory:writeDelta stock adjustment
POST/stock/setinventory:writeAbsolute stock set
PATCH/stock/:storeId/:productId/thresholdinventory:writeUpdate low stock threshold
GET/movementsinventory:readStock movement history
GET/transfersinventory:readList transfers
POST/transfersinventory:writeCreate transfer
GET/transfers/:idinventory:readGet transfer detail
POST/transfers/:id/shipinventory:writeMark as IN_TRANSIT
POST/transfers/:id/receiveinventory:writeMark as COMPLETED
POST/transfers/:id/cancelinventory:writeCancel transfer

Sales — /api/v1/sales

MethodEndpointPermissionDescription
POST/checkoutsale:createProcess checkout
GET/sale:readList sales
GET/:idsale:readGet sale detail
POST/:id/voidsale:voidVoid a sale
POST/:id/returnsale:returnReturn a sale

Payments — /api/v1/payments

MethodEndpointPermissionDescription
GET/sale:readList payments
GET/:idsale:readGet payment detail
POST/collect-duesale:createCollect due payment
GET/customer/:customerIdcustomer:readCustomer payment history

Customers — /api/v1/customers

MethodEndpointPermissionDescription
GET/groupscustomer:readList customer groups
POST/groupscustomer:writeCreate group
PATCH/groups/:idcustomer:writeUpdate group
DELETE/groups/:idcustomer:writeDelete group
GET/loyalty/programcustomer:readGet loyalty program config
GET/customer:readList customers
POST/customer:writeCreate customer
GET/:idcustomer:readGet customer detail
PATCH/:idcustomer:writeUpdate customer
DELETE/:idcustomer:writeDelete customer
GET/:id/ledgercustomer:readCustomer financial ledger
GET/:id/loyaltycustomer:readLoyalty point history
POST/:id/loyalty/adjustcustomer:writeAdjust loyalty points

Suppliers — /api/v1/suppliers

MethodEndpointPermissionDescription
GET/supplier:readList suppliers
POST/supplier:writeCreate supplier
GET/:idsupplier:readGet supplier detail
PATCH/:idsupplier:writeUpdate supplier
DELETE/:idsupplier:writeDelete supplier

Purchases — /api/v1/purchases

MethodEndpointPermissionDescription
GET/purchase:readList purchase orders
POST/purchase:writeCreate purchase order
GET/:idpurchase:readGet PO detail
POST/:id/receivepurchase:receiveReceive goods
POST/:id/paymentpurchase:writeAdd payment to PO
POST/:id/cancelpurchase:writeCancel PO

Expenses — /api/v1/expenses

MethodEndpointPermissionDescription
GET/categoriesexpense:readList expense categories
POST/categoriesexpense:writeCreate category
DELETE/categories/:idexpense:writeDelete category
GET/summaryexpense:readExpense summary
GET/expense:readList expenses
POST/expense:writeCreate expense
GET/:idexpense:readGet expense detail
PATCH/:idexpense:writeUpdate expense
DELETE/:idexpense:writeDelete expense

Reports — /api/v1/reports

MethodEndpointPermissionDescription
GET/salesreport:readSales summary report
GET/profitreport:readProfit & loss report
GET/stockreport:readStock valuation report
GET/cashierreport:readCashier performance report

Receipts — /api/v1/receipts

MethodEndpointPermissionDescription
GET/templatereceipt:readGet receipt template
PUT/templatereceipt:writeCreate/update template
GET/sale/:saleIdreceipt:generateGenerate receipt (data/HTML)
GET/sale/:saleId/previewreceipt:generateHTML receipt preview

Users — /api/v1/users

MethodEndpointPermissionDescription
PATCH/meAny authenticatedUpdate own profile
GET/ADMIN/MANAGERList users
POST/ADMIN/MANAGERCreate user
GET/:idADMIN/MANAGERGet user detail
PATCH/:idADMIN/MANAGERUpdate user
POST/:id/reset-passwordADMIN/MANAGERReset user password
DELETE/:idADMIN/MANAGERDeactivate user
PATCH/:id/restoreADMIN/MANAGERReactivate user

Stores — /api/v1/stores

MethodEndpointPermissionDescription
GET/store:manageList stores
POST/store:manageCreate store
GET/:idstore:manageGet store details
PATCH/:idstore:manageUpdate store
GET/:id/statsstore:manageStore dashboard stats
DELETE/:idstore:manageSoft-delete store

Tenant & Settings — /api/v1/tenants

MethodEndpointPermissionDescription
GET/metenant:manageGet own tenant profile
PATCH/metenant:manageUpdate own tenant
GET/me/settingstenant:manageGet tenant settings
PATCH/me/settingstenant:manageUpdate tenant settings
GET/me/dashboardtenant:manageDashboard statistics

Audit Logs — /api/v1/audit

MethodEndpointPermissionDescription
GET/report:readTenant audit logs
GET/allSUPER_ADMINPlatform-wide audit logs

Super Admin — /api/v1/super-admin

MethodEndpointDescription
GET/adminsList super admins
POST/adminsCreate super admin
GET/statsPlatform-wide statistics
GET/usersList all users (cross-tenant)
GET/users/:userIdGet user (cross-tenant)
DELETE/users/:userIdSoft-delete user
PATCH/users/:userId/restoreRestore user
DELETE/users/:userId/hardHard-delete user
POST/users/bulkBulk user action
POST/users/:userId/reset-passwordReset any password

Standard Response Format

Success Response

json

Error Response

json

HTTP Status Code Reference

Status CodeMeaningWhen It Occurs
200 OKSuccessGET, PATCH, DELETE requests that complete normally
201 CreatedResource createdPOST requests that create a new resource
400 Bad RequestValidation errorRequest body fails Zod schema — check error.details array
401 UnauthorizedInvalid authMissing or expired access token
403 ForbiddenInsufficient rightsToken is valid but the role lacks the required permission
404 Not FoundMissing resourceThe ID does not exist or belongs to a different tenant
409 ConflictDuplicateUnique constraint violation — e.g. SKU already exists
422 UnprocessableBusiness logic errore.g. insufficient stock, exceeded credit limit
429 Too Many RequestsRate limitedExceeded request limit — back off and retry
500 Server ErrorUnexpected errorCheck backend Pino logs for the full stack trace
← PreviousDeveloper GuideNext →Deployment Guide