🛠 Groceries Admin API

Admin-only endpoints (JWT + role: admin)

Overview

These endpoints require a valid JWT with role=admin. Include the token in the Authorization: Bearer <token> header.

Dashboard

GET /admin/dashboard Admin Only

Returns aggregated stats for the admin dashboard.

200 OK - Success

{
  "total_users": 42,
  "total_alerts": 18,
  "unread_alerts": 5,
  "users_by_role": {
    "admin": 2,
    "customer": 30,
    "employee": 8,
    "delivery": 2
  }
}

Users

GET /admin/users Admin Only

List users, optionally filtered by role. Supports pagination.

Query Parameters

  • role (optional) — filter by role (admin, customer, employee, delivery)
  • page (optional, default 1) — page number
  • per_page (optional, default 20) — items per page

Example Request:

GET /admin/users?role=customer&page=1&per_page=20
Authorization: Bearer <admin_token>

200 OK - Success

{
  "users": [
    {
      "id": 12,
      "full_name": "Jane Customer",
      "id_number": "CUST-12345",
      "email": "jane@example.com",
      "phone_number": "+254700000000",
      "role": "customer",
      "county": "Nairobi",
      "town": "Westlands",
      "street": "123 Main St",
      "created_at": "2025-01-15T10:30:00",
      "updated_at": "2025-01-15T10:30:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 30,
    "pages": 2,
    "has_next": true,
    "has_prev": false
  }
}

Manage Users

POST /admin/users Admin Only

Create a user with role employee or delivery.

Request Body (JSON)

  • full_name (required)
  • id_number (required)
  • email (required, unique)
  • phone_number (optional)
  • password (required)
  • role (required, must be employee or delivery)
  • county, town, street (optional)

Example Request:

POST /admin/users
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "full_name": "Jane Rider",
  "id_number": "EMP-001",
  "email": "jane.rider@example.com",
  "phone_number": "+254700000000",
  "password": "StrongPass123!",
  "role": "delivery",
  "county": "Nairobi",
  "town": "Westlands",
  "street": "123 Main St"
}

201 Created - Success

400 Bad Request - Missing required fields or invalid role

409 Conflict - Email already registered

GET /admin/users/<user_id> Admin Only

Fetch a user's details by ID.

200 OK - Success

404 Not Found - User not found

Shop Settings

GET /admin/settings Admin Only

Fetch current shop settings.

200 OK - Success

{
  "settings": {
    "store_name": "FreshMart",
    "number_of_branches": 2,
    "emails": ["main@freshmart.com", "support@freshmart.com"],
    "phones": ["+254700000000", "+254711111111"],
    "addresses": ["HQ Address", "Branch 2 Address"],
    "enable_delivery": true,
    "enable_pickup": true,
    "delivery_fee_per_km": "50.00",
    "free_delivery_threshold": "1000.00",
    "delivery_radius_km": "15.00",
    "enable_cash_on_delivery": true,
    "enable_bank_payments": false,
    "enable_mpesa": true,
    "enable_registrations": true,
    "maintenance_mode": false
  }
}
PUT /admin/settings Admin Only

Update shop settings (creates if none exist).

Request Body (JSON)

  • store_name (optional)
  • number_of_branches (optional)
  • emails (optional, array)
  • phones (optional, array)
  • addresses (optional, array)
  • enable_delivery, enable_pickup (optional, boolean)
  • delivery_fee_per_km, free_delivery_threshold, delivery_radius_km (optional, numeric)
  • enable_cash_on_delivery, enable_bank_payments, enable_mpesa, enable_registrations, maintenance_mode (optional, boolean)

Example Request:

PUT /admin/settings
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "store_name": "FreshMart",
  "number_of_branches": 2,
  "emails": ["main@freshmart.com", "support@freshmart.com"],
  "phones": ["+254700000000", "+254711111111"],
  "addresses": ["HQ Address", "Branch 2 Address"],
  "enable_delivery": true,
  "delivery_fee_per_km": 50,
  "free_delivery_threshold": 1000,
  "delivery_radius_km": 15,
  "enable_cash_on_delivery": true,
  "enable_mpesa": true
}

200 OK - Success

Notes

  • Authorization header is required: Bearer <admin_token>
  • Role enforcement uses JWT claim role == admin
  • Responses are JSON; timestamps (if any) are ISO 8601 UTC