Docs › Developer API

Developer API Reference

All WordPress actions and filters provided by StockOracle AI for custom integrations and extensions.

Overview

StockOracle AI is built with extensibility in mind. The Pro addon itself integrates entirely via these hooks — proving they're production-tested. All hooks follow the stockoracle_ prefix convention.

action do_action() — fire custom code at a point

filter apply_filters() — modify a value

Actions

stockoracle_after_dashboard_widgets action

Fires after the last dashboard widget/card section is rendered. Use this to append custom widgets to the dashboard.

Parameters

$data array — Full dashboard data array (health score, stats, charts, alerts, dead stock)

add_action( 'stockoracle_after_dashboard_widgets', function( $data ) {
    echo '<div class="soa-widget">';
    echo '<h3>My Custom Widget</h3>';
    // Use $data['health_score'], $data['stats'], etc.
    echo '</div>';
} );

stockoracle_after_forecast_data action

Fires after forecast data is generated for a product. Used by the Pro seasonality module to apply seasonal adjustments.

Parameters

$product_id int — WooCommerce product ID

$forecast array — Forecast result: ['sma', 'wma', 'confidence', 'recommended_order_qty']

add_action( 'stockoracle_after_forecast_data', function( $product_id, $forecast ) {
    // Log forecasts to a custom table, push to external system, etc.
    error_log( "Product $product_id forecast: " . print_r( $forecast, true ) );
}, 10, 2 );

stockoracle_after_settings_sections action

Fires at the end of the Settings page (inside the form). Use this to add additional settings sections to existing tabs.

Parameters

$current_tab string — Active tab slug: 'general', 'alerts', 'advanced', 'gopro'

add_action( 'stockoracle_after_settings_sections', function( $current_tab ) {
    if ( 'general' !== $current_tab ) return;
    echo '<h2>My Integration Settings</h2>';
    // Render your settings fields here
} );

stockoracle_daily_cron_complete action

Fires at the end of the daily cron job, after sales data has been collected and caches refreshed.

Parameters

$results array — Summary: ['products_processed', 'records_inserted', 'date']

add_action( 'stockoracle_daily_cron_complete', function( $results ) {
    // Notify external BI system, sync to spreadsheet, etc.
    wp_remote_post( 'https://my-bi-tool.com/webhook', [
        'body' => json_encode( $results )
    ]);
} );

Filters

stockoracle_health_score_factors filter

Modify or extend the five health score factors. Each factor contributes up to $max_points. Adding factors beyond the default 5 dilutes existing scores proportionally.

Parameters

$factors array — Array of factor arrays: [['name'=>string, 'score'=>float, 'max'=>int], …]

add_filter( 'stockoracle_health_score_factors', function( $factors ) {
    // Add a custom "Supplier Lead Time Risk" factor (max 20 pts)
    $risk_score = my_calculate_lead_time_risk(); // returns 0-20
    $factors[] = [
        'name'  => 'Supplier Lead Time Risk',
        'score' => $risk_score,
        'max'   => 20,
    ];
    return $factors;
} );

stockoracle_admin_tabs filter

Add or remove tabs from the Settings page navigation. The Pro addon uses this to inject Pro-specific settings tabs.

Parameters

$tabs array — Associative array of tab_slug => tab_label

add_filter( 'stockoracle_admin_tabs', function( $tabs ) {
    // Insert before 'gopro' tab
    $new = [];
    foreach ( $tabs as $key => $label ) {
        if ( 'gopro' === $key ) {
            $new['my_tab'] = 'My Integration';
        }
        $new[ $key ] = $label;
    }
    return $new;
} );

stockoracle_reorder_quantity filter

Override the suggested reorder quantity for a product. Useful for adding minimum order quantity (MOQ) constraints from your supplier.

Parameters

$qty float — Calculated suggested reorder quantity

$product_id int — WooCommerce product ID

$velocity float — Current daily sales velocity

add_filter( 'stockoracle_reorder_quantity', function( $qty, $product_id, $velocity ) {
    // Enforce minimum order of 50 units for product ID 123
    if ( 123 === $product_id && $qty < 50 ) {
        return 50;
    }
    // Round to nearest case pack of 12
    return ceil( $qty / 12 ) * 12;
}, 10, 3 );

stockoracle_dead_stock_threshold filter

Override the dead stock threshold (in days) for a specific product or category. Useful for products with known long sales cycles.

Parameters

$threshold int — Days threshold from settings (default 90)

