Deeproots Help Documentation Help Center

Hooks & Extending

The filters the plugin provides, what each one does, and best practice when extending.

Updated October 1, 2026

The filters

The plugin exposes five filters, all relating to the cart and checkout. That is deliberate: the sync is not a place where site-specific overrides are wanted, and the cart is.

Filter Controls Default
dispense_cart_enabled Whether the cart runtime loads at all true unless the mode is sync_only
dispense_cart_session_lifetime Cart session and cookie lifetime, in seconds 30 * DAY_IN_SECONDS
dispense_checkout_use_minimal_shell Whether checkout drops theme chrome The dispense_checkout_minimal_shell option, default on
dispense_purchase_complete_query_param The completion parameter name dispense_order_complete
dispense_purchase_transaction_query_param The transaction ID parameter name transaction_id

Put your code in a small plugin or your child theme’s functions.php — not in the plugin, which updates.

dispense_cart_enabled

Forces the cart runtime on or off, independently of the Plugin Mode setting.

apply_filters('dispense_cart_enabled', bool $enabled): bool

When it runs: very early, as Dispense_Cart_API is constructed. Returning false skips the PHP session, the cart JavaScript and CSS, all AJAX endpoints, the auto-created checkout page and the checkout render. The four cart shortcodes are registered as no-ops so leftover shortcodes degrade silently.

Turn the cart off everywhere

add_filter('dispense_cart_enabled', '__return_false');

Turn it off on staging only

Useful when staging shares a database with production and you do not want anyone creating a real cart from a test site:

CSS
add_filter('dispense_cart_enabled', function ($enabled) {
    return wp_get_environment_type() === 'production' ? $enabled : false;
});

Turn it off for a maintenance window

CSS
add_filter('dispense_cart_enabled', function ($enabled) {
    // Disable the cart outside trading hours.
    $hour = (int) current_time('G');
    return ($hour >= 9 && $hour < 22) ? $enabled : false;
});

dispense_cart_session_lifetime

Sets how long a visitor’s cart survives, in seconds.

apply_filters('dispense_cart_session_lifetime', int $seconds): int

Applied to session.gc_maxlifetime, the session cookie, and the dispense_cart_id / dispense_venue_id cookies. A value of zero or less falls back to the 30-day default.

A shorter cart

add_filter('dispense_cart_session_lifetime', function () {
    return 7 * DAY_IN_SECONDS;
});

A single-session cart

add_filter('dispense_cart_session_lifetime', function () {
    return HOUR_IN_SECONDS;
});

Considerations

  • Longer is friendlier — a customer returning a week later still has their basket.
  • Shorter is more accurate — a 30-day-old cart may contain products that no longer exist or cost something different. AIQ Ecommerce re-validates at add and checkout, so this is a UX question, not a correctness one.
  • Many hosts ignore session.gc_maxlifetime and clean sessions on their own schedule. The cookie mirror exists precisely for that, so the cart is usually restorable even when the session file is gone.

dispense_checkout_use_minimal_shell

Decides whether the checkout page renders in a minimal shell — no theme header or footer — or inside your normal layout.

apply_filters('dispense_checkout_use_minimal_shell', bool $use_minimal): bool

Always use the theme layout

add_filter('dispense_checkout_use_minimal_shell', '__return_false');

Always use the minimal shell

add_filter('dispense_checkout_use_minimal_shell', '__return_true');

Minimal shell on mobile only

Where a theme’s mobile header eats too much of a small screen:

CSS
add_filter('dispense_checkout_use_minimal_shell', function ($use_minimal) {
    return wp_is_mobile() ? true : $use_minimal;
});

What each branch does

Return Result
true The plugin emits a minimal document with wp_head()/wp_footer(), the checkout shortcode and no-cache headers, then exits
false The plugin returns early and the theme renders the page normally, with the shortcode in the content

dispense_purchase_complete_query_param

Renames the parameter that marks a completed order on the return URL.

apply_filters('dispense_purchase_complete_query_param', string $param): string
add_filter('dispense_purchase_complete_query_param', function () {
    return 'order_finished';
});

dispense_purchase_transaction_query_param

Renames the parameter carrying the transaction ID.

apply_filters('dispense_purchase_transaction_query_param', string $param): string
add_filter('dispense_purchase_transaction_query_param', function () {
    return 'order_id';
});

The same caution applies. If the parameter is missing, the plugin generates a fallback ID so the purchase event still fires — but the ID will not match the order in AIQ Ecommerce, which makes reconciliation impossible. Getting this right matters.

