Architecture and workflows
The ZiadaPOS API is a Go service built with Gin and GORM. It groups HTTP routes by business domain and passes shared dependencies to each app. PostgreSQL stores business records; Redis, MinIO, email, SMS, AI, and scheduled jobs are used where configured. Redis and MinIO can be unavailable during development boot, so integration availability depends on runtime configuration.
Request path
The API applies request ID, recovery, logging, and CORS middleware globally. Authentication and role checks are applied to route groups or individual routes. Public health and reference data endpoints do not use the same access rules as business operations.
API domains
| Domain | Responsibility |
|---|---|
| Accounts | Registration, verification, login, users, organisations, and store context. |
| Inventory and pharmacy | Product catalog, stock adjustments, medicine batches, expiry, and prescription records. |
| Transactions | Checkout, refunds, voids, emailed receipts, and POS summaries. |
| Customers and credits | Customer records, credit tabs, payments, reminders, and notes. |
| Suppliers | Supplier accounts, deliveries, payments, purchase orders, and reorder suggestions. |
| Operations | Expenses, staff, stores, notes, notifications, and reports. |
| Platform | Analytics, subscriptions, reviews, AI conversations, uploads, and admin routes. |
Use the REST API overview for the domain guide index and the API repository’s route reference (opens in a new tab) for the complete route list.
Store and organisation context
Authenticated tokens carry the user, organisation, role, and active store context. Domain handlers use this context to scope data. Switch the active store with POST /accounts/switch-store; the API returns refreshed tokens that carry the selected store. Owner-only and pharmacy-specific checks add restrictions beyond basic authentication.
Important workflows
Sale and stock
POST /pos/sale validates line items and payment details, creates a transaction, and updates inventory. Transaction events update customer aggregates and can create a credit tab when the payment method is Credit. A sale for a pharmacy can also allocate eligible, unexpired medicine batches using FEFO rules.
Supplier receiving and pharmacy batches
Supplier purchase orders and deliveries can receive quantities into stock and medicine batches. Pharmacy returns enter quarantine; an owner can release a returned batch after recording an inspection note. Disposal records a batch movement and stock adjustment.
Asynchronous side effects
The internal event bus decouples selected actions from work such as registration messages, staff onboarding messages, customer statistics, and credit-tab updates. Integrations depend on server configuration; route availability does not guarantee that a provider is configured.
For exact request fields and edge cases, use the relevant API guide and the API-owned business workflows (opens in a new tab).