WooCommerce Advanced Report Builder

A configurable WordPress/WooCommerce report-builder plugin. Instead of shipping only fixed reports, it lets administrators define datasets, dimensions, measures, filters, grouping, formulas, pivots, visualizations, dashboards, exports, schedules, alerts and access rules.

Primary goal

The WooCommerce adapter treats product structure as first-class report data. Reports can be built around:

• Product type: simple, variable, grouped, external and custom WooCommerce product types.
• Parent products and variations.
• Product categories, including an exploded category dimension that generates one analytical row per assigned category.
• Product tags.
• Global WooCommerce attributes (pa_*) as individual reportable fields.
• All/local product attributes as a searchable summary field.
• Variation attribute values and variation SKUs.
• Price, sale price, regular price, stock quantity/status, backorders and lifetime sales.
• Order-item sales joined conceptually with parent product, variation, category, attributes, customer, payment method and currency.

This makes reports such as these configurable rather than hard-coded:

• Sales by product type.
• Sales by category.
• Sales by color/size/brand attribute.
• Sales by parent product and variation.
• Inventory by product type/category/attribute.
• Variable-product performance.
• Product profitability when a recognized cost field is available.
• Order/customer/payment/geography reports.

Included datasets

WooCommerce Products

Product identity, SKU, type, status, pricing, inventory, categories, tags, all attributes/features, individual global attributes, ratings, dates and ACF product fields when ACF is active.

WooCommerce Product Variations

Variation SKU/name, parent product/type, categories, variation attributes, individual global attributes, pricing, stock and cost where available.

WooCommerce Sales / Order Items

The most powerful commerce dataset. Each line exposes order, customer, currency, payment, parent product, product type, categories, variation, attributes, quantity, refunds, net sales and optional estimated cost/profit.

WooCommerce Orders

Order status/dates, customer/geography, currency, subtotal, discount, shipping, tax, refunds, total/net total, payment, shipping methods and coupons.

WooCommerce Customers

Registered and guest customers are both included. Customer aggregation is kept separated by currency to avoid mathematically invalid cross-currency totals.

WordPress Posts / Custom Post Types

Posts and UI-visible CPTs with status, author, dates, taxonomies and ACF fields when available.

WordPress Users

User identity, roles and registration date with PII controls.

Registered Custom Tables

Administrators may register an existing database table as a read-only dataset and explicitly whitelist columns. No arbitrary write SQL is accepted.

Builder capabilities

• Select display columns.
• Multi-level grouping.
• Metrics: SUM, AVG, MIN, MAX, COUNT and COUNT DISTINCT.
• Filters: equals, not equals, contains, not contains, starts/ends with, IN/NOT IN, numeric/date comparison, BETWEEN, empty/non-empty.
• Relative date shortcuts: @today, @yesterday, @last7, @last30, @thismonth, @lastmonth.
• Relative dates stay dynamic in saved/scheduled reports.
• Safe calculated fields using {field} references and arithmetic + - * / % with parentheses. No PHP eval().
• Table, bar, line, pie, KPI and pivot views.
• Sorting and output limits.
• Saved report definitions.
• Report visibility: private, all report users, or selected WordPress roles.
• Dashboards composed from saved reports.
• Built-in templates.
• CSV and genuine XLSX export.
• Print view.
• Scheduled email reports.
• Threshold alerts by email and optional HTTPS webhook.
• REST endpoint for authenticated/authorized report execution.
• Front-end shortcode (disabled by default): [advanced_report_builder id="123"].
• Report result caching with version invalidation on relevant WooCommerce/WordPress changes.
• Audit log table for report actions.

Built-in templates

• Sales by Product Type
• Sales by Category
• Variation Sales
• Product Attribute Explorer
• Inventory by Product Type
• Orders by Payment Method
• Customer Value

Templates are ordinary saved definitions after installation and remain fully editable.

Product category semantics

Two category representations are exposed:

• All Categories: a combined display/filter string for the product.
• Category (one row per assigned category): an exploded analytical dimension. If a product belongs to multiple categories, the same sale can be attributed to each assigned category. Therefore, summing all exploded category groups can exceed store-wide revenue. This is expected membership-analysis behavior and is explicitly exposed rather than hidden.

Attributes and features

Global WooCommerce attributes are discovered dynamically with wc_get_attribute_taxonomies() and registered as independent fields, for example:

