Analytics

Analytics is a React application inside WooCommerce Admin. It lives under WooCommerce > Analytics, with these pages (the menu items come from Analytics::get_report_pages() in the 11.2.1 source and can be changed with the filter woocommerce_analytics_report_menu_items):

Source: WooCommerce docs: Extend analytics reports

The older WooCommerce > Reports screen that the books describe (sales by date, by product, by category, customer lists, stock and tax reports) is a different mechanism: it builds its figures by querying orders directly. In 11.2.1 the screen still answers at admin.php?page=wc-reports, and the core source comments say the legacy reports will be moved to a separate plugin. New work should target Analytics: it scales better because it reads precomputed tables, it has a REST API, and it is what the extension points in this page hook into. A book recipe that reads _order_total or _order_currency from wp_postmeta for a report is wrong on a store that uses HPOS, where those values live in wc_orders.

Analytics never reads orders while a report is rendered. It reads lookup tables that WooCommerce keeps in step with the orders: one narrow, indexed row per order, per order line, per coupon use and per tax line, plus one row per customer. These are the tables of the 11.2.1 schema, with the columns listed by the database of the test store:

Source: WooCommerce source: OrdersScheduler (11.2.1)

Two consequences matter in practice. First, a report can only be as current as the lookup tables: an order that has not been imported yet is not in any report, whatever its status says. Second, the lookup tables are derived data. They can be rebuilt from the orders at any time (the import below), so a custom extension should add columns or side tables rather than edit rows by hand, and should never treat them as the source of truth for money.

The figure shows the whole path. The upper row is the reporting pipeline; the lower box is the CSV export, which reuses the same REST controllers from the background.

Analytics > Settings writes WordPress options, and the same group is readable and writable over wc/v3/settings/wc_admin:

Source: WooCommerce source: Analytics settings (11.2.1)

The date type is the setting that surprises shop owners most. With the default date_paid, an order that has not been paid has no date, so a date-ranged report leaves it out until it is paid. Pocket Coffee offers bank transfer (BACS), whose orders wait in on-hold. At the time of the test, the Orders report for 2026 in euros showed 10 orders with date_paid, none of them on hold, and 23 orders with date_created, 12 of the extra rows on hold; the totals moved from 306.90 to 661.51 for the same orders. Neither answer is wrong: paid revenue and booked revenue are different questions, and the setting should be chosen on purpose and written down.

Source: WooCommerce docs: WC-CLI overview

The first request returned the five settings above with their types (multiselect, multiselect, text, select, radio) and their current values. The filters that decide the defaults take plain arrays, for example (checked on the test store, where the default list became pending,cancelled,failed,refunded):

Source: WooCommerce source: Analytics settings (11.2.1)

The React app is a client of the wc-analytics REST namespace, and so can any script with a key that carries the view_woocommerce_reports capability. The routes are not part of the public REST API documentation: they are an internal API of WooCommerce Admin, stable enough to build extensions on (the extension points below use them) but not guaranteed across majors, so integrations should pin the WooCommerce version they test against.

The common parameters are after and before (ISO 8601, interpreted in the store’s timezone), interval, per_page (up to 100), page, orderby, order, status_is, status_is_not, product_includes, coupon_includes, customer_type, refunds and force_cache_refresh. A request on the test store:

Source: WooCommerce source: Analytics report controllers (11.2.1)

returned a totals object with orders_count 11, num_items_sold 19, gross_sales 395.8, refunds 41.8, shipping 18.4 and net_revenue 354 at the time of the run; the figures change as other orders are created, which is exactly the point of reading them from the API instead of copying them into a document.

The official guide extends the Orders report with a currency selector. Its SQL joins wp_postmeta on _order_currency, which is the book-era storage and returns nothing useful on a store that keeps orders in the HPOS tables. The version below is the same idea rewritten for 11.2.1: it reads the currency from whichever storage is authoritative, carries the selection through the REST request, the cache key and the export, and is checked with PHPCS. It is the Pocket Coffee plugin pocket-coffee-analytics, in three files.

The Download button on every report, and the email link option for large reports, call the export route and then poll its status. The pieces:

Source: WooCommerce source: ReportExporter (11.2.1)

