HubBox Module for Magento 2

This guide provides everything you need to install, configure, and customise the HubBox module for your Magento 2 store. The module integrates HubBox pickup point selection directly into the Magento checkout, offering customers convenient delivery alternatives alongside standard home delivery.

The HubBox Extension is only suitable for standard Magento 2 checkouts. If your store uses a custom checkout application such as Hyvä or Amasty One Step Checkout, these can conflict with the module. In such cases, use the HubBox Tag or SDK integration instead.

Prerequisites

Before beginning installation, ensure the following are in place:

Requirement Details
Magento 2 instance A functioning Magento 2 installation on a supported version.
SSH / CLI access Access to your Magento server environment via terminal or SSH client.
Composer Installed and configured for your Magento project.
Magento Admin access Admin Panel access with appropriate permissions to install modules and modify configuration.
HubBox Composer credentials Username and Password for composer.developers.hub-box.com.
HubBox API credentials Username, Password/API Key, Client ID, and Client Secret.
HubBox configId Your HubBox configId — provided by your HubBox Integrations Manager.

Always perform installation steps on a staging or development environment first. Back up your site and database before proceeding.

Installation

Enable Maintenance Mode

Put your store into maintenance mode to prevent customer-facing errors during installation:

bin/magento maintenance:enable

Configure the Composer Repository

Add the HubBox Composer repository to your project's root composer.json file.

{
  "type": "composer",
  "url": "composer.developers.hub-box.com"
}

Your repositories section should look similar to this afterwards:

"repositories": [
    {
        "type": "composer",
        "url": "repo.magento.com/"
    },
    {
        "type": "composer",
        "url": "composer.developers.hub-box.com"
    }
]

composer config http-basic.composer.developers.hub-box.com USERNAME PASSWORD

Require the HubBox Module

Navigate to your Magento project root and run the composer require command. Replace x.y.z with the version number confirmed by your HubBox Integrations Manager:

COMPOSER_MEMORY_LIMIT=-1 composer require hub-box/click-and-collect:x.y.z

Setting COMPOSER_MEMORY_LIMIT=-1 prevents memory exhaustion errors on some server configurations.

If you did not pre-configure authentication in the previous step, Composer will prompt for credentials:

Authentication required (composer.developers.hub-box.com):
    Username: YOUR_HUBBOX_COMPOSER_USERNAME
    Password: YOUR_HUBBOX_COMPOSER_PASSWORD

Wait for Composer to download the module and its dependencies before proceeding.

Enable the Module and Run Setup

Enable the module within Magento:

bin/magento module:enable HubBox_ClickAndCollect

Run the setup upgrade to install the module's database schema and data:

bin/magento setup:upgrade

Compile and Deploy Static Content

If your store is running in Production mode, compile Magento's dependency injection:

bin/magento setup:di:compile

Deploy static view files. Replace en_US fr_FR with the locales used on your store:

bin/magento setup:static-content:deploy en_US fr_FR -f

Clear Cache

bin/magento cache:clean
bin/magento cache:flush

Disable Maintenance Mode

bin/magento maintenance:disable

The HubBox module is now installed and enabled. Proceed to configuration.

Configuration

Configure the module via the Magento Admin Panel.

Open HubBox Settings

Log in to your Magento Admin Panel and navigate to Stores > Configuration. In the left panel, expand HubBox and select Settings.

Set the Scope

Set the Scope (top-left dropdown) correctly — for example, a specific Website or Store View — before entering values.

Configure the Fields

Enter the values as described in the table below:

Configuration Field Scope Description Source Default
Enabled Website Set to Yes to enable HubBox functionality on the frontend checkout for the selected scope. N/A No
Inject Carrier Extra Data Website Set to Yes if using carriers (such as UPS API or DPD) that require HubBox to inject special codes into address fields for manifesting. Typically Yes. N/A Yes
Environment Website Select Sandbox for testing/development or Production for your live site. Determines which HubBox API endpoints the module communicates with. N/A Sandbox
Username Website HubBox API Username for authentication. Generate within Console —
Password Website HubBox API Password or Key for authentication. Generate within Console —
Client ID Website HubBox API Client ID for authentication. Generate within Console —
Client Secret Website HubBox API Client Secret for authentication. Generate within Console —
Design Store View Controls how the HubBox Widget is displayed: Modal (overlay popup) or Embed (inline on the page). N/A Modal
configId Store View Your unique HubBox configId. Determines network availability, Widget styling (colours, fonts, map settings), and other features. Provided by HubBox —

Credentials are case-sensitive and must not contain leading or trailing spaces. Use separate credentials for Sandbox and Production environments — do not use Sandbox credentials on your live site. You can generate your API credentials in Console by clicking "Setup" and then "Credentials Management" in the menu.

Save and Flush Cache

Click Save Config, then flush the Magento cache:

bin/magento cache:flush

Frontend Integration

The HubBox module uses standard Magento mechanisms to inject its frontend components into the checkout. It uses Magento's Layout XML (checkout_index_index.xml), Blocks, Templates (.phtml), and UI Components / KnockoutJS / JavaScript to render the following elements at the appropriate checkout step:

By default, the Launch Experience block (containing the Home Delivery and Local Pickup children) is injected at checkout.root.checkout.steps.shipping-step.shippingAddress. This position can be changed via Layout XML in a custom module — see the Advanced Customisation section below.

The visible UI elements are rendered using /docs/components-installation.

Styling

Default Styles

The module ships with default CSS providing basic styling for the launch experience components.

Applying Custom Styles (Recommended Method)

All customisations must be made in a custom Magento module that declares a dependency on HubBox_ClickAndCollect. Do not modify the HubBox module files directly — changes will be overwritten on the next module update.

Create a Custom Module

Create a module.xml for your custom module with a dependency on HubBox_ClickAndCollect:

<?xml version="1.0"?>
<config xmlns:xsi="w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="[YourNamespaceName]_[YourModuleName]">
        <sequence>
            <module name="HubBox_ClickAndCollect"/>
        </sequence>
    </module>
</config>

Replace [YourNamespaceName] and [YourModuleName] with your actual module name fragments.

Add a Layout XML File

Create checkout_index_index.xml under [YourNamespaceName]/[YourModuleName]/view/frontend/layout/:

<?xml version="1.0"?>
<page xmlns:xsi="w3.org/2001/XMLSchema-instance"
      layout="1column"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <head>
        <!-- Remove the default HubBox theme CSS -->
        <remove src="HubBox_ClickAndCollect::css/theme/orange.css"/>
        <!-- Add your custom CSS -->
        <css src="[YourNamespaceName]_[YourModuleName]::[your/desired/path]/[your-desired-name].css"/>
    </head>
</page>

The your/desired/path is a path of your choice within the [YourNamespaceName]/[YourModuleName]/view/frontend/web/css/ directory.

Create Your Custom CSS File

Create your CSS file at the path specified in the previous step. Style the HubBox Web Components using the CSS ::part() pseudo-element. Reference examples are available in vendor/hub-box/click-and-collect/view/frontend/web/css/theme/.

/* Example: Change the search button colour to yellow */
hb-core-search::part(search-button) {
  background-color: yellow;
}

/* Example: Style the toggle radio button */
hubbox-local-pickup-toggles::part(radio) {
  color: var(--primary-color);
  border: 1px solid var(--primary-color);
}

/* Example: Style the title within the home delivery choice component */
hubbox-home-delivery-toggles::part(title) {
  font-weight: bold;
  font-size: 1.1em;
}

Refer to the /docs/components-installation for the full list of available ::part() names and CSS variables (:root overrides) for easier theming.

Redeploy Static Content and Clear Caches

After adding or changing CSS, redeploy static content and clear caches:

bin/magento setup:static-content:deploy en_US fr_FR -f
bin/magento cache:flush

Styling Caveats: Inside the Widget

The HubBox Widget (the map and location list UI, whether in Modal or Embed mode) runs inside an <iframe>. This means:

For Widget appearance customisation, refer to the /docs/widget-configuration.

Advanced Customisation

For functionality beyond the standard configuration, Magento's plugin (interceptor) system and dependency injection (di.xml) are used. This requires Magento development expertise.

All customisations must be implemented in a custom module that depends on HubBox_ClickAndCollect. Never modify the HubBox module files directly. Install and test the module's standard functionality before building customisations — this makes it significantly easier to identify when an issue was introduced.

Relocating the Launch Experience

By default, the Launch Experience block sits at checkout.root.checkout.steps.shipping-step.shippingAddress. To move it:

  1. In your custom module's checkout_index_index.xml, remove the default reference and inject it at your desired location.
  2. To hide the Launch Experience components entirely and show only the Pickup Confirmation component, use custom CSS to hide the launch experience block.
  3. To bind the click event of a custom radio button to the HubBox selection logic, call the clickAndCollect method from the HubBox helper:
require("HubBox_ClickAndCollect/js/view/helper").clickAndCollect();
  1. To check whether a HubBox pickup is currently selected (e.g., to uncheck a radio button if no collect point is set), use the getIsHubBoxOrder method:
const checkoutData = require("HubBox_ClickAndCollect/js/checkout-data");
const isHubBoxOrder = checkoutData.getIsHubBoxOrder();

Product Eligibility Filtering

In certain cases, you may need to prevent the HubBox pickup option from appearing when the cart contains ineligible items. See the /docs/product-eligibility for the full strategy guide.

Two common implementation approaches are available:

Option 1: Plugin on ConfigProvider (Simpler)