WordPress hooks you can use

The plugin does not add many hooks of its own, but its data flows through standard WordPress ones.

After a product is saved

add_action('save_post_dispense_product', function ($post_id, $post) {
    if (wp_is_post_revision($post_id)) {
        return;
    }

    $price = get_post_meta($post_id, 'dispense_product_price', true);
    // Your logic here.
}, 10, 2);

Fired at the end of each product upsert during a sync. Keep it fast — it runs once per product, so a slow callback multiplies across the whole catalogue.

The sync events

// Fires on the schedule.
add_action('dispense_products_cron_sync', function () {
    // Runs before the plugin's own handler at the default priority.
}, 5);

// Fired when a manual sync is triggered.
add_action('dispense_products_background_sync', function () {
    // ...
}, 5);

Purging caches after a sync

The most useful thing to hook. The sync writes dispense_products_last_sync_complete when it finishes, so:

add_action('updated_option', function ($option) {
    if ($option !== 'dispense_products_last_sync_complete') {
        return;
    }

    // Your cache plugin's purge call, for example:
    if (function_exists('rocket_clean_domain')) {
        rocket_clean_domain();
    }
}, 10, 1);

That lets you run long cache lifetimes and fresh prices — purge on sync completion rather than expiring on a timer.

Modifying product queries

add_action('pre_get_posts', function ($query) {
    if (is_admin() || ! $query->is_main_query()) {
        return;
    }

    if ($query->get('post_type') === 'dispense_product') {
        $query->set('posts_per_page', 24);
    }
});

Best practice when extending

Do not modify the plugin

Your changes are lost on the next update. Everything on this page can be done from a child theme or a small plugin.

Prefer a small plugin to functions.php

Customisations in a plugin survive a theme change, and can be deactivated independently when debugging.

PHP
<?php
/**
 * Plugin Name: AIQ Ecommerce Customisations — Your Dispensary
 * Description: Site-specific overrides for the AIQ Ecommerce Products plugin.
 * Version: 1.0.0
 */

if (! defined('WPINC')) {
    die;
}

add_filter('dispense_cart_session_lifetime', fn () => 7 * DAY_IN_SECONDS);
add_filter('dispense_checkout_use_minimal_shell', '__return_false');

Guard against the plugin being absent

add_action('plugins_loaded', function () {
    if (! class_exists('Dispense_Products_API')) {
        return;
    }

    // Safe to use the plugin's classes here.
});

Never write to the plugin’s own fields

The sync overwrites every dispense_* product field. Anything you write there lasts until the next sync. Use your own field names.

// This will be overwritten.
update_post_meta($post_id, 'dispense_product_price', '9.99');

// This will not.
update_post_meta($post_id, 'my_custom_product_note', 'Staff pick');

Keep sync-time callbacks fast

Anything hooked to save_post_dispense_product runs once per product. A callback taking 100ms adds 40 seconds to a 400-product sync.

Do not call the API on every page load

The live detail shortcodes already call out at render time, which is why pages using them cannot be cached. Do not add more. If you need AIQ Ecommerce data on a busy page, cache it in a transient.

function my_dispense_venue_offers($venue_id) {
    $key    = 'my_dispense_offers_' . md5($venue_id);
    $cached = get_transient($key);

    if ($cached !== false) {
        return $cached;
    }

    $api    = new Dispense_Products_API();
    $result = $api->make_request('/offers', [], ['venueId' => $venue_id], null, $venue_id);

    if (is_wp_error($result)) {
        return [];   // Never cache a failure.
    }

    set_transient($key, $result, 15 * MINUTE_IN_SECONDS);

    return $result;
}

Handle WPError properly

Every API call can fail. Fail soft — a licensing or network problem must never take a page down.

CSS
$result = $api->make_request('/products', [], [], null, $venue_id);

if (is_wp_error($result)) {
    error_log('AIQ Ecommerce: ' . $result->get_error_code() . ' — ' . $result->get_error_message());
    return $fallback;   // Render something, not a fatal.
}

Never store a AIQ Ecommerce API key

There is no supported way to supply one, and there should not be. If you find yourself wanting to call AIQ Ecommerce directly, route it through Dispense_Products_API::make_request() so it goes through the licensing service with the right credential attached.

Respect the mode

If your code touches the cart, check the mode first:

if (class_exists('Dispense_Cart_API') && Dispense_Cart_API::is_cart_enabled()) {
    // Cart-specific code.
}

Did this answer your question?