Stores

All routes under /api/v1/stores require authentication + Owner role.

Store Statuses

GET /stores

List all stores with live KPI data.

Auth: Required + Owner

Query: status (filter by status)

Response:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "Main Store",
        "status": "open",
        "today_sales": 525000,
        "today_transactions": 45,
        "staff_on_duty": 5
      }
    ],
    "count": 3
  }
}

POST /stores

Create a new store.

Auth: Required + Owner

Request Body:

{
  "name": "Branch Store",
  "code": "BR-001",
  "phone": "+255712345678",
  "email": "branch@ziadapos.com",
  "area": "Kinondoni",
  "address": "Sea View Road",
  "latitude": -6.7738,
  "longitude": 39.2585,
  "open_hours": "08:00-18:00",
  "color": "#3B82F6",
  "status": "open",
  "vat_enabled": true
}

Response: Store object.

GET /stores/stats

Get aggregate stats across all stores.

Auth: Required + Owner

Response:

{
  "success": true,
  "data": {
    "total_stores": 3,
    "active_stores": 2,
    "total_sales_today": 1250000,
    "total_staff": 15
  }
}

GET /stores/:id

Get a single store with full details.

Auth: Required + Owner

PATCH /stores/:id

Update a store.

Auth: Required + Owner

Request Body: Same as POST /stores but all fields optional.

DELETE /stores/:id

Deactivate a store.

Auth: Required + Owner

GET /stores/:id/staff

Get staff roster for a store.

Auth: Required + Owner

Response: { items: [...], count: 5 }

GET /stores/:id/week

Get 7-day sales breakdown.

Auth: Required + Owner

Response: Weekly sales data for sparkline display.

PATCH /stores/:id/status

Set store status.

Auth: Required + Owner

Request Body:

{
  "status": "closed"
}

Response: Updated Store object.