Create an after plugin on HubBox\ClickAndCollect\Model\Ui\ConfigProvider::getConfig(). In your afterGetConfig method, inspect the current quote, check its items against your eligibility rules, and modify the isClickAndCollectable value in the $result array before returning it.

<?php
namespace Vendor\Module\Plugin\HubBox\Ui;

use HubBox\ClickAndCollect\Model\Ui\ConfigProvider;
use Magento\Checkout\Model\Session as CheckoutSession;

class ConfigProviderPlugin
{
    protected $checkoutSession;

    public function __construct(CheckoutSession $checkoutSession)
    {
        $this->checkoutSession = $checkoutSession;
    }

    public function afterGetConfig(ConfigProvider $subject, array $result): array
    {
        $isEligible = $result['isClickAndCollectable'] ?? true;

        try {
            $quote = $this->checkoutSession->getQuote();
            if ($quote && $quote->getId()) {
                foreach ($quote->getAllVisibleItems() as $item) {
                    $product = $item->getProduct();
                    // Example: check a custom product attribute 'allow_pickup'
                    if ($product->getData('allow_pickup') === '0') {
                        $isEligible = false;
                        break;
                    }
                    // Add additional checks here (category, dimensions, etc.)
                }
            }
        } catch (\Exception $e) {
            // Log the error; default to ineligible on exception
            $isEligible = false;
        }

        $result['isClickAndCollectable'] = $isEligible;
        return $result;
    }
}

Declare the plugin in your module's etc/di.xml.

Option 2: DI Preference for WidgetConfigInterface (More Involved)

Define a preference in your module's etc/di.xml to replace the default implementation of HubBox\ClickAndCollect\Api\WidgetConfigInterface with your own custom class. Your class must implement the interface and inject the necessary dependencies (such as CheckoutSession) to access quote data.

<config xmlns:xsi="w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <preference for="HubBox\ClickAndCollect\Api\WidgetConfigInterface"
                type="Vendor\Module\Model\CustomWidgetConfig"/>
</config>

Use this approach for complex eligibility logic that requires injecting multiple dependencies or implementing custom interfaces.

Shipping Rate Filtering

To show or hide Magento shipping methods based on whether Home Delivery or Pickup is selected, see the /docs/shipping-rate-filtering.

Create an after plugin on the collectRates method of the relevant shipping carrier model(s). You may need plugins for multiple carrier models depending on which rates you need to filter (e.g., Magento\OfflineShipping\Model\Carrier\Flatrate, Magento\Shipping\Model\Carrier\AbstractCarrierOnline, or specific third-party carrier modules).

In your afterCollectRates method:

  1. Determine whether the current quote represents a HubBox pickup selection (inspect the Quote or Quote Address object for a flag or specific data set by the HubBox module, or inspect the address fields directly).
  2. Iterate through the rates in the $result object using $result->getAllRates().
  3. If HubBox pickup is selected, remove rates intended only for home delivery.
  4. If Home Delivery is selected, remove rates intended only for HubBox pickup.
  5. Return the modified $result.
<?php
namespace Vendor\Module\Plugin\Quote\Address\RateResult;

use Magento\Checkout\Model\Session as CheckoutSession;

class CarrierPlugin
{
    protected $checkoutSession;

    public function __construct(CheckoutSession $checkoutSession)
    {
        $this->checkoutSession = $checkoutSession;
    }

    public function afterCollectRates(
        \Magento\Shipping\Model\Carrier\AbstractCarrier $subject,
        \Magento\Shipping\Model\Rate\Result $result
    ) {
        $quote = $this->checkoutSession->getQuote();

        // Replace with actual logic to determine if HubBox pickup is selected
        $isHubBoxSelected = false;

        $rates = $result->getAllRates();
        $result->reset();

        foreach ($rates as $rate) {
            $isHomeRate    = ($rate->getMethodCode() === 'home_delivery_standard');
            $isPickupRate  = ($rate->getMethodCode() === 'hubbox_pickup');

            if ($isHubBoxSelected && $isPickupRate) {
                $result->append($rate);
            } elseif (!$isHubBoxSelected && $isHomeRate) {
                $result->append($rate);
            }
            // Add logic for additional rate codes as required
        }

        return $result;
    }
}

The implementation above is illustrative. The actual logic depends heavily on your specific rate method codes and how the HubBox module signals pickup selection status in your checkout. Declare the plugin in your module's di.xml.

Data Storage: hbcc_order Table

The HubBox module creates a custom database table named hbcc_order. This table stores HubBox-specific data for each relevant Magento order, linked to the corresponding Magento order_id. The table includes the following fields:

Column Description
entity_id Unique identifier for the database record.
collect_point_id The HubBox collect point identifier (e.g., U18467140 for a UPS Access Point).
collect_point_type The carrier or network type (e.g., ups, mondialrelay).
magento_quote_id The corresponding Magento quote/order ID, linking the HubBox data to the order.
created_at Timestamp when the record was created.
updated_at Timestamp when the record was last updated.

