Metrics API

Counts and revenue for dashboards: totals by role, product/inventory metrics, and inventory revenue. All routes require Authorization: Bearer <access_token>. Base path: <API_BASE_URL>/metrics.

Endpoints

Dashboard metrics

GET /metrics/admin-dashboard

Returns all dashboard counts for the admin dashboard. Allowed: admin only. Includes user counts and product/inventory metrics. Query active_only: 1, true, yes (default) to filter by active products; 0 or false for all.

GET /metrics/staff-dashboard

Returns customer-focused counts for the staff dashboard. Allowed: admin, or staff with permission view_customers. Response: total_customers, active_customers, inactive_customers, customers_email_verified, customers_phone_verified.

GET /metrics/inventory

Returns product and inventory metrics. Allowed: admin, or staff with permission manage_inventory. Query active_only: same as admin-dashboard. Response: total_products, total_products_with_inventory, total_products_with_pricing, total_stock_quantity, total_reserved_quantity, total_available_quantity, products_in_stock, products_low_stock, products_out_of_stock, total_inventory_revenue, reserved_inventory_revenue, available_inventory_revenue.

Response

Admin response (GET /metrics/admin-dashboard)

200 with JSON containing user counts and product/inventory metrics.

User counts

  • Totals: total_customers, total_staff, total_admins
  • Active: active_customers, active_staff, active_admins
  • Inactive: inactive_customers, inactive_staff, inactive_admins
  • Email verified: customers_email_verified, staff_email_verified, admins_email_verified
  • Phone verified: customers_phone_verified, staff_phone_verified, admins_phone_verified

Product & inventory metrics

  • Products: total_products, total_products_with_inventory, total_products_with_pricing
  • Quantities: total_stock_quantity, total_reserved_quantity, total_available_quantity
  • Status: products_in_stock, products_low_stock, products_out_of_stock
  • Revenue (potential): total_inventory_revenue (stock × price), reserved_inventory_revenue (reserved × price), available_inventory_revenue (available × price). Values may be in mixed currencies if products use different currencies.

Staff response (GET /metrics/staff-dashboard)

200 with JSON: total_customers, active_customers, inactive_customers, customers_email_verified, customers_phone_verified.

Inventory response (GET /metrics/inventory)

200 with JSON: same product and inventory metrics as in admin response (no user counts). Available to admin or staff with manage_inventory.

Sample outputs

Admin dashboard (GET /metrics/admin-dashboard):

{
  "total_customers": 45,
  "total_staff": 8,
  "total_admins": 2,
  "active_customers": 42,
  "inactive_customers": 3,
  "active_staff": 7,
  "inactive_staff": 1,
  "active_admins": 2,
  "inactive_admins": 0,
  "customers_email_verified": 38,
  "customers_phone_verified": 12,
  "staff_email_verified": 7,
  "staff_phone_verified": 6,
  "admins_email_verified": 2,
  "admins_phone_verified": 2,
  "total_products": 120,
  "total_products_with_inventory": 95,
  "total_products_with_pricing": 110,
  "total_stock_quantity": 2450,
  "total_reserved_quantity": 180,
  "total_available_quantity": 2270,
  "products_in_stock": 88,
  "products_low_stock": 5,
  "products_out_of_stock": 7,
  "total_inventory_revenue": 1850000.0,
  "reserved_inventory_revenue": 135000.0,
  "available_inventory_revenue": 1715000.0
}

Staff with manage_inventory (GET /metrics/inventory):

{
  "total_products": 120,
  "total_products_with_inventory": 95,
  "total_products_with_pricing": 110,
  "total_stock_quantity": 2450,
  "total_reserved_quantity": 180,
  "total_available_quantity": 2270,
  "products_in_stock": 88,
  "products_low_stock": 5,
  "products_out_of_stock": 7,
  "total_inventory_revenue": 1850000.0,
  "reserved_inventory_revenue": 135000.0,
  "available_inventory_revenue": 1715000.0
}

Staff with view_customers (GET /metrics/staff-dashboard):

{
  "total_customers": 45,
  "active_customers": 42,
  "inactive_customers": 3,
  "customers_email_verified": 38,
  "customers_phone_verified": 12
}
Errors

Common responses

401 if missing or invalid token. 403 if authenticated but lacking required role or permission.