Ecommerce Tracking
Pro
All features on this page require Burst Statistics Pro.
Burst Statistics Pro includes ecommerce tracking for WooCommerce and Easy Digital Downloads. It records cart activity, order data, and visitor behaviour, then surfaces that data through four dashboards: Sales, Funnel, Quick Wins, and Top Performers.
Overview
When ecommerce tracking is active the plugin adds a should_load_ecommerce flag to the frontend tracking options, which instructs the JavaScript tracker to listen for cart and order events. Backend integrations (WooCommerce, EDD) fire two WordPress actions — burst_order_created and burst_cart_updated — which write to dedicated database tables.
Database tables
| Table | Purpose |
|---|---|
{prefix}burst_orders | One row per completed order |
{prefix}burst_order_items | One row per line item in an order |
{prefix}burst_cart | One active cart per visitor |
{prefix}burst_cart_items | Items currently in a cart |
All monetary values stored in burst_orders and burst_order_items carry a conversion_rate column so that multi-currency stores can be normalised to the store's base currency in reports.
Actions
burst_order_created
Fired when a completed order should be recorded. The ecommerce integration (WooCommerce, EDD, or a custom integration) fires this action and passes the full order payload. Burst uses it to write rows to burst_orders and burst_order_items, then marks the visitor's active cart as converted.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$data | array | Order data (see fields below) |
$data fields:
| Key | Type | Required | Description |
|---|---|---|---|
currency | string | Yes | ISO 4217 currency code (e.g. 'USD') |
total | float | Yes | Order total before tax |
tax | float | No | Tax amount (default 0.0) |
platform | string | Yes | Integration identifier (e.g. 'WooCommerce', 'EDD') |
conversion_rate | float | Yes | Exchange rate relative to the store base currency (use 1.0 for single-currency stores) |
products | array | Yes | Array of product line items (see below) |
Each item in products:
| Key | Type | Required | Description |
|---|---|---|---|
product_id | int | Yes | WordPress post ID of the product |
amount | int | Yes | Quantity purchased |
price | float | Yes | Unit price of the product |
Example:
do_action( 'burst_order_created', [
'currency' => 'USD',
'total' => 49.99,
'tax' => 4.50,
'platform' => 'WooCommerce',
'conversion_rate' => 1.0,
'products' => [
[
'product_id' => 42,
'amount' => 1,
'price' => 49.99,
],
],
] );
The action silently returns without recording if platform, total, currency, or conversion_rate are empty, or if any product item is missing product_id, amount, or price. Check your integration logs if orders are not appearing in reports.
burst_cart_updated
Fired whenever the visitor's cart changes (items added, removed, or quantity changed). Pass an empty items array to delete the cart. Burst reconciles the full item list on every call — it replaces all existing cart items with the supplied array.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$data | array | Cart data (see fields below) |
$data fields:
| Key | Type | Description |
|---|---|---|
items | array | Full current contents of the cart. Pass an empty array to clear the cart. |
Each item in items:
| Key | Type | Required | Description |
|---|---|---|---|
product_id | int | Yes | WordPress post ID of the product |
quantity | int | Yes | Item quantity (must be > 0) |
price | float | Yes | Unit price excluding tax (must be >= 0) |
Example:
// Add or update items in the cart.
do_action( 'burst_cart_updated', [
'items' => [
[
'product_id' => 42,
'quantity' => 2,
'price' => 24.99,
],
],
] );
// Clear the cart (e.g. after order is placed through a custom flow).
do_action( 'burst_cart_updated', [ 'items' => [] ] );
Filters
burst_tracking_options
Burst adds a should_load_ecommerce key (value true) to the tracking options array passed to the frontend JavaScript tracker. You can inspect or override this behaviour using the existing burst_tracking_options filter.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$options | array | Tracking options passed to the frontend tracker |
Example:
add_filter( 'burst_tracking_options', function( array $options ): array {
if ( is_page( 'staging-preview' ) ) {
$options['should_load_ecommerce'] = false;
}
return $options;
} );
burst_quick_wins_configs
Filters the full array of Quick Wins rule configurations before they are evaluated. Use this to add custom rules, modify thresholds, or remove built-in rules.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$quick_wins | array | Associative array of Quick Wins configs keyed by a unique string identifier |
Each config entry supports the following keys:
| Key | Type | Description |
|---|---|---|
type | string | Priority level: 'critical', 'recommended', or 'opportunity' |
data | callable|mixed | Callable that receives $args (date_start, date_end, filters) and returns a numeric value, or a static value |
conditions | array | Condition definition with keys compare (>, >=, <, <=, ==, !=) and value (float threshold) |
title | string | Translated title shown in the dashboard. Use %d or %f as a placeholder for the actual metric value |
message | string | Translated description of the issue |
recommendation | string | Translated recommended action |
url | string|null | Optional URL to related documentation or article |
Example:
add_filter( 'burst_quick_wins_configs', function( array $configs ): array {
$configs['high_homepage_bounce'] = [
'type' => 'critical',
'data' => function( array $args ): ?float {
return my_plugin_get_homepage_bounce_rate( $args );
},
'conditions' => [
'compare' => '>',
'value' => 80.0,
],
'title' => __( 'Homepage bounce rate is %f%%', 'my-plugin' ),
'message' => __( 'A high homepage bounce rate may indicate a poor first impression.', 'my-plugin' ),
'recommendation' => __( 'Review your homepage hero section and calls to action.', 'my-plugin' ),
'url' => null,
];
return $configs;
} );
Changed in v3.3.0: All built-in Quick Wins queries now JOIN burst_sessions to resolve device_id, browser_id, and first_time_visit. Custom data callables that reference statistics.first_time_visit directly in SQL must be updated to sessions.first_time_visit. Similarly, any direct references to statistics.device_id or statistics.browser_id must be updated to sessions.device_id / sessions.browser_id.
Quick Wins are only evaluated after ecommerce tracking has been active for at least 7 days. Rules with a data callable that throws an exception are skipped and logged, but do not halt other rules.
Sales analytics
The Sales dashboard shows four key metrics for the selected date range, each compared to the equivalent previous period of the same length.
| Metric | Description |
|---|---|
| Conversion Rate | Percentage of unique visitors who completed a purchase (converted / visitors × 100) |
| Abandoned Carts | Percentage of carts that were not converted and have been inactive for more than 30 minutes (abandoned / total_carts × 100) |
| Average Order Value | Mean revenue per order in the store's base currency, normalised using each order's conversion_rate |
| Revenue | Total revenue across all orders in the base currency, normalised using each order's conversion_rate |
Each metric is returned with current, previous, and rate_change keys. rate_change is null when either period has no data.
A cart is classified as abandoned only when its updated_at timestamp is more than 30 minutes in the past and converted = 0. Carts updated within the last 30 minutes are still considered active and excluded from the abandonment count.
The data layer functions that assemble Sales and Top Performers payloads (modify_product_data() and get_ecommerce_data()) both guard with user_can_view_sales() and return the unmodified data array immediately if the check fails. Changed in v3.3.0: this capability check is enforced at the data layer in addition to the REST API permission callback.
Funnel tracking
The Funnel dashboard visualises the five stages of the purchase journey. Each stage returns the count of unique visitors (uid) who reached that stage within the selected date range.
| Stage | ID | Description |
|---|---|---|
| Visitors started session | visits | All unique visitors in the date range |
| Viewed a product | product_page_views | Visitors who viewed a page with page_type = 'product' or page_type = 'download', or the configured product archive page |
| Added to cart | add_to_cart | Visitors who have at least one burst_cart_items row with added_at within the range |
| Started checkout | checkout_visits | Visitors who viewed the configured WooCommerce/EDD checkout page |
| Purchased | conversions | Visitors who have at least one row in burst_orders linked to their statistics record |
Drop-off between stages is calculated on the frontend from the raw counts.
Quick Wins
Quick Wins are automated insights that surface when a metric crosses a configured threshold. They are calculated once per day via a WordPress cron chain and cached in the burst_quick_wins option.
Each rule examines data from the last 31 days (31 days ago 00:00:00 through yesterday 23:59:59). If the ecommerce activation date falls within that window, the window is trimmed to start at the activation date.
Built-in metrics evaluated by Quick Wins
The following metrics are computed internally and can also be re-used in custom rules via the burst_quick_wins_configs filter. All methods accept an $args array with date_start (int, Unix timestamp), date_end (int, Unix timestamp), and filters (array).
Changed in v3.3.0: all underlying queries for these metrics JOIN burst_sessions on statistics.session_id = sessions.ID to resolve device_id, browser_id, and first_time_visit. The first_time_visit condition is now evaluated against sessions.first_time_visit rather than statistics.first_time_visit.
| Method | Return type | Description |
|---|---|---|
get_cart_abandonment_rate( $args ) | float|null | Cart abandonment rate as a percentage |
get_checkout_completion_rate( $args ) | float|null | Percentage of checkout page visitors who converted |
get_avg_checkout_completion_time( $args ) | int|null | Average time spent on the checkout page in seconds |
get_safari_checkout_abandonment_delta( $args ) | float|null | Difference in abandonment rate between Safari and all browsers combined (percentage points) |
get_cart_drop_off_rate( $args ) | float|null | Percentage of visitors who did not add anything to their cart |
get_cart_to_checkout_rate( $args ) | float|null | Percentage of cart starters who did not convert (cart exit rate) |
get_average_order_value( $args ) | float|null | Average order value in the store currency (not normalised) |
get_email_campaign_conversion_rate( $args ) | float|null | Conversion rate of visitors arriving via email campaigns |
get_returning_customer_rate( $args ) | float|null | Percentage of orders from customers who had a prior converted cart |
get_new_visitor_conversion_rate( $args ) | float|null | Conversion rate of first-time visitors |
get_returning_vs_new_visitor_cr_ratio( $args ) | float|null | Ratio of returning-visitor CR to new-visitor CR |
get_home_page_bounce_rate( $args ) | float|null | Bounce rate on the homepage (/) |
get_product_page_exit_without_add_to_cart_rate( $args ) | float|null | Percentage of product/download page visitors who left without adding to cart |
get_single_product_exit_rate( $args ) | float|null | Percentage of visitors who viewed exactly one product/download page and left without adding to cart |
get_avg_session_duration( $args ) | float|null | Average session duration in seconds |
get_mobile_vs_desktop_conversion_ratio( $args ) | float|null | Ratio of mobile+tablet CR to desktop CR |
Dismissing and snoozing Quick Wins
Users can dismiss or snooze individual Quick Wins from the dashboard. Dismissed IDs are stored permanently in burst_quick_win_dismissed_wins. Snoozed IDs are stored in burst_quick_win_snoozed_wins as a map of id => unix_expiry_timestamp. The default snooze period is 30 days.
Top Performers
The Top Performers dashboard shows the single highest-revenue entry in four dimensions for the selected period, with a comparison to the previous period of the same length.
| Dimension | ID | Fields returned |
|---|---|---|
| Top product | top-product | product_id, product_name, total_quantity_sold, total_revenue, currency |
| Top campaign | top-campaign | campaign_id, campaign_name, total_quantity_sold, total_revenue, currency |
| Top country | top-country | country_code, total_quantity_sold, total_revenue, currency |
| Top device | top-device | device_name, total_quantity_sold, total_revenue, currency |
Each dimension returns current, previous, and revenue_change keys. revenue_change is null when either period has no orders. Revenue figures are normalised to the store's base currency using each order's conversion_rate.
For product variations, the product name is formatted as Parent Product Name (Variation Description).
Changed in v3.3.0: the top-device query (and all Top Performers dimension queries) now JOIN burst_sessions on sessions.ID = statistics.session_id and resolve device_id via sessions.device_id rather than statistics.device_id.
WordPress cron events
| Event hook | Trigger | Description |
|---|---|---|
burst_daily | Daily | Schedules the Quick Wins processing chain |
burst_process_quick_wins_single_event | Chained, 1 minute apart | Evaluates one Quick Win rule per invocation; schedules the next index until all rules are processed |