The answer on the test store was {"message": "Your report file is being generated.", "export_id": "17931274599644"} (trimmed). After the batch had run (the queue limited to woocommerce_admin_report_export), the status call returned percent_complete 100 and the download URL, and the body of the file held only the two dollar orders; the header row sits in the .headers file:

(The first two lines are cut -d, -f2,3,4,12 of the body; the last is the .headers file, whose last column is the one the plugin added.) The CSV columns come from two filters for the orders report, woocommerce_report_orders_export_columns (key and label) and woocommerce_report_orders_prepare_export_item (the row, given the column array and the report item). The other reports implement the same ExportableInterface (get_export_columns() and prepare_item_for_export()) and have equivalent filters; a report type that has no controller of its own falls back to the columns of the REST schema. A completely new report can be exported by adding its controller class to the map filtered by woocommerce_export_report_controller_map (the filter was added in 9.8.0). The row of each report passes finally through woocommerce_export_{export_type}_row_data.

The pitfall this section exists for is the one in the extension figure: a filter written against $_GET works on screen and silently exports everything, because the batches have no query string. This is also why the plugin registers a hook on the batch action and reads report_args in the export request: the official guide stops at the live report.

The lookup rows themselves can be adjusted when they are written. woocommerce_analytics_update_order_stats_data receives the array written to wc_order_stats and the order; the data stores fire woocommerce_analytics_update_order_stats, woocommerce_analytics_update_product, woocommerce_analytics_update_coupon and woocommerce_analytics_delete_order_stats after a row is written or removed, which is where an extension keeps a side table in step. A new importable data set (for example, a table of supplier costs for a margin report) is a scheduler: a class that extends Automattic\WooCommerce\Internal\Admin\Schedulers\ImportScheduler, added to the list returned by the filter woocommerce_analytics_report_schedulers, so that it takes part in the historical import, the delete and the batch queue; ReportsSync throws an exception for anything in that list that is not such a subclass. The class is marked internal, so such an extension should be tested against every WooCommerce release it claims to support. Two smaller filters apply to customers: woocommerce_analytics_import_customer_roles (default customer) chooses which WordPress roles are imported into wc_customer_lookup, and woocommerce_analytics_disable_action_scheduling makes the imports run synchronously (use it in tests only).

Source: WooCommerce source: Analytics report controllers (11.2.1)

The books treat reporting as a screen you look at: WooCommerce Cookbook and Building E-Commerce Solutions with WooCommerce (WooCommerce 2.x) walk through the Sales, Customer, Stock and Tax reports of WooCommerce > Reports, and Building Your Online Store With WordPress and WooCommerce shows Google Analytics on the same screens. None of them knows the lookup tables, the Action Scheduler pipeline, the REST namespace or the export; their recipes that sum _order_total postmeta (or read wp_posts for orders) return nothing on an HPOS store. Tracking with Google Analytics is a separate concern from Analytics: a snippet that fires on the order-received page of the classic checkout must be reviewed for the Checkout block, which does not run the classic template hooks (see Cart and Checkout blocks).

On the local WordPress 7.1.3 and WooCommerce 11.2.1 stack (PHP 8.3.36, MariaDB 11.8.9, HPOS enabled, Action Scheduler 4.1.0) the following ran and produced the outputs above: the lookup tables' column lists; the import REST routes (totals, start, status) and the queue run with WP-CLI until the import finished; the orders and stats REST routes with and without the currency parameter; the CSV export through REST, the batch, the status route and the generated file; the settings route; the date type experiment (date_paid against date_created) with its cache invalidation; the filters woocommerce_analytics_is_test_order, woocommerce_analytics_import_interval and woocommerce_analytics_settings_default_excluded_order_statuses; PHPCS (WooCommerce-Core) and php -l on the plugin, and node --check on the script; and a login with an administrator cookie to confirm that the script is enqueued on the Analytics page.

Not run: the React screens in a browser (the dropdown, the column and the Download button were not clicked); the email option of the export (there is no mail server in the container); delete and cancel of the import (they would empty the shared test store’s reports); scheduled mode for more than one cycle (the 12-hour action was seen scheduled but did not fire); posts-based order storage (the plugin’s postmeta branch was not executed); and the test-mode orders of WooPayments (it needs an account).