Hooks & filters

Reference for the core and commonly used WordPress actions and filters provided by Burst Statistics v3.4.3. Use these to extend or modify plugin behaviour without editing core files.

This page is the central reference for general-purpose hooks that are useful across integrations, tracking, settings, and UI customization. It is not intended to duplicate every domain-specific hook already documented elsewhere in the docs.

Use the dedicated pages below for feature-specific hooks and extension points:

• Goals reference
• Reports
• REST API
• Statistics API
• Tracking
• Integrations
• Upgrading Burst Statistics
• Ecommerce tracking
• Geo-IP tracking
• A/B testing
• Anomaly detection
• License activation

For production-ready snippets, see the public Burst Integrations examples repository: burst-integrations. Most of those examples are intended for an mu-plugin or early-loaded custom code rather than direct edits to the plugin.

---

Actions

burst_after_save_field

Fires immediately after a Burst settings field is saved.

Parameters:

Parameter	Type	Description
$name	string	The sanitized option name.
$value	mixed	The new (sanitized) value.
$prev_value	mixed	The previous value before saving.
$type	string	The field type (e.g. checkbox, text).

Example:

Show code

add_action( 'burst_after_save_field', function( $name, $value, $prev_value, $type ) {
    if ( $name === 'cookieless_tracking' ) {
        my_plugin_handle_cookieless_change( $value, $prev_value );
    }
}, 10, 4 );

---

burst_every_ten_minutes

Cron action that fires every 10 minutes.

Parameters: none

Example:

add_action( 'burst_every_ten_minutes', function() {
    // Run your task every 10 minutes.
} );

---

burst_every_hour

Cron action that fires every hour.

Parameters: none

Example:

add_action( 'burst_every_hour', function() {
    // Run your task every hour.
} );

---

burst_daily

Cron action that fires once per day.

Parameters: none

Example:

add_action( 'burst_daily', function() {
    // Run your daily task.
} );

Changed in v3.4.0: Burst now hooks its own cleanup_viewer_sessions routine onto burst_daily to guarantee that share-link viewer sessions never exceed 24 hours. Third-party callbacks attached to burst_daily continue to run as before.

---

burst_weekly

Cron action that fires once per week.

Parameters: none

Example:

add_action( 'burst_weekly', function() {
    // Run your weekly task.
} );

---

burst_monthly

Cron action that fires once per month.

Parameters: none

Example:

add_action( 'burst_monthly', function() {
    // Run your monthly task.
} );

---

burst_before_create_statistic

Fires immediately before a new row is inserted into burst_statistics.

:::caution Breaking change Changed in v3.3.0: $statistic no longer contains session-level fields (bounce, browser_id, browser_version_id, platform_id, device_id, first_time_visit). These fields are now stored exclusively in burst_sessions. Code that read or modified those keys on $statistic inside this action must be updated. :::

Parameters:

Parameter	Type	Description
$statistic	array	Sanitized data array containing only burst_statistics column fields.

Example:

Show code

add_action( 'burst_before_create_statistic', function( $statistic ) {
    // $statistic no longer contains bounce, browser_id, device_id, etc.
    if ( ! empty( $statistic['page_url'] ) ) {
        my_plugin_log_page( $statistic['page_url'] );
    }
} );

---

burst_after_create_statistic

Fires immediately after a new row is inserted into burst_statistics.

:::caution Breaking change Changed in v3.3.0: $statistic no longer contains session-level fields (bounce, browser_id, browser_version_id, platform_id, device_id, first_time_visit). These fields are now stored exclusively in burst_sessions. Code that read those keys on $statistic inside this action must be updated. :::

Parameters:

Parameter	Type	Description
$insert_id	int	The ID of the newly created burst_statistics row (0 on failure).
$statistic	array	Sanitized data array containing only burst_statistics column fields.

Example:

Show code

add_action( 'burst_after_create_statistic', function( $insert_id, $statistic ) {
    if ( $insert_id > 0 ) {
        my_plugin_post_process( $insert_id, $statistic['page_url'] );
    }
}, 10, 2 );

---

burst_detect_malicious_data

Single scheduled event that runs the malicious-data detection sweep. It is scheduled roughly two minutes after burst_daily fires to avoid the race where tables are briefly missing right after reinstalling or resetting Burst.

Added in v3.4.0.

Parameters: none

Example:

add_action( 'burst_detect_malicious_data', function() {
    my_plugin_record_malicious_sweep_started( time() );
} );

---

burst_purge_mainwp_nonce

Scheduled single event that deletes a consumed MainWP dashboard nonce option once it falls outside the acceptance window. Burst schedules this event roughly six minutes after each successful MainWP signature verification so the single-use nonce record stored in wp_options is cleaned up automatically.

Added in v3.4.2.

Parameters:

Parameter	Type	Description
$option_key	string	The full option name to delete, prefixed with burst_mainwp_nonce_.

Example:

add_action( 'burst_purge_mainwp_nonce', function( $option_key ) {
    my_plugin_log_mainwp_nonce_purge( $option_key );
} );

---

burst_order_created

Fires after an order is captured by a Burst ecommerce integration, regardless of platform. WooCommerce and Easy Digital Downloads both emit this action with a normalized payload.

Parameters:

Parameter	Type	Description
$data	array	Normalized order data (see keys below).

$data keys:

Key	Type	Description
currency	string	ISO 4217 currency code.
total	float	Order subtotal excluding tax.
tax	float	Total tax applied to the order.
platform	string	WC for WooCommerce, EDD for Easy Digital Downloads.
products	array	List of line items with product_id, amount, price.

Example:

add_action( 'burst_order_created', function( $data ) {
    my_plugin_forward_order_to_crm( $data );
} );

---

burst_woocommerce_order_created

Platform-specific action that fires alongside burst_order_created when the order originates in WooCommerce.

Parameters:

Parameter	Type	Description
$data	array	Normalized WooCommerce order data.

Example:

add_action( 'burst_woocommerce_order_created', function( $data ) {
    my_plugin_handle_wc_order( $data );
} );

---

burst_edd_order_created

Platform-specific action that fires alongside burst_order_created when the order originates in Easy Digital Downloads.

Parameters:

Parameter	Type	Description
$data	array	Normalized EDD order data.

Example:

add_action( 'burst_edd_order_created', function( $data ) {
    my_plugin_handle_edd_order( $data );
} );

---

burst_cart_updated

Fires whenever an ecommerce integration detects a cart change (item added, removed, quantity updated, cart restored).

Parameters:

Parameter	Type	Description
$data	array	{ items: [ { product_id, quantity, price, added_at } ] }.

Example:

add_action( 'burst_cart_updated', function( $data ) {
    my_plugin_sync_cart_snapshot( $data['items'] ?? [] );
} );

---

burst_subscription_update_today

Pro - BusinessAvailable in the Business tier

Only fires when a Burst Pro subscription integration is active (WooCommerce Subscriptions, EDD Recurring, or Subscriben). See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Fires when any subscription lifecycle event happens (signup, renewal, status change, payment failure). Burst uses it to schedule a debounced rebuild of today's subscription aggregates. Third-party code can listen to receive near-real-time subscription notifications.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$plugin_source	string	Integration slug: woocommerce_subscriptions, edd_recurring, subscriben.