$product_id int — WooCommerce product ID

add_filter( 'stockoracle_dead_stock_threshold', function( $threshold, $product_id ) {
    // Luxury items category — extend dead stock threshold to 365 days
    if ( has_term( 'luxury', 'product_cat', $product_id ) ) {
        return 365;
    }
    return $threshold;
}, 10, 2 );

stockoracle_velocity_calculation filter

Modify the calculated daily velocity for a product before it is stored or used in calculations.

Parameters

$velocity float — Calculated daily velocity (units/day)

$product_id int — WooCommerce product ID

$period_days int — Analysis period in days

add_filter( 'stockoracle_velocity_calculation', function( $velocity, $product_id, $period_days ) {
    // Apply a 1.2x growth factor to all products in the 'trending' tag
    if ( has_term( 'trending', 'product_tag', $product_id ) ) {
        return $velocity * 1.2;
    }
    return $velocity;
}, 10, 3 );

stockoracle_export_columns filter

Add or remove columns from the CSV export. Return a modified array of column definitions.

Parameters

$columns array — Array of column definitions: [['key'=>string, 'label'=>string, 'callback'=>callable], …]

add_filter( 'stockoracle_export_columns', function( $columns ) {
    // Add a "Supplier Name" column
    $columns[] = [
        'key'      => 'supplier_name',
        'label'    => 'Supplier',
        'callback' => function( $product_id ) {
            return get_post_meta( $product_id, '_supplier_name', true ) ?: 'N/A';
        },
    ];
    return $columns;
} );

Complete Examples

Adding a Custom Health Score Factor

Add this to your theme's functions.php or a custom plugin to extend the health score with supplier reliability data:

/**
 * Add "Supplier Reliability" factor to StockOracle health score.
 * Scores 0-20 based on percentage of POs delivered on time (last 90 days).
 */
add_filter( 'stockoracle_health_score_factors', function( $factors ) {
    global $wpdb;

    $on_time = (int) $wpdb->get_var(
        "SELECT COUNT(*) FROM {$wpdb->prefix}my_purchase_orders
         WHERE status = 'received' AND delivered_date <= expected_date
         AND created_at > DATE_SUB(NOW(), INTERVAL 90 DAY)"
    );
    $total = (int) $wpdb->get_var(
        "SELECT COUNT(*) FROM {$wpdb->prefix}my_purchase_orders
         WHERE status IN ('received','late')
         AND created_at > DATE_SUB(NOW(), INTERVAL 90 DAY)"
    );

    $reliability = ( $total > 0 ) ? ( $on_time / $total ) : 1.0;
    $score       = round( $reliability * 20 );

    $factors[] = [
        'name'  => 'Supplier Reliability',
        'score' => $score,
        'max'   => 20,
    ];

    return $factors;
} );

Adding a Custom Settings Tab

Add a new "Integrations" tab to the StockOracle Settings page:

// Step 1: Register the tab
add_filter( 'stockoracle_admin_tabs', function( $tabs ) {
    $tabs['integrations'] = 'Integrations';
    return $tabs;
} );

// Step 2: Render the tab content
add_action( 'stockoracle_after_settings_sections', function( $current_tab ) {
    if ( 'integrations' !== $current_tab ) return;
    ?>
    <h2>Third-Party Integrations</h2>
    <table class="form-table">
        <tr>
            <th>Slack Webhook URL</th>
            <td>
                <input type="url" name="my_slack_webhook"
                       value="<?php echo esc_attr( get_option('my_slack_webhook') ); ?>"
                       class="regular-text" />
                <p class="description">Receive reorder alerts in Slack.</p>
            </td>
        </tr>
    </table>
    <?php
} );

// Step 3: Save the custom field
add_action( 'admin_init', function() {
    register_setting( 'stockoracle_settings', 'my_slack_webhook', 'esc_url_raw' );
} );

Adding a Custom CSV Export Column

Add a "Bin Location" column to the inventory CSV export:

add_filter( 'stockoracle_export_columns', function( $columns ) {
    $columns[] = [
        'key'      => 'bin_location',
        'label'    => 'Bin Location',
        'callback' => function( $product_id ) {
            $bin = get_post_meta( $product_id, '_warehouse_bin', true );
            return $bin ? $bin : 'Unassigned';
        },
    ];
    return $columns;
} );

Need a Hook That Doesn't Exist?

Open a feature request at themefreex.com/support with your use case. We add developer-requested hooks in minor releases.

← Use Cases FAQ →