• attribute_pa_color
• attribute_pa_size
• attribute_pa_brand

Local/non-taxonomy product attributes are included in the All Attributes / Features summary. Variation datasets additionally expose variation-specific attribute values.

Jalali and Gregorian dates

The selected calendar is an input/output concern only. WooCommerce/WordPress data remains canonical. Jalali input is converted to Gregorian boundaries before querying/filtering, and returned dates are formatted through the selected calendar.

Settings include:

• Gregorian or Jalali calendar.
• Gregorian and Jalali display formats.
• Site timezone through WordPress wp_timezone().

HPOS

The plugin declares compatibility with WooCommerce High-Performance Order Storage (custom_order_tables) and retrieves orders through WooCommerce CRUD/query APIs (wc_get_orders, WC_Order, etc.) rather than assuming orders live in wp_posts / wp_postmeta.

Currency handling

The plugin does not silently combine currencies for customer aggregation templates. Customer rows are split by identity + currency. Sales templates include currency as a group dimension by default. Display formatting uses the row currency when present.

If you intentionally remove currency from a grouped multi-currency report, you are responsible for ensuring the underlying values are comparable or already normalized.

Cost/profit fields

The plugin checks common cost meta keys (_wc_cog_cost, _alg_wc_cog_cost, _cost_price, cost_price). Estimated cost/profit remains empty when a cost value is unavailable. It does not invent margins.

Security

• WordPress capability checks on menus and mutations.
• Nonces on saves, deletes, exports and print actions.
• PII-aware fields and masking.
• Administrators receive all plugin capabilities by default.
• Shop Managers receive operational report/create/edit-own/delete/export/schedule capabilities, but not data-source/settings/PII-management capabilities by default.
• CSV spreadsheet-formula injection protection.
• Custom table identifiers and columns are administrator-registered and whitelisted.
• Custom table sources are SELECT/read-only.
• Formula language contains arithmetic only; no arbitrary functions or executable PHP.
• Optional webhooks must use HTTPS and are sent with WordPress safe HTTP APIs.

Capabilities

• wcrb_view_reports
• wcrb_create_reports
• wcrb_edit_own_reports
• wcrb_edit_all_reports
• wcrb_delete_reports
• wcrb_export_reports
• wcrb_schedule_reports
• wcrb_manage_data_sources
• wcrb_manage_settings
• wcrb_view_pii

Database tables

The plugin creates:

• {prefix}wcrb_reports
• {prefix}wcrb_dashboards
• {prefix}wcrb_schedules
• {prefix}wcrb_audit

Data is retained on uninstall unless Delete plugin tables/settings on uninstall is explicitly enabled.

Performance model

The builder has configurable safeguards:

• Maximum rows scanned per run.
• Preview row limit.
• Result cache TTL.
• WooCommerce order date/status filters are pushed into wc_get_orders() where implemented.
• Large final result sets are capped by the report output limit.

This V1 intentionally favors storage compatibility and a generic builder abstraction over direct SQL against WooCommerce order tables. Large enterprise stores should benchmark/report-specific workloads and can extend dataset adapters through the provided hook.

Extension point

Register additional datasets on:

add_action( 'wcrb_register_datasets', function ( $registry ) {
    $registry->register( new My_Custom_Dataset() );
} );

The dataset must implement WCRB\Contracts\DatasetInterface.

The final result can be modified with wcrb_report_result.

REST API

Authenticated users with wcrb_view_reports can use:

• GET /wp-json/wcrb/v1/reports
• GET /wp-json/wcrb/v1/reports/{id}/run

Sensitive fields are passed through the same PII export masking before REST output.

Installation

1. Upload the ZIP from Plugins → Add New → Upload Plugin.
2. Activate WooCommerce Advanced Report Builder.
3. Open Report Builder in WordPress admin.
4. Install a template or start a new report.
5. For sales reports by attribute/category/variation, start with WooCommerce Sales / Order Items.
6. Configure calendar, performance and privacy under Report Builder → Settings.

Validation status

The packaged source is statically validated with the available PHP runtime and JavaScript parser in the build environment. XLSX uses the plugin's self-contained ZIP writer and does not require PHP ZipArchive.

A live WordPress + WooCommerce database/plugin matrix is still required before production deployment, especially when using third-party product types, custom cost-of-goods plugins, large stores, ACF configurations or custom tables.

License

MIT