Example:

add_action( 'burst_subscription_update_today', function( $plugin_source ) {
    my_plugin_flag_subscriptions_dirty( $plugin_source );
} );

---

burst_subscription_day_finalized

Pro - BusinessAvailable in the Business tier

Fires from the Burst Pro subscription daily aggregator after a single day of subscription rows is finalized. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Fires once per finalized day during the subscription aggregator run. Burst uses it internally so each provider can release its per-request subscription row cache between processed days, preventing memory growth across long backfill batches. Third-party providers should hook in and drop their own per-day caches when $plugin_source matches their integration slug.

Added in v3.4.2.1.

Parameters:

Parameter	Type	Description
$plugin_source	string	Integration slug of the aggregator that finalized the day (e.g. woocommerce_subscriptions).
$day_start	int	Unix timestamp marking the start of the finalized day.

Example:

Show code

add_action( 'burst_subscription_day_finalized', function( $plugin_source, $day_start ) {
    if ( $plugin_source === 'my_plugin' ) {
        my_plugin_release_subscription_day_cache( $day_start );
    }
}, 10, 2 );

---

Filters

burst_option_{name}

Filters the value of any individual Burst option retrieved via burst_get_option(). Replace {name} with the sanitized option name (e.g. burst_option_cookieless_tracking).

Parameters:

Parameter	Type	Description
$value	mixed	The stored option value.
$name	string	The sanitized option name.

Example:

add_filter( 'burst_option_cookieless_tracking', function( $value, $name ) {
    return true; // Force cookieless tracking on.
}, 10, 2 );

---

burst_before_track_hit

Filters the sanitized tracking data array before any hit processing (session lookup, statistic insert/update) takes place.

:::caution Breaking change Changed in v3.3.0: After this filter returns, the session-level fields (bounce, browser_id, browser_version_id, platform_id, device_id, first_time_visit) are extracted from $sanitized_data and written to burst_sessions rather than burst_statistics. Those columns no longer exist in burst_statistics. Modifications to these fields via this filter still take effect, but they are applied to the session row — not to the statistics row. :::

Parameters:

Parameter	Type	Description
$sanitized_data	array	Sanitized tracking data, including session-level fields at this point in the flow.
$hit_type	string	'create' for a new page-view or 'update' for an existing one.
$previous_hit	array	The most recent statistic row for this visitor, or an empty array if none.

Example:

Show code

add_filter( 'burst_before_track_hit', function( $sanitized_data, $hit_type, $previous_hit ) {
    // Modify statistic-level fields only; session-level fields (bounce, browser_id, etc.)
    // will be routed to burst_sessions after this filter returns.
    if ( $hit_type === 'create' ) {
        $sanitized_data['page_url'] = my_plugin_normalize_url( $sanitized_data['page_url'] );
    }
    return $sanitized_data;
}, 10, 3 );

Integration example:

The integrations repo includes several practical uses of this filter, such as excluding specific pages or query parameters from tracking by marking the hit as spammer traffic before it is stored.

Show code

add_filter( 'burst_before_track_hit', function( $sanitized_data ) {
    if ( str_contains( $sanitized_data['parameters'] ?? '', 'autoupdater_nonce=' ) ) {
        $sanitized_data['referrer'] = 'spammer';
    }

    return $sanitized_data;
} );

---

burst_fieldvalue

Filters a settings field value just before it is written to the database.

Parameters:

Parameter	Type	Description
$value	mixed	The sanitized value about to be saved.
$name	string	The sanitized field name.
$type	string	The field type (e.g. checkbox, text).

Example:

Show code

add_filter( 'burst_fieldvalue', function( $value, $name, $type ) {
    if ( $name === 'sample_rate' && (int) $value > 100 ) {
        return 100;
    }
    return $value;
}, 10, 3 );

---

burst_obfuscate_filename

Filters whether the frontend tracking script filename should be obfuscated. When true, the filename is replaced with an 8-character hash derived from the site URL instead of burst.min.js.

Parameters:

Parameter	Type	Description
$obfuscate	bool	true to obfuscate, false to use default name.

Example:

// Always obfuscate the tracking script filename.
add_filter( 'burst_obfuscate_filename', '__return_true' );

---

burst_upload_dir

Filters the base filesystem path used for Burst file uploads (e.g. GeoIP database).

Parameters:

Parameter	Type	Description
$basedir	string	The base upload directory path (no trailing slash).

Example:

add_filter( 'burst_upload_dir', function( $basedir ) {
    return '/mnt/persistent-storage';
} );

---

burst_upload_url

Filters the base URL corresponding to the Burst upload directory.

Parameters:

Parameter	Type	Description
$upload_url	string	The base upload URL (no trailing slash).

Example:

add_filter( 'burst_upload_url', function( $upload_url ) {
    return 'https://cdn.example.com/uploads';
} );

---

burst_is_preview

Filters whether the current request is a page-builder preview. When true, tracking is suppressed.

Parameters:

Parameter	Type	Description
$preview	bool	true if a known page-builder preview parameter is detected.

Example:

Show code

add_filter( 'burst_is_preview', function( $preview ) {
    if ( isset( $_GET['my_preview_mode'] ) ) {
        return true;
    }
    return $preview;
} );

---

burst_enable_logging

Filters whether Burst writes debug messages to the PHP error log. Only active when WP_DEBUG is true.

Parameters:

Parameter	Type	Description
$enabled	bool	true to enable logging, false to suppress it.

Example:

// Disable Burst debug logging even when WP_DEBUG is on.
add_filter( 'burst_enable_logging', '__return_false' );

---

burst_max_shared_link_requests

Filters the maximum number of REST API requests allowed per shared-link token within a one-minute window. Requests beyond this limit are rejected.

Parameters:

Parameter	Type	Description
$max	int	Maximum requests per minute per token (default: 100).

Example:

add_filter( 'burst_max_shared_link_requests', function( $max ) {
    return 50;
} );

---

burst_share_link_permissions

Filters the permission flags sent to the frontend for shared-link viewers.

Parameters:

Parameter	Type	Description
$permissions	array	Associative array of permission flags (see keys below).

$permissions keys:

Key	Type	Description
can_change_date	bool	Whether the viewer may change the date range.
can_filter	bool	Whether the viewer may apply dashboard filters.
is_shareable_link_viewer	bool	true when the current user has the burst_viewer role.

Example:

Show code

add_filter( 'burst_share_link_permissions', function( $permissions ) {
    $permissions['can_change_date'] = true;
    return $permissions;
} );

---

burst_endpoint_tab_map

Filters the map that resolves Burst REST endpoint paths to dashboard tab slugs. Burst uses this map to gate shared-dashboard viewers: a request for an endpoint mapped to a tab that is not in the share token's shared_tabs list is rejected with a 403. Endpoints that are not present in the map are denied by default for shared viewers.

Pro registers additional entries for sources, sales, and settings endpoints. Mapping an endpoint to all makes it reachable from any share token regardless of which tabs it shares.

Added in v3.4.2.

Parameters:

