Data Analytics

The Data Analytics system provides interactive e-commerce reporting with 10 built-in reports, a KPI dashboard, and CSV export — all with responsive Recharts visualizations.

Separate from Email Reports

This is the interactive analytics hub (formerly labeled "Reports" in the admin menu). For automated email-based reports, see Email Reports.

Overview

Navigate to Reports (Data Analytics) in the WordPress admin menu to access the analytics dashboard and report viewer.

Key Features:

📊 KPI Dashboard — Real-time key metrics with date range selection
📈 10 Built-in Reports — Sales, shipping, chargebacks, geographic, queue health, and more
📉 Interactive Charts — Bar, line, pie, and area charts via Recharts
🔍 Sortable Tables — Click column headers to sort, with automatic totals row
📥 CSV Export — Download any report as a CSV file
🏪 Site Filtering — Filter all reports by individual site
🔗 Deep Linking — Shareable URLs for specific reports (e.g., ?page=gsm-data-reports&report=sales-summary)
🔒 SQL Security — SELECT-only parser, table allowlist, 10K row limit, 5-second execution timeout

Permission Required: manage_options

Version Added: 1.18.0

KPI Dashboard

The dashboard displays at the top of the analytics page with key metrics for the selected date range:

KPI	Description
Total Orders	Count of distinct orders in the date range
Total Revenue	Sum of line item revenue (price × quantity)
Avg Order Value	Revenue ÷ Total Orders
Pending Orders	Orders with `ship_status = 0`
Shipped Orders	Orders with `ship_status = 2`
Items Processed	Sum of product line item quantities
Chargeback Rate	Chargebacks ÷ Total Orders (percentage)
Avg Fulfillment Time	Average days between order creation and shipment

Date Range Selection

Select start and end dates via calendar picker
Maximum 12-month range enforced on both frontend and backend
KPI data refreshes automatically on date change (400ms debounce to prevent excessive API calls)
In-flight requests are cancelled when a newer date is selected

Caching

Dashboard KPI results are cached with a 5-minute TTL via WordPress transients, preventing repeated heavy queries on page reload.

Available Reports

Category: Sales & Revenue

Report	Description	Chart Type
Sales Summary	Order totals and revenue by date	Line chart
Revenue by Site	Revenue breakdown per store	Bar chart
Payment Method Breakdown	Order count and revenue by payment method	Pie chart
Geographic Sales	Revenue by shipping region	Bar chart

Category: Operations

Report	Description	Chart Type
Orders by Status	Order distribution by processing status	Pie chart
Top Selling Products	Highest quantity products by SKU and name	Bar chart
Shipping Performance	Shipping metrics by carrier	Bar chart
Order Volume Trends	Order volume over time	Area chart

Category: Health & Monitoring

Report	Description	Chart Type
Chargeback Summary	Dispute trends and analysis	Line chart
Queue Health	Queue job status and processing metrics	Bar chart

Interface

Category Tabs — Reports grouped by Sales & Revenue, Operations, Health & Monitoring
Search Filter — Type to filter available reports by name
Report Submenu — Each report also appears as a submenu item under Reports in the WordPress admin sidebar for one-click access

Report Viewer

After selecting a report:

Date range picker — Set start and end dates (12-month max)
Site filter — Filter by specific site or view all sites
Chart visualization — Interactive Recharts chart (hover for tooltips)
Data table — Sortable columns with automatic totals row
CSV Export — Download button for the current report data

Deep Linking

Reports support URL-based navigation:

/wp-admin/admin.php?page=gsm-data-reports&report=sales-summary
/wp-admin/admin.php?page=gsm-data-reports&report=payment-method-breakdown

Navigating between reports and tabs updates the URL for shareability and bookmarking.

REST API Endpoints

List Available Reports

GET /wp-json/gsm-middleware/v1/analytics/reports

Returns all registered reports with metadata (name, description, category, slug).

Execute a Report

POST /wp-json/gsm-middleware/v1/analytics/reports/{slug}/execute

Body Parameters:

Parameter	Type	Required	Description
`start_date`	string	Yes	Start date (`YYYY-MM-DD`)
`end_date`	string	Yes	End date (`YYYY-MM-DD`)
`site_id`	integer	No	Filter by site ID

Response:

{
  "success": true,
  "data": {
    "columns": [
      { "key": "date", "label": "Date", "type": "date" },
      { "key": "total_orders", "label": "Total Orders", "type": "number" },
      { "key": "revenue", "label": "Revenue", "type": "currency" }
    ],
    "rows": [...],
    "totals": { "total_orders": 1523, "revenue": 192456.78 }
  }
}

Dashboard KPIs

GET /wp-json/gsm-middleware/v1/analytics/dashboard

Query Parameters:

Parameter	Type	Required	Description
`start_date`	string	Yes	Start date (`YYYY-MM-DD`)
`end_date`	string	Yes	End date (`YYYY-MM-DD`)
`site_id`	integer	No	Filter by site ID

List Sites

GET /wp-json/gsm-middleware/v1/analytics/sites

Returns the list of sites for the filter dropdown. Cached for 10 minutes via transient.

SQL Security Layer

All report queries are validated through a security layer:

SELECT-only — Only SELECT statements are permitted; any DML/DDL is rejected
Table allowlist — Queries can only access approved rm_* tables
Row limit — Maximum 10,000 rows returned per query
Execution timeout — Queries are killed after 5 seconds
Parameter binding — All user inputs (dates, site IDs) are parameterized via wpdb::prepare()

Performance Indexes

Migration 020 adds analytics-specific indexes for high-volume tables:

Table	Index	Purpose
`rm_lineitems`	`idx_item`	Top Selling Products report (2.6M+ rows)
`shipments`	`idx_order_id`	Shipping Performance and fulfillment KPI
`shipments`	`idx_shipping_provider`	Shipping Performance GROUP BY
`rm_order`	`idx_site_dateadded`	Site-filtered date range queries (all reports)
`rm_address`	`idx_order_type`	Geographic Sales report (1.7M+ rows)
`rm_items`	`idx_sku`	SKU lookups in reports and order processing

Architecture

Data Flow

User selects report, date range, and optional site filter
React app sends POST to /analytics/reports/{slug}/execute
Report_Executor validates parameters (date format, 12-month max range)
SQL query runs against the tasks database with parameterized inputs
cast_column_types() converts string values to proper numeric types (required for Recharts)
JSON response rendered as chart + sortable table

Dashboard Loading

Dashboard data is optimized for fast initial render:

Reports list and sites data are inlined into the page via wp_localize_script (eliminates 2 REST API calls on load)
Only the KPI dashboard fetch requires a REST API call
KPI fetch fires immediately on mount (no initial debounce delay)

Email Reports — Automated email-based reporting
Performance Optimization — Query and index optimizations
Crontab Generator — Schedule automated report delivery

Overview​

KPI Dashboard​

Date Range Selection​

Caching​

Available Reports​

Category: Sales & Revenue​

Category: Operations​

Category: Health & Monitoring​

Interface​

Report Navigation​

Report Viewer​

Deep Linking​

REST API Endpoints​

List Available Reports​

Execute a Report​

Dashboard KPIs​

List Sites​

SQL Security Layer​

Performance Indexes​

Architecture​

Data Flow​

Dashboard Loading​

Related Documentation​