br-woo-analytics

Better Route WooCommerce Analytics

Use the report service for staff reporting over native WooCommerce Analytics. Register only the reports the application needs; the CRUD registrar does not add them.

Register a report

use BetterRoute\BetterRoute;
use BetterRoute\Http\Response;
use BetterRoute\Integration\Woo\WooAnalyticsOpenApi;

add_action('rest_api_init', static function (): void {
    $analytics = BetterRoute::wooAnalyticsService();
    $router = BetterRoute::router('myapp', 'v1');
    $report = 'revenue/stats';
    $router->get('/analytics/revenue', static function ($request) use ($analytics, $report): Response {
        return new Response(
            $analytics->report($report, $request),
            200,
            ['Cache-Control' => 'private, no-store']
        );
    })
        ->permission(static fn (): bool => current_user_can('view_woocommerce_reports'))
        ->args(WooAnalyticsOpenApi::args($report))
        ->meta(WooAnalyticsOpenApi::meta($report));
    $router->register();
});

This example uses the current native WP user. Add the application's actual authentication before accessing reports. JWT/Bearer middleware must establish the native WP identity; protectedByMiddleware() declares intent but adds no auth. Keep application rate limits and avoid shared response caches.

The service always enforces view_woocommerce_reports and dispatches through native REST permission checks under that same user. Stock retains its extra native product permissions. There is no loopback HTTP request, privilege elevation or import trigger.

Reports and queries

Use reports() to obtain the fixed report list:

revenue/stats, orders/stats, products, products/stats, categories, customers, customers/stats, coupons, coupons/stats, taxes, stock, variations.

• after/before are ISO8601 datetimes, defaulting to the last seven days in the shop timezone. Explicit offsets are converted to that timezone. The maximum window is 366 days, or 31 days for hourly intervals. Reversed windows fail.
• compare_after and compare_before must be supplied together. Each window is independently validated; comparison output is returned in comparison.
• Paginated reports accept page 1..10000 and per_page 1..100. Over-limit values fail rather than clamp. Use report-specific orderby, order and segmentby.
• interval is hour/day/week/month/quarter/year only for reports that support it. customers/stats maps dates to registration dates and accepts no pagination or interval. Stock accepts no dates or comparison window.
• Unsupported query keys fail, including WordPress globals _locale, _fields, _embed and context. Do not apply the CRUD parser's global-parameter allowance to Analytics. An adapter may remove a known transport-only key such as _locale; continue rejecting every other unsupported key rather than silently dropping all unknown parameters.