Parameter	Type	Description
$map	array	Associative array of endpoint path => tab slug.

Example:

Show code

add_filter( 'burst_endpoint_tab_map', function( $map ) {
    $map['data/my_custom_endpoint'] = 'statistics';
    return $map;
} );

---

burst_datatable_id_tab_map

Filters the map that resolves datatable IDs to dashboard tab slugs. The generic data/datatable and data/ecommerce/datatable endpoints don't carry enough information by themselves to identify a tab, so Burst inspects the id request parameter (or the trailing path segment for the granular data/datatable/{id} endpoints) and looks it up in this map for shared-viewer access checks.

Added in v3.4.2.

Parameters:

Parameter	Type	Description
$map	array	Associative array of datatable ID => tab slug.

Example:

Show code

add_filter( 'burst_datatable_id_tab_map', function( $map ) {
    $map['my_custom_table'] = 'statistics';
    return $map;
} );

---

burst_localize_script

Filters the entire data object passed to the Burst dashboard JavaScript. Use this to expose additional values or override existing ones.

Parameters:

Parameter	Type	Description
$data	array	Associative array of localised settings.

Example:

Show code

add_filter( 'burst_localize_script', function( $data ) {
    $data['my_custom_key'] = 'my_value';
    return $data;
} );

---

burst_date_ranges

Filters the list of date-range options available in the Burst dashboard date picker.

Parameters:

Parameter	Type	Description
$ranges	array	Indexed array of date-range identifier strings.

Default values: today, yesterday, last-7-days, last-30-days, last-90-days, last-month, last-year, week-to-date, month-to-date, year-to-date, all-time

Changed in v3.4.0: all-time is now included by default. It resolves the range start to the plugin activation timestamp (or the earliest Burst release date for older installs).

Example:

add_filter( 'burst_date_ranges', function( $ranges ) {
    return array_values( array_diff( $ranges, [ 'last-90-days' ] ) );
} );

---

burst_bounce_time

Filters the bounce-time threshold used by Burst when determining whether a visit counts as a bounce.

The value is expressed in milliseconds.

Parameters:

Parameter	Type	Description
$bounce_time_ms	int	Bounce threshold in milliseconds. Default: 5000.

Example:

Show code

add_filter( 'burst_bounce_time', function( $bounce_time_ms ) {
    $bounce_in_seconds = 10;
    return $bounce_in_seconds * 1000;
} );

---

burst_column_post_types

Filters the post types for which Burst exposes its admin pageviews column and related postmeta updates.

This is useful when you want Burst's pageview column and scheduled postmeta updates to include custom post types.

Parameters:

Parameter	Type	Description
$post_types	array	List of post type slugs included by Burst.

Example:

Show code

add_filter( 'burst_column_post_types', function( $post_types ) {
    $post_types[] = 'sportpark';
    return $post_types;
} );

---

burst_roles_excluded_from_tracking

Filters the list of WordPress user roles excluded from tracking.

Administrators are excluded by default; use this filter to exclude additional built-in or custom roles.

Parameters:

Parameter	Type	Description
$roles	array	Role slugs excluded from tracking.

Example:

add_filter( 'burst_roles_excluded_from_tracking', function( $roles ) {
    return array_merge( $roles, [ 'subscriber', 'editor' ] );
} );

---

burst_ip_blocklist

Filters the list of blocked IP addresses before Burst applies IP-based exclusion.

The integrations repo includes an example that loads IPs from a text file and merges them into Burst's existing blocklist.

Parameters:

Parameter	Type	Description
$ip_blocklist	array	Array of blocked IP addresses.

Example:

Show code

add_filter( 'burst_ip_blocklist', function( $ip_blocklist ) {
    $file = file( __DIR__ . '/burst-ip-blocklist.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES );

    if ( is_array( $file ) ) {
        foreach ( $file as $line ) {
            $ip_blocklist[] = trim( $line );
        }
    }

    return $ip_blocklist;
}, 10, 1 );

---

burst_datatable_data

Filters dashboard datatable rows just before they are returned to the UI.

This is useful for presentation-layer adjustments such as rewriting URLs to post titles, stripping query-string names from the parameters column, or removing rows that match a pattern.

Parameters:

Parameter	Type	Description
$data	array	Datatable rows after query execution.
$qd	object	Query context object used to produce the rows.

Example:

Show code

add_filter( 'burst_datatable_data', function( $data, $qd ) {
    foreach ( $data as $index => $item ) {
        $page = get_page_by_path( $item['page_url'] ?? '' );

        if ( $page ) {
            $data[ $index ]['page_url'] = $page->post_title;
        }
    }

    return $data;
}, 10, 2 );

caution

Lookups inside this filter can become expensive on large datasets. The integrations repo explicitly notes that URL-to-title mapping may be too slow for some sites.

---

burst_datatable_pre_data

Short-circuits the default datatable query. Return a non-null array from this filter and Burst will skip its own SQL query and use your rows directly. Returning null (the default) keeps Burst's built-in query behaviour.

Added in v3.4.0. Used internally to serve cached subscription datatables without running the generic query engine.

Parameters:

Parameter	Type	Description
$data	array|null	Pre-resolved rows, or null to fall through to the default query.
$args	array	The datatable request args, including id, date_start, date_end, metrics.

Example:

Show code

add_filter( 'burst_datatable_pre_data', function( $data, $args ) {
    if ( ( $args['id'] ?? '' ) !== 'my_custom_table' ) {
        return $data;
    }

    return my_plugin_build_rows( $args['date_start'], $args['date_end'] );
}, 10, 2 );

---

burst_datatable_metric_allow_list

Filters the allow-list of metric keys that may be returned for each datatable endpoint. Burst intersects the requested metrics against this list before running the query, so a metric must appear here to be returned for the named datatable. Use this filter to expose extra metrics for built-in datatables or to register the allow-list for a custom datatable endpoint.

The default list covers statistics_pages, statistics_parameters, statistics_referrers, and the dummy_data preview dataset. Pro registers additional entries for sources_countries, sources_campaigns, sources_referrers, sales_products, and subscription_products.

Added in v3.4.2.

Parameters:

Parameter	Type	Description
$allow_list	array	Associative array of datatable ID => list of allowed metric keys.

Example:

Show code

add_filter( 'burst_datatable_metric_allow_list', function( $allow_list ) {
    $allow_list['my_custom_table'] = [ 'page_url', 'pageviews', 'visitors' ];
    return $allow_list;
} );

---

burst_live_traffic_args

Filters the Query_Data object used to fetch the live traffic feed on the dashboard.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$qd	Query_Data	Query context used to load live-traffic rows.

Example:

Show code

add_filter( 'burst_live_traffic_args', function( $qd ) {
    // Exclude a specific path from the live feed.
    $qd->add_filter_exclusion( 'page_url', '/internal-status' );
    return $qd;
} );

---

burst_get_data_available_args

Filters the allow-list of request argument keys accepted by Query_Data for a given dashboard data type. Use this to register custom query parameters that your code reads from the REST payload.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$available_args	array	Current list of allowed argument keys.
$data_type	string	The data type being resolved (e.g. datatable, insights).

Example:

Show code

add_filter( 'burst_get_data_available_args', function( $available_args, $data_type ) {
    if ( $data_type === 'datatable' ) {
        $available_args[] = 'my_custom_arg';
    }
    return $available_args;
}, 10, 2 );

---

burst_sanitize_arg

Filters the sanitization of a single REST argument before it is passed to Query_Data. Return any non-null value to override Burst's default sanitization, or leave it null to let Burst handle it.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$sanitized_value	mixed	Existing sanitized value (null if not yet handled).
$arg	string	Argument key.
$value	mixed	Raw request value.

Example:

Show code

add_filter( 'burst_sanitize_arg', function( $sanitized_value, $arg, $value ) {
    if ( $arg === 'my_custom_arg' ) {
        return absint( is_array( $value ) ? ( $value[0] ?? 0 ) : $value );
    }
    return $sanitized_value;
}, 10, 3 );

---

burst_allowed_metrics

Filters the map of metric keys to internal SQL-friendly names. Use this to register new metric identifiers that Query_Data will accept in select, order_by, and datatable responses.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$metrics	array	Associative array of metric key ⇒ SQL column/label.

Example:

Show code

add_filter( 'burst_allowed_metrics', function( $metrics ) {
    $metrics['my_metric'] = 'My Metric';
    return $metrics;
} );

---

burst_allowed_metrics_labels

Filters the translated labels used as datatable column headers and for chart legends. Register a label here when you add a new metric via burst_allowed_metrics.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$labels	array	Associative array of metric key ⇒ label text.

Example:

Show code

add_filter( 'burst_allowed_metrics_labels', function( $labels ) {
    $labels['my_metric'] = __( 'My Metric', 'my-plugin' );
    return $labels;
} );

---

burst_minimum_archive_months

Filters the minimum age, in months, before Burst allows data to be archived.

By default, data older than 12 months can be archived.

Parameters:

Parameter	Type	Description
$months	int	Minimum archive age in months. Default: 12.

Example:

add_filter( 'burst_minimum_archive_months', function( $months ) {
    return 3;
} );

---

burst_verify_nonce

Filters the result of Burst's internal nonce verification.

caution

Returning true unconditionally from this filter bypasses CSRF protection. Only use this in controlled, trusted contexts such as automated test suites.

Changed in v3.3.0: Fixed a bug where wp_verify_nonce() was called twice. $valid is now the cached result of the single wp_verify_nonce() call made before the filter fires.

Parameters:

Parameter	Type	Description
$valid	int|false	Result of wp_verify_nonce() (1, 2, or false).
$nonce	string	The nonce string that was verified.
$action	string	The nonce action name.

Example:

Show code

add_filter( 'burst_verify_nonce', function( $valid, $nonce, $action ) {
    if ( defined( 'BURST_STAGING' ) && BURST_STAGING && $action === 'burst_nonce' ) {
        return 1;
    }
    return $valid;
}, 10, 3 );

---

burst_abilities_rate_limit_window

Filters the size, in seconds, of the per-user rolling window used by the Abilities API rate limiter. Each window holds its own counter, so a smaller window allows more frequent bursts and a larger one smooths usage over time.

Only active when the Abilities API integration is enabled (enable_abilities_api setting) and the host site has the WordPress Abilities API available. The limiter applies per logged-in user and per ability.

Added in v3.4.1.

Parameters:

Parameter	Type	Description
$window	int	Window length in seconds. Default: 60. Values below 1 are clamped to 1.
$ability	string	Ability slug being checked (e.g. live-visitors, data, sales-data).

Example:

Show code

// Use a 5-minute window for the data ability so heavier reads can be smoothed
// across a longer period.
add_filter( 'burst_abilities_rate_limit_window', function( $window, $ability ) {
    if ( $ability === 'data' ) {
        return 300;
    }
    return $window;
}, 10, 2 );

---

burst_abilities_rate_limit_max

Filters the maximum number of Abilities API calls a single user may make per ability within one rate-limit window. Requests above the cap return a burst_abilities_rate_limited WP_Error with HTTP 429.

Pair this with burst_abilities_rate_limit_window to size the budget appropriately. Only active when the Abilities API integration is enabled.

Added in v3.4.1.

Parameters:

Parameter	Type	Description
$max	int	Maximum requests per window per user per ability. Default: 30. Values below 1 are clamped to 1.
$ability	string	Ability slug being checked (e.g. live-visitors, data, sales-data).

Example:

Show code

// Allow trusted automation to make more frequent live-traffic polls,
// while keeping the default cap for everything else.
add_filter( 'burst_abilities_rate_limit_max', function( $max, $ability ) {
    if ( $ability === 'live-traffic' ) {
        return 120;
    }
    return $max;
}, 10, 2 );

---

burst_chat_availability

Filters the availability payload returned by the burst/v1/chat/status REST endpoint and exposed to the dashboard JavaScript as chat_availability. Use this to override the computed enabled flag or to attach additional diagnostic keys for the dashboard UI.

Only relevant when the Abilities API integration is enabled.

Added in v3.4.2.

Parameters:

Parameter	Type	Description
$payload	array	Availability flags: enabled, abilities_enabled, ai_client_loaded, has_configured_provider, disabled_reason.

Example:

Show code

add_filter( 'burst_chat_availability', function( $payload ) {
    $payload['custom_flag'] = true;
    return $payload;
} );

---

burst_chat_expose_exception

When true, the chat REST endpoint includes the underlying exception class and message in the error response returned to the client. Off by default so provider-side details are not leaked into the dashboard UI.

Only active when the Abilities API integration is enabled.

Added in v3.4.2.

Parameters:

Parameter	Type	Description
$expose	bool	true to include the exception in the error data. Default: false.

Example:

Show code

// Surface provider exceptions on staging only.
add_filter( 'burst_chat_expose_exception', function() {
    return defined( 'BURST_STAGING' ) && BURST_STAGING;
} );

---

burst_chat_debug

Filters whether the chat endpoint emits structured debug events through wp_trigger_error(). Defaults to the value of WP_DEBUG. Use this to force chat debug logging on or off independently of the global debug constant.

Only active when the Abilities API integration is enabled.

Added in v3.4.2.

Parameters:

Parameter	Type	Description
$enabled	bool	true to log chat debug events, false to suppress them.

Example:

// Force chat debug logging on regardless of WP_DEBUG.
add_filter( 'burst_chat_debug', '__return_true' );

---

burst_chat_rate_limit_window

Filters the size, in seconds, of the per-user rolling window used by the chat REST endpoint rate limiter. This is independent of the Abilities API rate limiter and only applies to the chat endpoint.

Pair with burst_chat_rate_limit_max to size the budget. Only active when the Abilities API integration is enabled.

Added in v3.4.2.

Parameters:

Parameter	Type	Description
$window	int	Window length in seconds. Default: 60. Values below 1 are clamped to 1.

Example:

add_filter( 'burst_chat_rate_limit_window', function( $window ) {
    return 300;
} );

---

burst_chat_rate_limit_max

Filters the maximum number of chat requests a single user may make within one rate-limit window. Requests above the cap return a burst_chat_rate_limited WP_Error with HTTP 429.

Only active when the Abilities API integration is enabled.

Added in v3.4.2.

Parameters:

Parameter	Type	Description
$max	int	Maximum chat requests per window per user. Default: 20. Values below 1 are clamped to 1.

Example:

add_filter( 'burst_chat_rate_limit_max', function( $max ) {
    return 60;
} );

---

burst_chat_prompt_max_length

Filters the maximum number of characters accepted in a single chat prompt and in each history-message text field. Text above this length is truncated before being sent to the AI provider.

Only active when the Abilities API integration is enabled.

Added in v3.4.2.

Parameters:

Parameter	Type	Description
$length	int	Maximum characters per prompt. Default: 8000. Values below 1 are clamped to 1.

Example:

add_filter( 'burst_chat_prompt_max_length', function( $length ) {
    return 4000;
} );

---

burst_chat_history_max_items

Filters the maximum number of history messages forwarded to the AI provider per chat request. Older messages beyond this cap are dropped before the prompt is built.

Only active when the Abilities API integration is enabled.

Added in v3.4.2.

Parameters:

Parameter	Type	Description
$items	int	Maximum history items. Default: 40. Values below 1 are clamped to 1.

Example:

add_filter( 'burst_chat_history_max_items', function( $items ) {
    return 20;
} );

---

burst_chat_parts_max_items

Filters the maximum number of message parts retained per history message. Excess parts are discarded before the history is normalized.

Only active when the Abilities API integration is enabled.

Added in v3.4.2.

Parameters:

Parameter	Type	Description
$items	int	Maximum parts per history message. Default: 50. Values below 1 are clamped to 1.

Example:

add_filter( 'burst_chat_parts_max_items', function( $items ) {
    return 10;
} );

---

burst_query_timeout_ms

Filters the per-query MySQL execution timeout (in milliseconds) used for foreground dashboard reads. Burst injects this value as a MAX_EXECUTION_TIME optimizer hint on every analytics SELECT, so an interrupted query returns null/[] instead of stalling a request. The default is also overridable via the burst_query_timeout_ms option — when that option is set to a positive integer, it replaces the built-in default before the filter runs.

Only the foreground (request-time) code path uses this filter. Background cron aggregations resolve their timeout via burst_query_timeout_ms_background.

Added in v3.4.2.1.

Parameters:

Parameter	Type	Description
$timeout_ms	int	Foreground timeout in milliseconds. Default: 30000 (30s). Values below 0 are clamped to 0 (disabled).
$qd	Query_Data	Query context being executed. May be null for the goal statistics path.

Example:

Show code

// Tighten the foreground timeout to 10 seconds on a fast database.
add_filter( 'burst_query_timeout_ms', function( $timeout_ms, $qd ) {
    return 10000;
}, 10, 2 );

---

burst_query_timeout_ms_background

Filters the per-query MySQL execution timeout (in milliseconds) used during cron-triggered analytics work (aggregation, backfill, recalculation). Background jobs default to a much longer ceiling than foreground requests because they are not user-facing.

Added in v3.4.2.1.

Parameters:

Parameter	Type	Description
$timeout_ms	int	Background timeout in milliseconds. Default: 900000 (15 minutes). Values below 0 are clamped to 0.
$qd	Query_Data	Query context being executed. May be null for the goal statistics path.

Example:

Show code

// Allow background backfill queries up to 30 minutes on a slow shared host.
add_filter( 'burst_query_timeout_ms_background', function( $timeout_ms, $qd ) {
    return 30 * 60 * 1000;
}, 10, 2 );

---

burst_query_results_cache_ttl

Filters the TTL (in seconds) of the per-query result cache used by Statistics::get_row() and Statistics::get_results(). Successful query results are stored under a SHA-256 cache key derived from the prepared SQL, so repeated dashboard reads of the same query within the TTL skip the database round trip entirely.

The default is 30 seconds, raised to 300 seconds when the requested date range exceeds 30 days (an "expensive aggregation window"). Setting the burst_query_results_cache_ttl option to a non-negative integer overrides the default before the filter runs. Returning 0 disables result caching for the query.

Added in v3.4.2.1.

Parameters:

Parameter	Type	Description
$ttl	int	Cache TTL in seconds. Default: 30, or 300 for ranges longer than 30 days. Values below 0 are clamped to 0.
$qd	Query_Data	Query context being executed.

Example:

Show code

// Cache long-range datatable reads for 10 minutes on a high-traffic site.
add_filter( 'burst_query_results_cache_ttl', function( $ttl, $qd ) {
    if ( $qd->date_end - $qd->date_start > 90 * DAY_IN_SECONDS ) {
        return 600;
    }
    return $ttl;
}, 10, 2 );

---

burst_query_timeout_cooldown_ttl

Filters the cooldown window (in seconds) Burst applies after a query times out. While the cooldown is active, identical follow-up reads of the same cache key short-circuit to null/[] instead of re-running the failing query, which prevents a slow query from being hammered into the database on every dashboard refresh.

The default tracks the configured query timeout (rounded up to whole seconds, with a 30s floor). Returning 0 disables the cooldown and allows immediate retries.

Added in v3.4.2.1.

Parameters:

Parameter	Type	Description
$ttl	int	Cooldown TTL in seconds. Default: derived from the query timeout, with a 30s floor.
$qd	Query_Data	Query context being executed.
$timeout_ms	int	The resolved query timeout in milliseconds that produced the timeout being cooled down.

Example:

Show code

// Use a short cooldown so flaky timeouts recover quickly.
add_filter( 'burst_query_timeout_cooldown_ttl', function( $ttl, $qd, $timeout_ms ) {
    return 15;
}, 10, 3 );

---

burst_query_single_flight_enabled

Filters whether Burst applies the single-flight pattern to identical concurrent dashboard queries. When enabled, only one request per cache key actually executes the query (the leader). Followers briefly poll for the leader's result and either return the cached value or fall through to an empty payload, preventing a thundering herd when many tabs/users hit the same expensive aggregation at once.

The default is true only when WordPress is using a shared external object cache (wp_using_ext_object_cache()), since the wp_cache layer is the coordination primitive. On the in-memory fallback cache the leader/follower coordination cannot work, so single-flight stays off.

Added in v3.4.2.1.

Parameters:

Parameter	Type	Description
$enabled	bool	true if a shared external object cache is detected. false on installs without one.
$qd	Query_Data	Query context being executed.

Example:

Show code

// Force single-flight off for a specific custom query that should always
// re-execute (e.g. a low-cost real-time counter).
add_filter( 'burst_query_single_flight_enabled', function( $enabled, $qd ) {
    if ( $qd->get_id() === 'my_realtime_widget' ) {
        return false;
    }
    return $enabled;
}, 10, 2 );

---

burst_query_single_flight_wait_ms

Filters the maximum time (in milliseconds) a follower request waits for a leader to populate the cache before giving up. While waiting, Burst polls the cache with an exponential backoff (50ms → 200ms). After the budget is spent without a result, the follower returns null/[] so the request does not block indefinitely.

Pair this with burst_query_single_flight_enabled. Only active when single-flight is on.

Added in v3.4.2.1.

Parameters:

Parameter	Type	Description
$wait_ms	int	Maximum follower wait time in milliseconds. Default: 1200. Values below 0 are clamped to 0.
$qd	Query_Data	Query context being executed.

Example:

Show code

// Give followers up to 3 seconds before falling back to an empty result.
add_filter( 'burst_query_single_flight_wait_ms', function( $wait_ms, $qd ) {
    return 3000;
}, 10, 2 );

---

burst_query_single_flight_lock_ttl

Filters the leader-lock TTL (in seconds) used by the single-flight coordinator. The lock is added via wp_cache_add() and protects the cache key while the leader query is in flight; if the leader crashes or the request is killed, the TTL guarantees the lock is released within a bounded window so the next request can become the new leader.

The default scales with the configured query timeout (ceil($timeout_ms / 1000) + 2, with a 5s floor) so the lock cannot expire before the underlying query has had a chance to complete.

Only active when single-flight is on.

Added in v3.4.2.1.

Parameters:

Parameter	Type	Description
$lock_ttl	int	Lock TTL in seconds. Default: derived from the query timeout, with a 5s floor.
$qd	Query_Data	Query context being executed.
$timeout_ms	int	The resolved query timeout in milliseconds, used to derive the default.

Example:

Show code

// Hold the leader lock for at least one minute regardless of timeout.
add_filter( 'burst_query_single_flight_lock_ttl', function( $lock_ttl, $qd, $timeout_ms ) {
    return max( 60, $lock_ttl );
}, 10, 3 );

---

burst_object_cache_recommendation_threshold_seconds

Filters the slow-query threshold (in seconds) that triggers Burst's "enable a persistent object cache" admin task. The check inspects the recorded max_execution_time across all entries in burst_query_stats and surfaces the recommendation if the worst case meets or exceeds this threshold. The recommendation is also automatically suppressed on installs that already have a shared external object cache active.

Added in v3.4.2.1.

Parameters:

Parameter	Type	Description
$threshold	float	Slow-query threshold in seconds. Default: 10.0. Values below 0.1 are clamped to 0.1.

Example:

Show code

// Only recommend object cache when queries exceed 30 seconds.
add_filter( 'burst_object_cache_recommendation_threshold_seconds', function( $threshold ) {
    return 30.0;
} );

---

burst_subscription_cache_max_rows

Pro - BusinessAvailable in the Business tier

Applies only to the Burst Pro subscription providers (WooCommerce Subscriptions, EDD Recurring, Subscriben). See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Filters the cumulative row-count ceiling for the per-request in-memory subscription row cache. Each provider keeps the full subscription row set under an args-hash key so multiple aggregation methods sharing the same shape only hit the database once. When adding the next entry would push the cumulative row count over this ceiling, the entry is skipped (correctness is unaffected — callers fall back to keyset re-fetches), keeping cron memory under control on cheap PHP hosts.

The default of 25000 rows is sized for a 128 MB PHP memory_limit. Hosts with memory_limit ≥ 512 MB can raise it; the trade-off is roughly an extra ~3 KB resident per cached row against the cost of additional re-fetches.

Added in v3.4.2.1.

Parameters:

Parameter	Type	Description
$ceiling	int	Cumulative cached row count ceiling. Default: 25000.
$plugin_source	string	Provider source key (e.g. subscriben, woocommerce_subscriptions, edd_recurring).

Example:

Show code

// Allow more cached rows on a high-memory WooCommerce host.
add_filter( 'burst_subscription_cache_max_rows', function( $ceiling, $plugin_source ) {
    if ( $plugin_source === 'woocommerce_subscriptions' ) {
        return 75000;
    }
    return $ceiling;
}, 10, 2 );

---

burst_subscription_query_timeout_ms

Pro - BusinessAvailable in the Business tier

Applies only to queries built by the Burst Pro subscription Query builder. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Filters the per-query MySQL execution timeout (in milliseconds) used by the Pro subscription Query builder for foreground dashboard reads (Subscriptions tab, charts, datatables). Mirrors burst_query_timeout_ms but is scoped to subscription-specific queries so site owners can tune them independently of the main analytics queries.

The default is also overridable via the burst_query_timeout_ms option — when the option is set to a positive integer, it replaces the built-in default before the filter runs.

Added in v3.4.2.1.

Parameters:

Parameter	Type	Description
$timeout_ms	int	Foreground subscription-query timeout in milliseconds. Default: 30000 (30s). Values below 0 are clamped to 0.

Example:

Show code

// Allow the Subscriptions dashboard up to 60 seconds on a slow database.
add_filter( 'burst_subscription_query_timeout_ms', function( $timeout_ms ) {
    return 60000;
} );

---

burst_subscription_query_timeout_ms_background

Pro - BusinessAvailable in the Business tier

Applies only to queries built by the Burst Pro subscription Query builder. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Filters the per-query MySQL execution timeout (in milliseconds) used by the Pro subscription Query builder during cron-triggered work (subscription daily aggregator, backfill). Mirrors burst_query_timeout_ms_background but is scoped to subscription-specific queries.

Added in v3.4.2.1.

Parameters:

Parameter	Type	Description
$timeout_ms	int	Background subscription-query timeout in milliseconds. Default: 900000 (15 minutes). Values below 0 are clamped to 0.

Example:

Show code

// Cap subscription backfill queries at 5 minutes per query.
add_filter( 'burst_subscription_query_timeout_ms_background', function( $timeout_ms ) {
    return 5 * 60 * 1000;
} );

---

burst_checkout_page_id

Pro - BusinessAvailable in the Business tier

This filter is only relevant when the Burst Pro ecommerce tracking feature is active. See WooCommerce Funnel Analytics.

Everything in the Business tier is also available in the Agency tier.

Filters the WordPress page ID treated as the checkout page. The resolved value is cached for 24 hours.

Parameters:

Parameter	Type	Description
$page_id	int	The checkout page ID. Defaults to -1 (not set).

Example:

Show code

add_filter( 'burst_checkout_page_id', function( $page_id ) {
    if ( function_exists( 'wc_get_page_id' ) ) {
        return (int) wc_get_page_id( 'checkout' );
    }
    return $page_id;
} );

---

burst_products_page_id

Pro - BusinessAvailable in the Business tier

This filter is only relevant when the Burst Pro ecommerce tracking feature is active. See WooCommerce Funnel Analytics.

Everything in the Business tier is also available in the Agency tier.

Filters the WordPress page ID treated as the main products/shop page. The resolved value is cached for 24 hours.

Parameters:

Parameter	Type	Description
$page_id	int	The products page ID. Defaults to -1 (not set).

Example:

Show code

add_filter( 'burst_products_page_id', function( $page_id ) {
    if ( function_exists( 'wc_get_page_id' ) ) {
        return (int) wc_get_page_id( 'shop' );
    }
    return $page_id;
} );

---

burst_base_currency

Pro - BusinessAvailable in the Business tier

This filter is only relevant when the Burst Pro ecommerce tracking feature is active. Learn more about revenue and sales tracking.

Everything in the Business tier is also available in the Agency tier.

Filters the ISO 4217 currency code used for revenue reporting. The resolved value is cached for 24 hours.

Parameters:

Parameter	Type	Description
$currency	string	ISO 4217 currency code. Defaults to USD.

Example:

Show code

add_filter( 'burst_base_currency', function( $currency ) {
    if ( function_exists( 'get_woocommerce_currency' ) ) {
        return get_woocommerce_currency();
    }
    return $currency;
} );

---

burst_woocommerce_order_data

Pro - BusinessAvailable in the Business tier

Only applied when the Burst Pro ecommerce integration captures a WooCommerce order. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Filters the normalized order payload before it is dispatched via burst_order_created / burst_woocommerce_order_created. Use this to attach custom fields (e.g. currency conversion rates) derived from the underlying WC_Order.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$data	array	Normalized order data (see burst_order_created).
$order	WC_Order	The raw WooCommerce order object.

Example:

Show code

add_filter( 'burst_woocommerce_order_data', function( $data, $order ) {
    $rate = (float) $order->get_meta( '_wcpay_multi_currency_stripe_exchange_rate', true );
    if ( $rate > 0 ) {
        $data['conversion_rate'] = $rate;
    }
    return $data;
}, 10, 2 );

---

burst_edd_order_data

Pro - BusinessAvailable in the Business tier

Only applied when the Burst Pro ecommerce integration captures an Easy Digital Downloads order. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Filters the normalized order payload before it is dispatched via burst_order_created / burst_edd_order_created. Use it to enrich the payload with EDD-specific data such as multi-currency rates.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$data	array	Normalized order data.
$order_id	int	EDD payment ID.
$payment	EDD_Payment	The raw EDD payment object.

Example:

Show code

add_filter( 'burst_edd_order_data', function( $data, $order_id, $payment ) {
    $order = edd_get_order( $order_id );
    if ( $order && ! empty( $order->rate ) ) {
        $data['conversion_rate'] = (float) $order->rate;
    }
    return $data;
}, 10, 3 );

---

burst_subscription_integrations_enabled

Pro - BusinessAvailable in the Business tier

Subscriptions analytics require a Burst Pro Business subscription together with an active subscription integration plugin. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Determines whether Burst should expose the Subscriptions dashboard, run the daily aggregator, and register subscription menu items. Burst's WooCommerce Subscriptions, EDD Recurring, and Subscriben integrations return true when they load. Third-party integrations can hook in to opt in.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$enabled	bool	true if any subscription integration is active.

Example:

add_filter( 'burst_subscription_integrations_enabled', '__return_true' );

---

burst_subscription_aggregator_integrations

Pro - BusinessAvailable in the Business tier

Used by subscription daily aggregators that feed the Subscriptions dashboard. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Filters the list of Subscription_Aggregator_Base instances registered with the central orchestrator. Each entry is responsible for per-day aggregation and backfill of one subscription integration.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$integrations	array	List of Subscription_Aggregator_Base instances.

Example:

Show code

add_filter( 'burst_subscription_aggregator_integrations', function( $integrations ) {
    $integrations[] = new My_Plugin_Subscription_Aggregator();
    return $integrations;
} );

---

burst_subscription_aggregated_data

Pro - BusinessAvailable in the Business tier

Used internally by the Subscriptions dashboard to short-circuit on-demand metric calculations. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Short-circuits subscription summary metrics for a plugin source and date range. Return an array of pre-aggregated metrics to skip on-demand SQL; return null to fall through to the provider's calculation.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$data	array|null	Default value (null = no cached data).
$plugin_source	string	Plugin slug (e.g. woocommerce_subscriptions).
$args	array	{ date_start: int, date_end: int }.

Example:

Show code

add_filter( 'burst_subscription_aggregated_data', function( $data, $plugin_source, $args ) {
    if ( $plugin_source !== 'my_plugin' ) {
        return $data;
    }
    return my_plugin_get_cached_summary( $args['date_start'], $args['date_end'] );
}, 10, 3 );

---

burst_subscription_aggregated_product_data

Pro - BusinessAvailable in the Business tier

Used internally by the Subscriptions product datatable. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Short-circuits per-product subscription metrics for a plugin source and date range. Return cached rows to skip the provider's on-demand query.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$data	array|null	Default value (null = no cached data).
$plugin_source	string	Plugin slug.
$args	array	{ date_start: int, date_end: int, metrics: string[] }.

Example:

add_filter( 'burst_subscription_aggregated_product_data', function( $data, $plugin_source, $args ) {
    return my_plugin_product_cache( $plugin_source, $args );
}, 10, 3 );

---

burst_subscription_aggregated_revenue_chart_data

Pro - BusinessAvailable in the Business tier

Used internally by the Subscriptions revenue chart. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Short-circuits new-vs-renewal chart series for a plugin source and date range. Return the bucketed series directly to skip the on-demand builder.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$data	array|null	Default value (null = no cached data).
$plugin_source	string	Plugin slug.
$args	array	{ date_start: int, date_end: int, group_by?: string, chart_mode?: string }.

Example:

add_filter( 'burst_subscription_aggregated_revenue_chart_data', function( $data, $plugin_source, $args ) {
    return my_plugin_revenue_chart_cache( $plugin_source, $args );
}, 10, 3 );

---

burst_subscription_aggregated_retention_data

Pro - BusinessAvailable in the Business tier

Used internally by the Subscriptions retention cohort chart. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Short-circuits monthly cohort retention metrics for a plugin source and date range. Returning null (the default) forces the provider to compute cohorts on demand — the cache is only authoritative for confirmed-empty ranges.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$data	array|null	Default value (null = no cached data).
$plugin_source	string	Plugin slug.
$args	array	{ date_start: int, date_end: int, product_id?: int }.

Example:

Show code

add_filter( 'burst_subscription_aggregated_retention_data', function( $data, $plugin_source, $args ) {
    if ( $plugin_source === 'my_plugin' ) {
        return my_plugin_retention_cache( $args );
    }
    return $data;
}, 10, 3 );

---

burst_subscription_aggregated_backfill_progress

Pro - BusinessAvailable in the Business tier

Used by the Subscriptions dashboard to display backfill progress. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Filters the merged backfill progress payload returned via the subscriptions REST endpoint.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$progress	array	{ is_processing: bool, progress: int, processed: int, total: int, integrations: array }.

Example:

Show code

add_filter( 'burst_subscription_aggregated_backfill_progress', function( $progress ) {
    $progress['custom_flag'] = true;
    return $progress;
} );

---

burst_ecommerce_subscriptions_data

Pro - BusinessAvailable in the Business tier

Powers the Subscriptions summary blocks on the Subscriptions dashboard. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Resolves the summary payload (MRR, active/canceled counts, churn, lifetime value) for a given date range. Each registered subscription provider hooks into this filter to contribute its data.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$data	array	Accumulated summary payload.
$args	array	{ date_start: int, date_end: int }.

Example:

add_filter( 'burst_ecommerce_subscriptions_data', function( $data, $args ) {
    return my_plugin_merge_subscription_summary( $data, $args );
}, 10, 2 );

---

burst_ecommerce_subscriptions_product_data

Pro - BusinessAvailable in the Business tier

Powers the Subscriptions product datatable. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Returns per-product subscription rows for the datatable. Burst aggregates rows from every subscription provider.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$args	array	{ date_start: int, date_end: int, metrics: string[] }.

Example:

add_filter( 'burst_ecommerce_subscriptions_product_data', function( $args ) {
    return my_plugin_subscription_product_rows( $args );
} );

---

burst_ecommerce_subscriptions_revenue_chart_data

Pro - BusinessAvailable in the Business tier

Powers the Subscriptions revenue chart. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Resolves the new-vs-renewal bucketed chart series (revenue or sales mode). Defaults to an empty series if no provider handles the request.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$data	array	Current chart payload { interval, spans_multiple_years, rows, mode, currency }.
$args	array	{ date_start, date_end, group_by, chart_mode }.

Example:

add_filter( 'burst_ecommerce_subscriptions_revenue_chart_data', function( $data, $args ) {
    return my_plugin_build_revenue_chart( $data, $args );
}, 10, 2 );

---

burst_ecommerce_subscriptions_distribution_data

Pro - BusinessAvailable in the Business tier

Powers the Subscriptions distribution donut chart (gateways, currencies, countries). See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Returns distribution rows for the selected view. Each provider merges rows into the response by id, summing counts.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$data	array	Rows contributed by earlier providers [ { id, label, count } ].
$args	array	{ date_start, date_end, distribution_view: 'gateways'|'currencies'|'countries' }.

Example:

Show code

add_filter( 'burst_ecommerce_subscriptions_distribution_data', function( $data, $args ) {
    $data[] = [
        'id'    => 'my_gateway',
        'label' => 'My Gateway',
        'count' => 42,
    ];
    return $data;
}, 10, 2 );

---

burst_ecommerce_subscriptions_retention_data

Pro - BusinessAvailable in the Business tier

Powers the Subscriptions retention cohort chart. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Returns monthly signup cohorts and cross-month renewal counts for the retention chart.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$data	array	{ cohorts: array, products: array } accumulated by providers.
$args	array	{ date_start, date_end, product_id }.

Example:

add_filter( 'burst_ecommerce_subscriptions_retention_data', function( $data, $args ) {
    return my_plugin_merge_retention_data( $data, $args );
}, 10, 2 );

---

burst_ecommerce_subscriptions_first_subscription_date

Pro - BusinessAvailable in the Business tier

Used to set the earliest selectable date on the Subscriptions date picker. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Resolves the earliest subscription creation timestamp across all registered integrations. Return null if none have data yet.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$first_subscription_date	int|null	Unix timestamp of earliest subscription, or null.

Example:

Show code

add_filter( 'burst_ecommerce_subscriptions_first_subscription_date', function( $first ) {
    $custom = my_plugin_earliest_subscription();
    return $custom ? max( (int) $custom, (int) $first ) : $first;
} );

---

burst_woocommerce_subscriptions_count

Pro - BusinessAvailable in the Business tier

Used by the WooCommerce Subscriptions daily aggregator. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Returns active / trialling / canceled subscription counts for a day. Mirrored by burst_edd_recurring_subscriptions_count and burst_subscriben_subscriptions_count for the other integrations.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$counts	array	{ active_count: int, trialling_count: int, canceled_count: int }.
$date_start	int	Day start timestamp (UTC).
$date_end	int	Day end timestamp (UTC).

Example:

add_filter( 'burst_woocommerce_subscriptions_count', function( $counts, $date_start, $date_end ) {
    return my_plugin_subscription_counts( $counts, $date_start, $date_end );
}, 20, 3 );

---

burst_woocommerce_subscriptions_monthly_recurring_revenue

Pro - BusinessAvailable in the Business tier

Used by the WooCommerce Subscriptions daily aggregator. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Returns the MRR for a given day. Parallel filters exist for the other integrations: burst_edd_recurring_monthly_recurring_revenue, burst_subscriben_monthly_recurring_revenue.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$mrr	array	{ mrr: float }.
$date_start	int	Day start timestamp (UTC).
$date_end	int	Day end timestamp (UTC).

Example:

add_filter( 'burst_woocommerce_subscriptions_monthly_recurring_revenue', function( $mrr, $start, $end ) {
    return $mrr;
}, 10, 3 );

---

burst_woocommerce_subscriptions_daily_chart_breakdown

Pro - BusinessAvailable in the Business tier

Used by the WooCommerce Subscriptions daily aggregator. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Returns the per-day new-vs-renewal revenue/sales breakdown. Parallel filters: burst_edd_recurring_daily_chart_breakdown, burst_subscriben_daily_chart_breakdown.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$chart	array	{ new_revenue: float, renewal_revenue: float, new_sales: int, renewal_sales: int }.
$date_start	int	Day start timestamp (UTC).
$date_end	int	Day end timestamp (UTC).

Example:

add_filter( 'burst_woocommerce_subscriptions_daily_chart_breakdown', function( $chart, $start, $end ) {
    return $chart;
}, 10, 3 );

---

burst_woocommerce_subscriptions_revenue_churn

Pro - BusinessAvailable in the Business tier

Used by the WooCommerce Subscriptions daily aggregator. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Returns the churned MRR and churn percentage for a day. Parallel filters: burst_edd_recurring_revenue_churn, burst_subscriben_revenue_churn.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$churn	array	{ churned_percentage: float, churned_mrr: float, count: int }.
$date_start	int	Day start timestamp (UTC).
$date_end	int	Day end timestamp (UTC).

Example:

add_filter( 'burst_woocommerce_subscriptions_revenue_churn', function( $churn, $start, $end ) {
    return $churn;
}, 10, 3 );

---

burst_woocommerce_subscriptions_average_lifetime_value

Pro - BusinessAvailable in the Business tier

Used by the WooCommerce Subscriptions daily aggregator. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Returns the average lifetime value of active subscriptions for a day. Parallel filters: burst_edd_recurring_average_lifetime_value, burst_subscriben_average_lifetime_value.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$ltv	array	{ value: float, active_subscription_count: int, total_revenue: float }.
$date_start	int	Day start timestamp (UTC).
$date_end	int	Day end timestamp (UTC).

Example:

add_filter( 'burst_woocommerce_subscriptions_average_lifetime_value', function( $ltv, $start, $end ) {
    return $ltv;
}, 10, 3 );

---

burst_woocommerce_subscriptions_product_metrics

Pro - BusinessAvailable in the Business tier

Used by the WooCommerce Subscriptions daily aggregator to feed the product datatable. See Revenue & sales tracking.

Everything in the Business tier is also available in the Agency tier.

Returns per-product subscription metrics for a day. Parallel filters: burst_edd_recurring_product_metrics, burst_subscriben_product_metrics.

Added in v3.4.0.

Parameters:

Parameter	Type	Description
$date_start	int	Day start timestamp (UTC).
$date_end	int	Day end timestamp (UTC).
$products	array	Existing product rows (usually empty; append to contribute).

Example:

add_filter( 'burst_woocommerce_subscriptions_product_metrics', function( $start, $end, $products ) {
    return array_merge( $products, my_plugin_product_rows( $start, $end ) );
}, 10, 3 );