👤 Groceries Employee API

Employee endpoints (JWT + role: employee)

Overview

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

Dashboard

GET /employee/dashboard Employee Only

Returns aggregated stats for the employee dashboard including total customers, products, and carts.

200 OK - Success

{
  "total_customers": 150,
  "total_products": 45,
  "total_carts": 23
}

Response Fields:

  • total_customers - Count of all users with role "customer"
  • total_products - Count of all products in the system
  • total_carts - Count of all shopping carts

Example Request:

GET /employee/dashboard
Authorization: Bearer <employee_token>

401 Unauthorized - Invalid or missing token

403 Forbidden - User does not have employee role

Customer Management

GET /employee/customers Employee Only

List all customers with pagination support. Soft-deleted customers are excluded by default.

Query Parameters

  • page (optional, default: 1) - Page number
  • per_page (optional, default: 20) - Items per page
  • include_deleted (optional, default: false) - Include soft-deleted customers

Example Request:

GET /employee/customers?page=1&per_page=20&include_deleted=false
Authorization: Bearer <employee_token>

200 OK - Success

{
  "customers": [
    {
      "id": 1,
      "full_name": "John Doe",
      "id_number": "12345678",
      "email": "john@example.com",
      "phone_number": "+254712345678",
      "role": "customer",
      "county": "Nairobi",
      "town": "Westlands",
      "street": "123 Main Street",
      "is_active": true,
      "deleted_at": null,
      "created_at": "2025-01-15T10:30:00",
      "updated_at": "2025-01-15T10:30:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 150,
    "pages": 8,
    "has_next": true,
    "has_prev": false
  }
}
GET /employee/customers/<customer_id> Employee Only

Get detailed information about a specific customer, including all their cart history with items.

200 OK - Success

{
  "customer": {
    "id": 1,
    "full_name": "John Doe",
    "id_number": "12345678",
    "email": "john@example.com",
    "phone_number": "+254712345678",
    "role": "customer",
    "county": "Nairobi",
    "town": "Westlands",
    "street": "123 Main Street",
    "is_active": true,
    "deleted_at": null,
    "created_at": "2025-01-15T10:30:00",
    "updated_at": "2025-01-15T10:30:00",
    "carts": [
      {
        "id": 1,
        "user_id": 1,
        "status": "active",
        "created_at": "2025-01-20T10:00:00",
        "updated_at": "2025-01-20T10:00:00",
        "items": [
          {
            "id": 1,
            "cart_id": 1,
            "product_id": 5,
            "quantity": "2.000",
            "sale_channel": "online",
            "unit_price": "100.00",
            "line_total": "200.00",
            "created_at": "2025-01-20T10:01:00",
            "updated_at": "2025-01-20T10:01:00"
          }
        ],
        "items_count": 1
      }
    ],
    "total_carts": 3
  }
}

404 Not Found - Customer not found

POST /employee/customers/<customer_id>/delete Employee/Admin

Soft delete a customer by setting the deleted_at timestamp. The customer record is not permanently removed.

200 OK - Success

{
  "message": "Customer deleted successfully",
  "customer": {
    "id": 1,
    "full_name": "John Doe",
    "email": "john@example.com",
    "deleted_at": "2025-01-20T15:30:00",
    ...
  }
}

400 Bad Request - Customer already deleted

404 Not Found - Customer not found

POST /employee/customers/<customer_id>/restore Employee/Admin

Restore a soft-deleted customer by clearing the deleted_at timestamp.

200 OK - Success

{
  "message": "Customer restored successfully",
  "customer": {
    "id": 1,
    "full_name": "John Doe",
    "email": "john@example.com",
    "deleted_at": null,
    ...
  }
}

400 Bad Request - Customer is not deleted

404 Not Found - Customer not found

POST /employee/customers/<customer_id>/activate Employee/Admin

Activate a customer by setting is_active to true. This allows the customer to access their account.

200 OK - Success

{
  "message": "Customer activated successfully",
  "customer": {
    "id": 1,
    "full_name": "John Doe",
    "email": "john@example.com",
    "is_active": true,
    ...
  }
}

400 Bad Request - Customer is already active

404 Not Found - Customer not found

POST /employee/customers/<customer_id>/deactivate Employee/Admin

Deactivate a customer by setting is_active to false. This prevents the customer from accessing their account.

200 OK - Success

{
  "message": "Customer deactivated successfully",
  "customer": {
    "id": 1,
    "full_name": "John Doe",
    "email": "john@example.com",
    "is_active": false,
    ...
  }
}

400 Bad Request - Customer is already inactive

404 Not Found - Customer not found

Notes

  • Authorization header is required: Bearer <employee_token>
  • Role enforcement uses JWT claim role == employee or admin
  • Customer management endpoints (delete, restore, activate, deactivate) require employee or admin role
  • Soft delete does not permanently remove customer records; use the restore endpoint to recover
  • Deactivated customers cannot access their accounts until reactivated
  • Responses are JSON; timestamps are ISO 8601 UTC format
  • Customer detail endpoint includes complete cart history with all items