Skip to main content

Analytics Reports

Better Route 1.1.2 provides an opt-in read-only Analytics service. WooRouteRegistrar does not add report routes automatically. Register only the reports the application needs.

use BetterRoute\Integration\Woo\WooAnalyticsService;
use BetterRoute\Integration\Woo\WooAnalyticsOpenApi;
use BetterRoute\Router\Router;

add_action('rest_api_init', static function (): void {
$service = new WooAnalyticsService();
$report = 'orders/stats';
$router = Router::make('myapp', 'v1');
$router->get('/analytics/orders/stats', static fn ($request): array => $service->report($report, $request))
->args(WooAnalyticsOpenApi::args($report))
->meta(WooAnalyticsOpenApi::meta($report))
->permission(static fn (): bool => current_user_can('view_woocommerce_reports'));
$router->register();
});

The example expects native WordPress authentication, such as Application Passwords over HTTPS. For JWT/Bearer, configure issuer-safe native WP user mapping and actual authorization; a token claim or permissive route callback alone does not establish the native user.

Supported reports and queries​

Reports: revenue/stats, orders/stats, products, products/stats, categories, customers, customers/stats, coupons, coupons/stats, taxes, stock and variations. The allowlist is fixed; the service is not an arbitrary native REST proxy.

ParameterContract
after / beforeDatetimes with optional offsets; omitted offset uses shop timezone; default last seven days
compare_after / compare_beforeBoth required together; independently validated comparison window
page / per_pagePaginated reports: page 1–10000, per_page 1–100; defaults 1/20
orderby / orderReport-specific orderby allowlist; asc/desc, stock defaults asc and other reports desc
intervalWhere supported: hour/day/week/month/quarter/year; default day
segmentbyOnly each report's declared segment allowlist

Windows must be ordered and at most 366 days; hourly windows at most 31 days. Stock accepts no dates/comparison. Customers/stats has no pagination or interval. Use the helper args or AnalyticsReports::definition() for exact report-specific availability.

Unknown parameters return 400, including _locale, _fields and context. Unlike CRUD, Analytics does not accept WordPress global query arguments; configure frontend clients such as wp.apiFetch accordingly.

Permissions and readiness​

The service mandates the current native WP user's view_woocommerce_reports and preserves upstream report permissions. Stock can require additional native capabilities. It performs internal native REST dispatch without loopback HTTP, user elevation or a wrapper response cache.

Disabled/unavailable Analytics returns analytics_unavailable 503. Unknown, running, incomplete or insufficient historical import coverage returns analytics_data_not_ready 503, checking both primary and comparison windows. Stock has no import-readiness gate. The wrapper starts no imports. Configure imports operationally; idle means import state, not guaranteed realtime freshness.

Response and OpenAPI​

The response is {report,data,meta,comparison?} without another data envelope. Stats contain totals/intervals, collections contain items, and meta.totalUnit distinguishes intervals/items. Customers/stats only includes readiness metadata. Comparison contains a nonrecursive result.

Money, including monetary averages, is a decimal string. Counts are integers and non-monetary averages can be fractional numbers. The mapper strips unknown extension fields and links. Empty metric maps serialize as objects.

Merge BetterRoute::wooOpenApiComponents() into export options and enable strictSchemas. The helper supplies report parameters and schemas, not authentication definitions: configure the application's real security schemes/global or per-route requirements separately. Override the helper operation ID if exposing one report more than once.

Tested scope​

The 2.0 CI uses WP 6.9.4/Woo 10.9.4, PHP 8.3/8.5 and HPOS/CPT. Synthetic native lookup data covers all twelve reports, reports-only users, comparison, readiness, projection and identity preservation; external JSON Schema validation checks actual responses. Readiness providers are request-local fixtures. This does not establish a complete background import, an external identity-provider deployment or every WP/Woo version combination.