Dashboard Home

Last Updated: 2026-07-09

The dashboard_home action on StoreViewSet returns an aggregated snapshot of a store's current trading state in a single cached response. It is the primary data source for the management dashboard home screen.

Endpoint

GET /stores/{store_code}/dashboard_home/

The lookup value accepts a store_code, Django UUID, or Sanity ID (multi-lookup, same as store retrieve).

Authentication: Inherits the platform default permission (IsActiveUser in production, AllowAny in DEBUG; settings/base.py:251-253) Cache: 60 seconds per store (Redis)

Response Schema

{
  "kpis": {
    "revenue_today": "1842.50",
    "transactions_today": 27,
    "avg_transaction_value": "68.24",
    "active_promotions": 3
  },
  "top_products_today": [
    {
      "product_id": 12,
      "name": "Classic Tee",
      "revenue": "540.00",
      "units_sold": 18
    }
  ],
  "low_stock_alerts": [
    {
      "variant_sku": "TEE-BLK-M",
      "name": "Classic Tee",
      "stock_on_hand": 2,
      "reorder_point": 5
    }
  ],
  "recent_transactions": [
    {
      "transaction_id": "TXN-20260305-ABC123",
      "total": "98.50",
      "status": "completed",
      "timestamp": "2026-03-05T14:22:00+00:00"
    }
  ]
}

Fields

kpis

Field	Type	Description
`revenue_today`	string (decimal)	Sum of `totalAmount` for completed transactions today (UTC date)
`transactions_today`	integer	Count of completed transactions today
`avg_transaction_value`	string (decimal)	`revenue_today / transactions_today`, or `"0.00"` if no transactions
`active_promotions`	integer	Count of globally active `PromotionalCampaign` records

top_products_today

Up to 5 products ranked by revenue for today. Delegated to ProductAnalyticsService.get_top_products(). Returns an empty list if no sales today.

low_stock_alerts

Up to 10 InventoryLevel records where stock_on_hand <= reorder_point and reorder_point > 0. Only active inventory levels are included.

Field	Type	Description
`variant_sku`	string	SKU of the variant
`name`	string	Variant name, falling back to the product name
`stock_on_hand`	integer	Current on-hand quantity
`reorder_point`	integer	Configured reorder threshold

recent_transactions

Up to 10 most recent transactions by timestamp, any status.

Field	Type	Description
`transaction_id`	string	Public transaction identifier (`transactionId`)
`total`	string (decimal)	`totalAmount`
`status`	string	Transaction status
`timestamp`	string (ISO 8601)	Transaction timestamp

Implementation Notes

revenue_today and transactions_today use the UTC calendar date: django.utils.timezone.localdate() resolves in the active Django timezone, which is TIME_ZONE = 'UTC' project-wide, and no per-store timezone is activated on this path. A store whose local day differs from UTC sees its KPI window roll over at UTC midnight.
active_promotions is global. PromotionalCampaign has no relational store FK, so this count reflects all active campaigns platform-wide.
The response is cached for 60 seconds per store. The cache is not invalidated on transaction completion; clients should poll at a reasonable interval.
Source: stores/services.py (DashboardService.get_dashboard_home, services.py:77-168), stores/views.py (StoreViewSet.dashboard_home, views.py:128-151)