Hooks & Filters
A reference for the most useful action and filter hooks provided by BoxCart, with parameters, source locations, and ready-to-use code examples. BoxCart fires many more hooks than are listed here; grep the source for do_action( 'boxcart_ and apply_filters( 'boxcart_ to discover the full set.
Overview
BoxCart follows standard WordPress conventions for extensibility by exposing action hooks and filter hooks throughout its codebase. These hooks allow theme and plugin developers to modify behaviour, inject custom logic, and integrate with external services without editing BoxCart core files.
do_action()fires an action hook at a specific point in execution. Your callback runs but does not return a value. Use actions to perform side-effects such as sending notifications, logging events, or syncing data with external systems.apply_filters()fires a filter hook that passes a value through one or more callbacks. Each callback receives the value, optionally modifies it, and must return the result. Use filters to change data before BoxCart uses it - for example, adjusting prices, modifying email content, or altering available time slots.
All BoxCart hooks are prefixed with boxcart_ to avoid conflicts with other plugins. Hook callbacks should always be added in your theme's functions.php or in a custom plugin file.
Action Hooks
Action hooks let you execute custom code at specific points during BoxCart operations. Register your callback with add_action().
boxcart_order_created
Fired immediately after a new order is created during checkout. Use this hook to trigger external notifications, sync orders to a third-party system, or perform post-order processing.
| Parameter | Type | Description |
|---|---|---|
| $order_id | int | The ID of the newly created order |
Fired from: BoxCart_Checkout
add_action( 'boxcart_order_created', 'my_notify_on_new_order' );
function my_notify_on_new_order( $order_id ) {
// Example: send a Slack notification when a new order is placed
$order = BoxCart_Order::get( $order_id );
if ( ! $order ) {
return;
}
wp_remote_post( 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL', [
'body' => wp_json_encode( [
'text' => sprintf( 'New order #%s received!', $order->get_order_number() ),
] ),
'headers' => [ 'Content-Type' => 'application/json' ],
] );
}
boxcart_order_status_changed
Fired when an order's status changes (e.g. Pending to Processing, Processing to Ready). Useful for integrating with fulfilment systems or sending custom notifications based on specific status transitions.
| Parameter | Type | Description |
|---|---|---|
| $order_id | int | The ID of the order |
| $old_status | string | The previous status (e.g. 'pending', 'processing') |
| $new_status | string | The new status (e.g. 'ready', 'completed') |
Fired from: BoxCart_Order
add_action( 'boxcart_order_status_changed', 'my_on_order_ready', 10, 3 );
function my_on_order_ready( $order_id, $old_status, $new_status ) {
if ( $new_status === 'ready' ) {
// Send an SMS notification when the order is ready for collection
my_send_sms( $order_id, 'Your order is ready for collection!' );
}
}
boxcart_payment_status_changed
Fired when payment status changes on an order (e.g. when payment is confirmed as complete, fails, or is refunded). Use this to trigger accounting integrations, update external records, or send payment-specific notifications.
| Parameter | Type | Description |
|---|---|---|
| $order_id | int | The ID of the order |
| $old_status | string | The previous payment status |
| $new_status | string | The new payment status (e.g. 'paid', 'failed', 'refunded') |
Fired from: BoxCart_Order
add_action( 'boxcart_payment_status_changed', 'my_log_payment_change', 10, 3 );
function my_log_payment_change( $order_id, $old_status, $new_status ) {
if ( $new_status === 'paid' ) {
// Record the payment in an external accounting system
my_accounting_api_record_payment( $order_id );
}
}
boxcart_after_add_to_basket
Fired after an item is successfully added to the basket. A companion hook boxcart_before_add_to_basket fires before the item is added, allowing you to perform validation or logging.
| Parameter | Type | Description |
|---|---|---|
| $product_id | int | The product being added |
| $quantity | float | The quantity added |
| $basket_id | int | The basket ID |
| $quantity_type_id | int | The quantity type ID (e.g. per kg, each) |
Fired from: BoxCart_Basket
add_action( 'boxcart_after_add_to_basket', 'my_track_add_to_basket', 10, 4 );
function my_track_add_to_basket( $product_id, $quantity, $basket_id, $quantity_type_id ) {
// Track add-to-basket events for analytics
if ( function_exists( 'my_analytics_track' ) ) {
my_analytics_track( 'add_to_cart', [
'product_id' => $product_id,
'quantity' => $quantity,
] );
}
}
boxcart_before_add_to_basket
Fired before an item is added to the basket. Use this hook to perform pre-addition validation, logging, or conditional logic.
| Parameter | Type | Description |
|---|---|---|
| $product_id | int | The product being added |
| $quantity | float | The quantity requested |
| $quantity_type_id | int | The quantity type ID |
Fired from: BoxCart_Basket
add_action( 'boxcart_before_add_to_basket', 'my_log_basket_addition', 10, 3 );
function my_log_basket_addition( $product_id, $quantity, $quantity_type_id ) {
error_log( sprintf(
'BoxCart: Adding product %d (qty: %s, type: %d) to basket',
$product_id, $quantity, $quantity_type_id
) );
}
boxcart_basket_updated
Fired whenever the basket is updated (item quantity changed, item removed, etc.). Useful for recalculating custom totals or syncing basket state with an external service.
| Parameter | Type | Description |
|---|---|---|
| $basket_id | int | The ID of the updated basket |
Fired from: BoxCart_Basket
add_action( 'boxcart_basket_updated', 'my_on_basket_update' );
function my_on_basket_update( $basket_id ) {
// Invalidate any cached basket data
wp_cache_delete( 'boxcart_basket_' . $basket_id, 'boxcart' );
}
boxcart_basket_cleared
Fired when all items are cleared from a basket.
| Parameter | Type | Description |
|---|---|---|
| $basket_id | int | The ID of the cleared basket |
Fired from: BoxCart_Basket
add_action( 'boxcart_basket_cleared', 'my_on_basket_cleared' );
function my_on_basket_cleared( $basket_id ) {
// Log basket clear events for analytics
error_log( 'BoxCart: Basket ' . $basket_id . ' was cleared.' );
}
boxcart_before_checkout
Fired before the order creation process begins at checkout. Use this to perform pre-checkout validation, fraud checks, or logging.
| Parameter | Type | Description |
|---|---|---|
| No parameters | ||
Fired from: BoxCart_Checkout
add_action( 'boxcart_before_checkout', 'my_pre_checkout_log' );
function my_pre_checkout_log() {
error_log( 'BoxCart: Checkout process starting at ' . current_time( 'mysql' ) );
}
boxcart_after_checkout
Fired after the order has been created at checkout. Similar to boxcart_order_created but fires specifically within the checkout flow context.
| Parameter | Type | Description |
|---|---|---|
| $order_id | int | The ID of the newly created order |
Fired from: BoxCart_Checkout
add_action( 'boxcart_after_checkout', 'my_post_checkout_tasks' );
function my_post_checkout_tasks( $order_id ) {
// Trigger a webhook to an external fulfilment service
wp_remote_post( 'https://api.example.com/orders', [
'body' => wp_json_encode( [ 'order_id' => $order_id ] ),
'headers' => [ 'Content-Type' => 'application/json' ],
] );
}
boxcart_checkout_validation
Fired during checkout validation, allowing you to inspect or log the posted form data.
| Parameter | Type | Description |
|---|---|---|
| $posted_data | array | The sanitised checkout form data |
Fired from: BoxCart_Checkout
add_action( 'boxcart_checkout_validation', 'my_validate_checkout_data' );
function my_validate_checkout_data( $posted_data ) {
// Example: log checkout attempts for monitoring
error_log( 'BoxCart: Checkout validation for ' . $posted_data['email'] );
}
boxcart_customer_details_updated
Fired after a customer updates their account details (name, email, phone, address).
| Parameter | Type | Description |
|---|---|---|
| $customer_id | int | The WordPress user ID |
| $data | array | The updated profile data |
Fired from: BoxCart_Account
add_action( 'boxcart_customer_details_updated', 'my_sync_customer_profile', 10, 2 );
function my_sync_customer_profile( $customer_id, $data ) {
// Sync updated details to a CRM
my_crm_update_contact( $customer_id, $data );
}
boxcart_order_modified
Fired after a customer modifies an existing order (changes items, collection slot, or notes) within the allowed modification window.
| Parameter | Type | Description |
|---|---|---|
| $order_id | int | The ID of the modified order |
| $changes | array | An array describing what was changed |
| $user_id | int | The WordPress user ID of the customer who made the modification |
Fired from: BoxCart_Order_Modification
add_action( 'boxcart_order_modified', 'my_on_order_modified', 10, 3 );
function my_on_order_modified( $order_id, $changes, $user_id ) {
// Log order modifications for audit purposes
error_log( sprintf(
'BoxCart: Order #%d modified by user %d. Changes: %s',
$order_id, $user_id, wp_json_encode( $changes )
) );
}
boxcart_slot_selected
Fired when a customer selects a collection time slot for their basket.
| Parameter | Type | Description |
|---|---|---|
| $basket_id | int | The basket ID |
| $location_id | int | The selected collection location ID |
| $slot_date | string | The selected date (Y-m-d format) |
| $time_start | string | Slot start time (H:i format) |
| $time_end | string | Slot end time (H:i format) |
Fired from: BoxCart_Basket
add_action( 'boxcart_slot_selected', 'my_on_slot_selected', 10, 5 );
function my_on_slot_selected( $basket_id, $location_id, $slot_date, $time_start, $time_end ) {
// Track slot selection for demand analytics
my_analytics_track( 'slot_selected', [
'location_id' => $location_id,
'date' => $slot_date,
'time' => $time_start . ' - ' . $time_end,
] );
}
boxcart_favourite_added
Fired when a customer adds a product to their favourites list.
| Parameter | Type | Description |
|---|---|---|
| $product_id | int | The product that was favourited |
| $user_id | int | The WordPress user ID |
Fired from: BoxCart_Favourites
add_action( 'boxcart_favourite_added', 'my_track_favourite', 10, 2 );
function my_track_favourite( $product_id, $user_id ) {
// Track which products are most favourited
$count = (int) get_post_meta( $product_id, '_favourite_count', true );
update_post_meta( $product_id, '_favourite_count', $count + 1 );
}
boxcart_favourite_removed
Fired when a customer removes a product from their favourites list.
| Parameter | Type | Description |
|---|---|---|
| $product_id | int | The product that was unfavourited |
| $user_id | int | The WordPress user ID |
Fired from: BoxCart_Favourites
add_action( 'boxcart_favourite_removed', 'my_untrack_favourite', 10, 2 );
function my_untrack_favourite( $product_id, $user_id ) {
$count = max( 0, (int) get_post_meta( $product_id, '_favourite_count', true ) - 1 );
update_post_meta( $product_id, '_favourite_count', $count );
}
boxcart_favourites_cleared
Fired when a customer clears all of their favourites in one go (e.g. via the "Clear all" button on the favourites view).
| Parameter | Type | Description |
|---|---|---|
| $user_id | int | The WordPress user ID whose favourites list was cleared |
Fired from: BoxCart_Favourites
add_action( 'boxcart_favourites_cleared', 'my_on_favourites_cleared' );
function my_on_favourites_cleared( $user_id ) {
// Reset any cached favourites data for this customer
delete_user_meta( $user_id, 'my_favourites_cache' );
}
boxcart_admin_settings_saved
Fired after the admin saves BoxCart settings from the settings page.
| Parameter | Type | Description |
|---|---|---|
| $settings | array | The full settings array that was saved |
Fired from: BoxCart_Admin_Settings
add_action( 'boxcart_admin_settings_saved', 'my_on_settings_saved' );
function my_on_settings_saved( $settings ) {
// Clear any caches when settings change
wp_cache_flush();
// Log which admin changed settings
error_log( 'BoxCart settings updated by user ' . get_current_user_id() );
}
boxcart_admin_dashboard
Fired when the BoxCart admin dashboard view is rendered. Use this to inject custom widgets or content into the dashboard.
| Parameter | Type | Description |
|---|---|---|
| No parameters | ||
Fired from: dashboard.php (admin view)
add_action( 'boxcart_admin_dashboard', 'my_custom_dashboard_widget' );
function my_custom_dashboard_widget() {
echo '<div class="boxcart-dashboard-widget">';
echo '<h3>Custom Analytics</h3>';
echo '<p>Your custom dashboard content here.</p>';
echo '</div>';
}
boxcart_admin_order_status_fields and boxcart_before_delete_order
Added in 1.5.0.
| Action | Arguments | Description |
|---|---|---|
| boxcart_admin_order_status_fields | BoxCart_Order $order | Fires inside the Update Status form on the admin order screen, under the status choice. Add your own fields here: they're posted with the status change, so you can read them in boxcart_before_admin_status_update. BoxCart Pro adds its "Refund to the customer's card" box here. |
| boxcart_before_delete_order | int $order_id | Fires before a cancelled order is deleted, so you can remove your own data for it. BoxCart Pro removes the order's messages. |
Fired from: order-view.php (admin view) and BoxCart_Order::delete().
Filter Hooks
Filter hooks let you modify data before BoxCart uses it. Register your callback with add_filter(). Your callback must return a value - either the original value unmodified or your modified version.
boxcart_basket_total
Filter the basket total before it is displayed or used in calculations. Use this to apply custom discounts, surcharges, or pricing logic.
| Parameter | Type | Description |
|---|---|---|
| $total | float | The calculated basket total |
| $basket | BoxCart_Basket | The basket instance (use $basket->get_items(), $basket->get_total(), etc.) |
Returns: float - The filtered basket total.
add_filter( 'boxcart_basket_total', 'my_apply_bulk_discount', 10, 2 );
function my_apply_bulk_discount( $total, $basket ) {
// Apply a 10% discount on orders over 50
if ( $total > 50 ) {
$total *= 0.9;
}
return $total;
}
boxcart_email_recipient
Filter the recipient email address before an email is sent. Use this to add CC recipients, redirect emails during testing, or conditionally change recipients.
| Parameter | Type | Description |
|---|---|---|
| $to | string | The recipient email address |
| $order | BoxCart_Order | The order object associated with the email (use getters like $order->get_customer_email()) |
Returns: string - The filtered email address.
add_filter( 'boxcart_email_recipient', 'my_redirect_test_emails', 10, 2 );
function my_redirect_test_emails( $to, $order ) {
// During development, redirect all emails to a test address
if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
return 'dev-testing@example.com';
}
return $to;
}
boxcart_email_subject
Filter the subject line of emails sent by BoxCart.
| Parameter | Type | Description |
|---|---|---|
| $subject | string | The email subject line |
| $template_type | string | The email template type. This filter fires for 'order_confirmation', 'order_modified', and 'order_message_to_customer'. |
| $order | BoxCart_Order | The order object (use getter methods) |
Returns: string - The filtered subject line.
add_filter( 'boxcart_email_subject', 'my_custom_email_subject', 10, 3 );
function my_custom_email_subject( $subject, $template_type, $order ) {
// Add a store name prefix to all email subjects
$store_name = BoxCart_Helpers::get_settings()['business_name'] ?? 'Our Store';
return '[' . $store_name . '] ' . $subject;
}
boxcart_email_content
Filter the content of emails before they are sent. Use this to add custom sections, banners, or modify the email body. It runs for the customer emails and, since 1.6.0, for the shop's own emails too (new_order_admin, order_modified_admin, order_message_to_admin, payment_failed_admin). Since 1.8.0 it also runs for two BoxCart Pro emails to the shop: refund_failed (a card refund didn't go through) and shop_report (the weekly or monthly Shop Report). The shop's emails are plain text, not HTML, when Admin Email Format is set to Plain Text.
| Parameter | Type | Description |
|---|---|---|
| $content | string | The email content (HTML, or plain text for the shop's emails when set to Plain Text) |
| $template_type | string | The email template type |
| $order | BoxCart_Order|null | The order object (use getter methods). null for shop_report, which isn't about one order. |
Returns: string - The filtered email content.
add_filter( 'boxcart_email_content', 'my_add_email_footer', 10, 3 );
function my_add_email_footer( $content, $template_type, $order ) {
// Add a promotional footer to order confirmation emails
if ( $template_type === 'order_confirmation' ) {
$content .= '<div style="margin-top:20px;padding:15px;background:#f8f8f8;">';
$content .= '<p>Thank you for your order! Use code COLLECT10 for 10% off your next order.</p>';
$content .= '</div>';
}
return $content;
}
boxcart_email_headers
Filter the email headers (e.g. to add CC, BCC, or Reply-To addresses).
| Parameter | Type | Description |
|---|---|---|
| $headers | string|array | The email headers |
| $to | string | The recipient email address |
| $subject | string | The email subject |
Returns: string|array - The filtered headers.
add_filter( 'boxcart_email_headers', 'my_add_bcc_to_emails', 10, 3 );
function my_add_bcc_to_emails( $headers, $to, $subject ) {
// BCC the store manager on all outgoing emails
if ( is_array( $headers ) ) {
$headers[] = 'Bcc: manager@example.com';
} else {
$headers .= "\r\nBcc: manager@example.com";
}
return $headers;
}
boxcart_show_prices and members-only pricing filters
These filters drive the members-only pricing feature. They live in the free core so BoxCart Pro (or your own code) can hide prices and the add-to-cart controls from logged-out visitors. On the free build they return their defaults unless you filter them yourself.
| Filter | Type | Description |
|---|---|---|
| boxcart_show_prices | bool | Whether product prices are shown. Return false to hide prices. |
| boxcart_show_add_to_cart | bool | Whether the add-to-cart control is shown. Return false to hide it. |
| boxcart_hidden_price_text | string | Message shown in place of a hidden price (default 'Log in to see prices and order'). |
| boxcart_hidden_price_cta_label | string | Label for the call-to-action shown with a hidden price (default 'Log in'). |
| boxcart_can_add_to_basket | bool | Server-side guard on the add-to-basket AJAX action. Return false to block it. |
| boxcart_can_place_order | bool | Server-side guard on placing an order. Return false to block checkout. |
Defined in: BoxCart_Helpers and BoxCart_Ajax.
boxcart_max_line_quantity and boxcart_checkout_discount
Added in 1.3.1. Both are applied on the server, so a value sent from the browser can never override them.
| Filter | Arguments | Description |
|---|---|---|
| boxcart_max_line_quantity | float $max, array $quantity_type | The highest quantity allowed on a single basket line, applied on top of a product's own maximum. Default 100000 (enough for 100 kg sold by the gram). |
| boxcart_checkout_discount | float $discount, array $items, float $subtotal | A discount to take off the order subtotal at checkout, before tax. Default 0. The result is kept between zero and the subtotal. |
Defined in: BoxCart_Product_Quantities and BoxCart_Checkout.
Checkout, payment and customer filters
Added in 1.5.0.
| Filter | Arguments | Description |
|---|---|---|
| boxcart_checkout_ask_billing_address | bool $ask | Whether checkout asks for (and requires) a billing address. Default false. Only applies when prices are switched on. |
| boxcart_payment_setup_problems | string[] $problems | Messages about payment settings that don't fit together, shown as warnings at the top of BoxCart's admin screens. Free adds one when payments are on but no payment method is available; BoxCart Pro adds one when card payment is on without Stripe keys for the current mode. |
| boxcart_before_admin_status_update | null|WP_Error $error, BoxCart_Order|false $order, string $new_status | Runs before an admin changes an order's status from the order screen. Return a WP_Error to stop the change: its message is shown on the order screen. BoxCart Pro uses it to refund the card first when an order is cancelled with the refund box ticked. |
| boxcart_customer_roles | string[] $roles | Roles treated as customers: sent to My Account instead of the WordPress dashboard, and shown no admin bar, when those settings are on. Default array( 'boxcart_customer', 'subscriber', 'customer' ). A user counts as a customer only if all their roles are in the list and they can't edit_posts. |
| boxcart_hide_duplicate_page_heading | bool $hide, string $element_id | BoxCart hides its own Checkout and My Account heading when the theme already shows the same title above it. Return false to always show BoxCart's heading. Default true. |
Defined in: BoxCart_Checkout, BoxCart_Payment, BoxCart_Admin_Orders, BoxCart and BoxCart_Frontend.
// Ask for a billing address at checkout again.
add_filter( 'boxcart_checkout_ask_billing_address', '__return_true' );
// Treat a custom "member" role as a customer too.
add_filter( 'boxcart_customer_roles', function ( $roles ) {
$roles[] = 'member';
return $roles;
} );
// Don't let an order be cancelled without a note.
add_filter( 'boxcart_before_admin_status_update', function ( $error, $order, $new_status ) {
if ( 'cancelled' === $new_status && empty( $_POST['status_note'] ) ) {
return new WP_Error( 'note_needed', 'Add a note saying why the order was cancelled.' );
}
return $error;
}, 10, 3 );
Shop staff and the order page
Added in 1.6.0.
| Hook | Arguments | Description |
|---|---|---|
| boxcart_dashboard_widget_capability | string $capability | Filter. Capability needed to see the BoxCart Today dashboard widget. Default is now manage_boxcart_shop (administrators and shop staff), not manage_options. Since 1.8.0 it also covers the widget's day picker and its Resend button for missing shop emails. |
| boxcart_order_confirmation_actions | BoxCart_Order $order, string $view_token | Action. Runs after the order details on the order confirmation page (also reached from the confirmation email). $view_token is the order's token when the page was opened with it, otherwise empty. BoxCart Pro adds "Change your order" here for the signed-in customer who owns the order, and, for a guest, a note on how to change it with an account. |
| boxcart_order_view_link_text | string $text, BoxCart_Order $order | Filter. The words on the order confirmation email's link to the order. Default "View your order online →". |
| boxcart_order_message_text | string $text, BoxCart_Order $order, int $message_id | Filter. The text of an order message, for the email about it. Message emails are queued with the message's ID rather than its text; BoxCart Pro looks the text up here. Default empty. |
Shop access is the manage_boxcart_shop capability (see Shop staff). Check it with current_user_can( 'manage_boxcart_shop' ) in your own shop tools.
Collection times for a date, and order change wording
Added in 1.6.0. Every check that works from a date (the slot list at checkout, the calendar, booking, the dashboard) now asks BoxCart_Location::get_slots_for_date( $date ) and is_open_on_date( $date ), so they all agree. BoxCart Pro's special times hook in here.
| Hook | Arguments | Description |
|---|---|---|
| boxcart_slots_for_date | array $slots, int $location_id, string $date | Filter. The collection slots a location has on a date (Y-m-d): arrays with id, time_start and time_end (H:i:s) and capacity, earliest first. Default: the location's weekly slots for that day of the week. BoxCart Pro returns the date's special times instead when it has some; their ids look like date-12 and they carry their own capacity. |
| boxcart_location_open_on_date | bool $open, int $location_id, string $date | Filter. Whether a location takes collections on a date, before closures are checked (a closure still closes it). Default: the weekly schedule. BoxCart Pro opens a date with special times even on a day the location is usually closed. |
| boxcart_order_email_changes_text | string $text, BoxCart_Order $order | Filter. A line in the order confirmation email saying until when the customer can change the order, e.g. "You can change this order until 1:00 pm on Sunday 20 December." Default empty; BoxCart Pro fills it in while changes are open. |
The boxcart_order_modify_state array (used for the order window) also has a changes_text key since 1.6.0: the whole sentence saying until when, or for how long, the order can be changed.
Status emails and customer sign-in forms
Added in 1.7.0.
| Hook | Arguments | Description |
|---|---|---|
| boxcart_queue_status_email | bool $send, int $order_id, string $old_status, string $new_status | Filter. Whether a status change queues the customer's status email. Default true. BoxCart returns false while it completes orders after the collection day, so customers aren't emailed. |
| boxcart_security_form_fields | bool $fire, string $form | Filter. Whether BoxCart runs WordPress's own form action inside its customer forms, so security plugins can add their fields (CAPTCHAs). $form is login, register, lostpassword or resetpass (firing login_form, register_form, lostpassword_form, resetpass_form). Default true. |
| boxcart_security_form_skip | array $skip, string $form | Filter. Callbacks on those form actions that BoxCart leaves out of its forms, because they only work on wp-login.php (for example WP 2FA's passkey button). Add a callable to leave out another one. |
Search Insights
Added in 1.8.0. The Searches screen (BoxCart > Searches) and the BoxCart Searches dashboard widget are part of the free plugin. BoxCart Pro adds its extras (week by week, rising searches, "now in stock" notes, the CSV download and "led to a basket add") through these hooks.
| Hook | Arguments | Description |
|---|---|---|
| boxcart_search_insights_track_adds | bool $track | Filter. Whether the shop page reports a search that led to a basket add, so the log's adds column is counted and the Searches screen shows "led to a basket add". Default false. BoxCart Pro returns true while Search Insights is on and the licence is active. |
| boxcart_dashboard_widget_searches | array $panel | Action. Fires in the BoxCart Searches dashboard widget, under the summary line and above the "Most searched" and "Found nothing" lists. $panel holds the last 30 days: totals (searches, no_results), top and none (rows with term, term_key, searches and results). Only fires while Search Insights is on. BoxCart Pro shows its "now in stock" notes here. |
| boxcart_searches_screen_after_figures | array $search_range, array $search_terms | Action. Fires on the Searches screen, under the figures. $search_range has from, to, prev_from and prev_to (Y-m-d). $search_terms has one row per search in the period, most searched first: term, term_key, searches, no_results, results, adds, last_searched and previous (searches in the period before). BoxCart Pro adds week by week here. |
| boxcart_searches_screen_side | array $search_range, array $search_terms | Action. Fires on the Searches screen, under the "Found nothing" list. Same arguments as above. BoxCart Pro adds rising searches and "now in stock" notes here. |
| boxcart_searches_screen_footer | string $search_period | Action. Fires at the foot of the Searches screen. $search_period is 4weeks, 12weeks or 26weeks. BoxCart Pro adds its "Download as a spreadsheet (CSV)" link here. |
The three Searches screen hooks only fire while Search Insights is on and the chosen period has searches. The screen and the widget need the manage_boxcart_shop capability.
Defined in: BoxCart_Search_Insights, BoxCart_Admin_Searches and searches.php (admin view).
// Beside the lists on BoxCart > Searches: how many different
// searches found nothing in the chosen period.
add_action( 'boxcart_searches_screen_side', function ( $range, $terms ) {
$nothing = array_filter( $terms, function ( $row ) {
return 0 === $row['results'] && 0 === $row['adds'];
} );
printf(
'<div class="boxcart-card"><p>%d different searches found nothing.</p></div>',
count( $nothing )
);
}, 10, 2 );
Shop-wide emails and email templates
Added in 1.8.0. BoxCart Pro's Shop Report email uses all three; its failed refund email uses boxcart_email_template_file.
| Hook | Arguments | Description |
|---|---|---|
| boxcart_outbox_shop_wide_types | string[] $types | Filter. Email types the outbox may hold that aren't about one order (queued with order ID 0). Default array( 'daily_collections' ). BoxCart Pro adds shop_report. |
| boxcart_send_shop_wide_email | string $email_type, string $extra | Action. Sends a queued email of one of those types. BoxCart sends daily_collections itself, so this fires for the others. $extra is what the email was queued with (for the Shop Report, its period). BoxCart Pro sends the Shop Report here. |
| boxcart_email_template_file | string $file, string $template, bool $plain | Filter. The template file an email is built from. Default includes/emails/{$template}.php in the plugin folder, or includes/emails/plain-text/{$template}.php when $plain is true. BoxCart Pro uses its own folder for shop-report and refund-failed, which BoxCart has no file for. |
Defined in: BoxCart_Email.
BoxCart fires many more action and filter hooks than are catalogued here. If you need a hook at a specific point that is not listed, grep the source for do_action( 'boxcart_ / apply_filters( 'boxcart_, consider extending BoxCart, or raise a feature request.