This data is useful for:

!cdn.hub-box.com/console/magento/magento-orders-table.png

!cdn.hub-box.com/console/magento/magento-order-example.png

When a HubBox pickup order is placed, the shipping address in the Magento order will reflect the collect point address. The hbcc_order table provides the structured HubBox data (collect point ID, type, and network) linked to that order for downstream processing.

Testing

All testing should be performed on a staging or development environment that mirrors your production setup before going live.

In Stores > Configuration > HubBox > Settings, set Environment to Sandbox and ensure the API credentials and Config ID are correct for the sandbox environment.

Verification Checklist

For the full HubBox UAT guide, refer to the /docs/testing.

Going Live

Complete Staging Testing

Ensure thorough testing on your staging environment is complete and all checklist items are passed.

Deploy to Production

Deploy the tested codebase (including the enabled HubBox module) to your production environment.

Run Deployment Commands

Run the necessary Magento deployment commands on production:

bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy en_US fr_FR -f
bin/magento cache:flush

Update Production Configuration

In the production Magento Admin Panel (Stores > Configuration > HubBox > Settings), change Environment to Production and verify all API credentials and the configId are correct for the live environment.

Save and Flush

Save the configuration and flush caches:

bin/magento cache:flush

Smoke Test

Perform final smoke tests on the live site before announcing the feature to customers.

Troubleshooting

Log Files

The HubBox module writes errors to a dedicated log file:

var/log/hubbox.log

If something fails during execution in the Collection or Delivery controllers, the error is logged here. In the browser, a red 500 status will appear in the Network tab of Developer Tools, but no message is rendered to the customer.

When the collect point is selected or unselected, a request is made to the Magento backend to save the quote. If debug mode is enabled in the browser, a console message will be displayed in Developer Tools.

Common Issues

Module version not found during `composer require`

This typically indicates a version mismatch. Confirm the exact version number with your HubBox Integrations Manager and ensure your Composer credentials are correct for composer.developers.hub-box.com.

Authentication errors (401 Unauthorized) in the HubBox API HubBox UI not appearing at checkout Shipping address not populating after pickup selection Custom CSS not applying

FAQs

Can I use the HubBox Extension with Hyvä or Amasty One Step Checkout?

No. The HubBox Extension is designed for the standard Magento 2 checkout. Custom checkout applications such as Hyvä and Amasty One Step Checkout can conflict with the module's Layout XML and JavaScript. In these cases, use the HubBox Tag or SDK integration instead. Contact your HubBox Integrations Manager to discuss the best approach for your setup.

How do I check which version of the HubBox module is installed?

Run the following command from your Magento project root:

composer show hub-box/click-and-collect

This will display the installed version. You can also check composer.lock for the exact version pinned in your project.

How do I update the HubBox module to a new version?

Run the composer require command with the new version number provided by your HubBox Integrations Manager:

COMPOSER_MEMORY_LIMIT=-1 composer require hub-box/click-and-collect:x.y.z

Then run the standard Magento deployment steps:

bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy en_US fr_FR -f
bin/magento cache:flush

Always test the update on a staging environment before deploying to production.

What is the `hbcc_order` table and what data does it store?

The hbcc_order table is a custom database table added by the HubBox module. It stores HubBox-specific data for each pickup order, including:

This data is used for reporting, identifying pickup orders in backend processes, and passing collect point information to fulfillment systems. It does not store personally identifiable information.

Where should I make customisations — in the HubBox module files or in a custom module?

Always make customisations in a custom Magento module that declares a dependency on HubBox_ClickAndCollect. Never modify the HubBox module files directly — any changes will be overwritten when the module is updated. This applies to Layout XML, CSS, PHP plugins, and DI preferences.

How do I implement product eligibility filtering?

There are two approaches:

  1. Plugin on ConfigProvider (simpler) — create an after plugin on HubBox\ClickAndCollect\Model\Ui\ConfigProvider::getConfig() and modify the isClickAndCollectable value in the result array based on your cart inspection logic.

  2. DI Preference for WidgetConfigInterface (more involved) — define a preference in di.xml to replace the default WidgetConfigInterface implementation with your own custom class.

See the Advanced Customisation section above for full code examples, and the /docs/product-eligibility for the full strategy guide.

How do I implement shipping rate filtering?

Create an after plugin on the collectRates method of the relevant shipping carrier model(s). In your plugin, inspect the quote to determine whether HubBox pickup is selected, then filter the $result object to show or hide rates accordingly.

See the Advanced Customisation section above for a code example, and the /docs/shipping-rate-filtering for the full implementation guide.

What should I provide when contacting HubBox support?

When raising a support request, provide the following to help the team diagnose the issue quickly: