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:
add_filter('dispense_cart_enabled', function ($enabled) {
return wp_get_environment_type() === 'production' ? $enabled : false;
});
Turn it off for a maintenance window
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_maxlifetimeand 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:
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
/**
* 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.
$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.
}