This guide explains how to integrate HubBox pickup point selection into your WooCommerce store using the HubBox Tag script. This method involves adding HubBox's JavaScript directly into your website's frontend on the checkout page.
For full details on the HubBox Tag, refer to the Tag documentation.
| Requirement | Details |
|---|---|
| WooCommerce store | A functioning WooCommerce installation on WordPress |
| Admin access | WordPress admin privileges to install plugins or edit theme files |
| HubBox Tag script | The JavaScript snippet or CDN URL provided by your HubBox Integrations Manager — unique to your account |
There are two primary ways to add the HubBox Tag script to your WooCommerce site. Choose the method that best suits your setup before proceeding.
A plugin provides a user-friendly interface within WP Admin, reduces the risk of PHP errors breaking your site, and typically includes options to load scripts only on specific pages such as the checkout.
The trade-off is an additional plugin dependency.
functions.php (Child Theme or Custom Plugin)Editing functions.php requires no extra plugin and gives direct control via code. However, it requires familiarity with PHP and WordPress hooks.
Never edit your main theme's functions.php directly — changes will be lost on theme updates and PHP errors can break your site. Always use a Child Theme or a site-specific custom plugin.
Before you begin, ensure you have the correct HubBox Tag script from your HubBox Integrations Manager. This JavaScript snippet contains your unique configuration ID and the logic required to display and manage the HubBox pickup point selection interface on your WooCom checkout.
You can access the Tag script via Console by going to "Setup" and then "Tag Management" in the menu.
Install a reputable plugin designed for adding custom code snippets or header/footer scripts. Options include:
HubBox is not affiliated with these third-party plugins. Evaluate them based on your needs, compatibility, and reviews before installing.
Navigate to the plugin's interface within your WP Admin panel and create a new snippet. Configure it as follows:
HubBox Tag Script.<script src="YOUR_HUBBOX_CDN_URL_HERE"></script> or use the plugin's option for enqueueing external scripts if available.</body> tag. This ensures the page is mostly loaded before the script runs.is_checkout()). Avoid loading it site-wide.!cdn.hub-box.com/console/woocom/woocom-snippet-plugin.png
Save the snippet and confirm it is active. Refer to your chosen plugin's documentation for any plugin-specific steps.
functions.phpOnly use this method if you are comfortable editing PHP and are working within a Child Theme or custom plugin. Incorrect PHP code can break your site.
Ensure you have the correct HubBox Tag script or CDN URL from your HubBox Integrations Manager before proceeding.
functions.phpOpen the functions.php file of your active Child Theme (or your custom plugin file) using one of the following methods:
Paste the appropriate code snippet at the end of the file. Choose the method that matches what HubBox provided.
Recommended: Enqueueing the Script (CDN URL)
This method correctly adds the script to the WordPress page load queue and supports footer loading. Replace YOUR_HUBBOX_CDN_SCRIPT_URL_HERE with the URL provided by HubBox.
/**
* Enqueue HubBox Tag Script on WooCommerce Checkout Page.
*/
function enqueue_hubbox_checkout_script() {
if ( function_exists( 'is_checkout' ) && is_checkout() ) {
wp_enqueue_script(
'hubbox-tag', // Unique handle for the script
'YOUR_HUBBOX_CDN_SCRIPT_URL_HERE', // CDN URL provided by HubBox
array(), // Dependencies (usually empty)
null, // Script version (optional)
true // Load in footer (recommended)
);
}
}
add_action( 'wp_enqueue_scripts', 'enqueue_hubbox_checkout_script' );
Alternative: Embedding a Full Script Block (wp_footer)
If HubBox provided a full <script>...</script> block rather than a CDN URL, use this method instead. Replace the comment block with the complete script provided by HubBox.
/**
* Add HubBox Tag Script Block to Footer on WooCommerce Checkout Page.
*/
function add_hubbox_footer_script() {
if ( function_exists( 'is_checkout' ) && is_checkout() ) {
?>
<script>
// PASTE FULL HUBBOX TAG SCRIPT BLOCK HERE
// (including the config object inside)
</script>
<?php
}
}
add_action( 'wp_footer', 'add_hubbox_footer_script' );
Save the functions.php file. If the page breaks after saving, check for PHP syntax errors in the code you added.
Locate the config object within the HubBox Tag script and set the mode property to "test":
config: {
mode: "test", // Set to "test" for testing
// ... other configuration options ...
}
functions.php with embedded full script — Edit the script directly within your functions.php file.functions.php with enqueued CDN script — The config object must be defined before the enqueued script runs. Add a small inline script via wp_footer or wp_head that defines window.HubBoxConfig = { mode: "test", ... } before the enqueued script loads. Contact HubBox support if you are unsure how to configure test mode with the CDN method.With mode: "test" set, the HubBox widget only appears when a specific query parameter is appended to your checkout URL. Navigate to your WooCommerce checkout page and add ?hubboxPayloadTest=true to the end of the URL:
yourstore.com/checkout/?hubboxPayloadTest=true
This allows you to see and interact with the HubBox integration without affecting regular customers.
If you have a WordPress staging environment, test there first before testing on your live site.
Work through the following checklist during testing:
Once testing is complete and you are satisfied with the integration:
Access the HubBox Tag script via your plugin or child theme's functions.php and change the mode property from "test" to "live":
config: {
mode: "live", // Set to "live" for deployment
// ... other configuration options ...
}
Save the script. HubBox pickup options will now be live for all eligible customers.
The HubBox Tag script includes a config object where advanced features such as product eligibility filtering and shipping rate filtering can be configured.
Use this feature to prevent the HubBox pickup option from appearing when the cart contains items unsuitable for pickup (e.g., oversized or hazardous items). This is configured using the callbacks.getShouldBailOut function within the Tag script's config.
The function must return true to hide HubBox ("bail out") or false to show it. For guidance on eligibility strategy, refer to the /docs/product-eligibility.
The examples below should be added within config.callbacks in your HubBox Tag script.
This example checks the cart against a predefined list of ineligible SKUs. It relies on product data being available in a window.dataLayer_content object, which is common in Google Tag Manager / GA4 setups for WooCommerce. Verify your data layer structure before using this approach.
callbacks: {
getShouldBailOut: () =>
new Promise((resolve) => {
try {
const notAllowed = ["SKU-NO-PICKUP-1", "SKU-NO-PICKUP-2"]; // Your ineligible SKUs
const products = window?.dataLayer_content?.ecommerce?.checkout?.products;
if (!Array.isArray(products)) {
console.warn("HubBox Bailout: Data layer for products not found or not an array.");
resolve(false);
return;
}
const cartSkuList = products.map((product) => product?.sku);
const hasNotAllowedSku = cartSkuList.some((sku) => notAllowed.includes(sku));
resolve(hasNotAllowedSku); // Bail out (true) if an ineligible SKU is found
} catch (error) {
console.error("HubBox Bailout SKU Check Error:", error);
resolve(false); // Default to not bailing out on error
}
}),
}
This example reads the cart total from the DOM and bails out if it meets or exceeds a defined threshold.
This approach relies on scraping a value from the DOM and is sensitive to theme and plugin changes. The CSS selector below targets a standard WooCommerce order review table — you may need to adjust it for your theme. A server-side check or WooCommerce session data via AJAX is more robust if available.
callbacks: {
getShouldBailOut: () => new Promise(resolve => {
try {
// Adjust this selector to match your theme's order total element
var selector = ".shop_table.woocommerce-checkout-review-order-table .order-total .woocommerce-Price-amount.amount";
var totalElement = document.querySelector(selector);
if (!totalElement) {
console.warn("HubBox Bailout: Cart total element not found with selector:", selector);
resolve(false);
return;
}
// Parse the total value — adjust for your store's currency format
var total = Number(
totalElement.innerText
.replace(/[^0-9.,]+/g, "")
.replace(",", ".")
);
const maxPickupValue = 5000; // Set your threshold
resolve(total >= maxPickupValue); // Bail out if total meets or exceeds threshold
} catch (error) {
console.error("HubBox Bailout Value Check Error:", error);
resolve(false); // Default to not bailing out on error
}
}),
}
Use this feature to show or hide specific WooCommerce shipping methods based on whether the customer selects Home Delivery or HubBox Pickup. This is configured within the config.shippingMethods object in your HubBox Tag script. For strategy guidance, refer to the /docs/shipping-rate-filtering.
config: {
shippingMethods: {
wrapper: '#shipping_method',
interactionPreventionAction: 'hide li',
excludeOnLocalPickup: [
{
selectors: [
'text-fragment: Royal Mail',
'text-fragment: Evri',
],
},
],
},
}
Once the HubBox Tag script is correctly implemented and live:
functions.php, confirm the file was saved without PHP errors and the child theme is active.?hubboxPayloadTest=true to the checkout URL and that mode is set to "test" in the script config.configId within the script is correct for your environment.nearest or within in request URLs).console.log statements within your callback to trace the execution path and confirm the expected data is available.window.dataLayer_content object exists and contains the expected structure on your checkout page..catch() block to resolve false (not bail out).wrapper selector (#shipping_method) matches the actual element on your checkout page — this may differ depending on your theme or checkout plugins.text-fragment values in excludeOnLocalPickup match the exact text displayed for each shipping method on your checkout.