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 Magento 2.4.7 (PHP 8.2/8.3), 2.4.8 (PHP 8.3/8.4), or 2.4.9 (PHP 8.5).
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 OAuth Client ID and Client Secret for the selected environment.
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.

If you are upgrading from the legacy hub-box/click-and-collect package, it cannot be installed alongside this module. Back up and record the existing configuration values and scopes, uninstall the legacy package, then follow the migration steps below after installing this package.

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 hubbox/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 Configuration

Log in to your Magento Admin Panel and navigate to Stores > Configuration > HubBox > Click & Collect.

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. All fields support Magento default, website, and store-view scopes; configure the intended scope and use normal Magento scope inheritance where appropriate. The module reads the effective values at store scope.

Configuration Field Scope Description Source Default
Module Version Default, Website, Store View Display-only version of the installed module. N/A —
Enabled Default, Website, Store View Set to Yes to enable the HubBox widget and related functionality on the frontend checkout for the selected scope. This controls HubBox checkout behaviour; it does not enable or disable the Magento module itself. N/A —
Design Default, Website, Store View Controls how the HubBox widget is displayed: Modal (overlay popup) or Embedded (inline on the page). N/A —
Environment Default, Website, Store View Select Sandbox for testing/development or Production for the live site. N/A —
Config ID Default, Website, Store View Your unique HubBox configId, which controls the widget's network availability, styling, and content. Provided by HubBox —
Client ID Default, Website, Store View OAuth client identifier for the selected environment. Provided by HubBox —
Client Secret Default, Website, Store View OAuth client secret for the selected environment. Magento stores this value using its encrypted configuration backend. Provided by HubBox —

Client ID, Client Secret, and Config ID are case-sensitive and must not contain leading or trailing spaces. Use separate OAuth credentials and Config IDs for Sandbox and Production — do not use Sandbox values on your live site. When the section is saved with Enabled set to Yes, the module validates the credentials and generates authentication; if validation fails, it disables the widget. You can obtain credentials from HubBox via Setup > Credentials Management in Console.

Save and Flush Cache

Click Save Config, then flush the Magento cache:

bin/magento cache:flush

Migrating from the Legacy Module

If migrating from the legacy hub-box extension, uninstall it before installing the currently supported hubbox/click-and-collect module. The two extensions must not be installed together. After installing hubbox/click-and-collect, migrate configuration from the legacy package if applicable. The migration preserves each value's scope and scope ID and does not remove the old configuration rows.

  1. Preview the migration:

    bin/magento hbcc:config:migrate --dry-run

  2. Run the migration:

    bin/magento hbcc:config:migrate

    Use --force (or -f) only when you intentionally want to overwrite destination values.

  3. Generate a new authentication token:

    bin/magento hbcc:generate-auth

The migration maps hbcc/general/enabled, hbcc/api/environment, hbcc/api/client_id, and hbcc/api/client_secret to the same paths, and maps hbcc/ui/design to hbcc/general/design and hbcc/ui/config_id to hbcc/api/config_id. Validate the effective configuration, authentication, checkout selection, and order sharing after migration.

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:

The module adds the launch-experience UI component as a shippingAddress jsLayout child in the checkout shipping step, using the launch-experience display area. This position can be changed by overriding or merging the checkout.root jsLayout arguments in a custom module's checkout_index_index.xml — 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/hubbox/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 active search container */
hb-core-search::part(container-active) {
  border-color: var(--primary-color);
}

/* Example: Style the title within the home delivery component */
hb-core-home::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

The launch experience is a jsLayout child under the checkout shipping address. To move it:

  1. In your custom module's checkout_index_index.xml, override or merge the checkout.root jsLayout arguments, then move, remove, or redefine the launch-experience child at the required UI-component path. Removing a conventional layout reference alone will not relocate it.
  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 getIsHbccOrder method:
const checkoutData = require("HubBox_ClickAndCollect/js/checkout-data");
const isHubBoxOrder = checkoutData.getIsHbccOrder();

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.

Implement product eligibility through the module's supported HubBox\ClickAndCollect\Api\CollectableInterface extension point. Create a custom implementation and configure a DI preference for the interface. Implement isCollectable() to inspect the active quote/cart according to your eligibility rules and return false for ineligible carts.

```php
<?php
namespace Vendor\Module\Model;

use HubBox\ClickAndCollect\Api\CollectableInterface;

class Collectable implements CollectableInterface
{
    public function isCollectable(): bool
    {
        // Inspect the active quote and apply your eligibility rules.
        return true;
    }
}

Configure the preference in your module's etc/di.xml:

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

Shipping Rate Filtering

The HubBox module does not provide a pickup shipping method or filter Magento shipping methods. If your checkout presents Home Delivery and Pickup as separate choices before rates are displayed, implement the required availability and pricing rules in your own carrier/rate logic.

Use the following approach:

  1. Identify the carrier methods that are specifically intended for pickup or home delivery.
  2. In the carrier's rate-calculation path, obtain the current Magento quote ID and query HubBox\ClickAndCollect\Api\HbccQuoteRepositoryInterface (for example, with tryGetByMagentoQuoteId($quoteId, $hbccQuote)).
  3. Treat a matching hbcc_quote record with a collect-point ID as pickup selected. Use its collect_point_network and collect_point_type when different carriers or networks need different rates.
  4. Apply the retailer's explicit allow-list to the rates returned by that carrier. Preserve unrelated rates and return the concrete carrier's expected result type; do not reset and rebuild the entire global rate result.
  5. Trigger Magento's shipping-rate recollection after the customer changes between Home Delivery and Pickup, and test both selection and unselection paths. A stale rate cache must not leave pickup rates visible for home delivery, or vice versa.

The exact plugin or service depends on the carrier implementation. A typical decision flow is:

quoteId = current quote ID
pickup = hbccQuoteRepository.tryGetByMagentoQuoteId(quoteId)

if pickup exists and has a collect point:
    retain only explicitly configured pickup methods
    optionally match pickup.collect_point_network to the carrier/network
else:
    retain only explicitly configured home-delivery methods

Do not inspect or parse the shipping address to determine pickup state. The extension may add carrier-specific routing data to the street field at checkout submission for supported DPD, UPS, and GB DHL networks; use hbcc_quote instead. See /docs/shipping-rate-filtering for platform-wide strategy guidance.

Data Storage

The HubBox module creates three custom database tables: hbcc_auth, hbcc_quote, and hbcc_order. The hbcc_quote table stores checkout selections, including magento_quote_id, collect_point_id, collect_point_network, and collect_point_type. The hbcc_auth table stores authentication tokens and expiry data.

The hbcc_order table is an internal order-sharing queue. It 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).
magento_order_id The corresponding Magento order identifier.
collect_point_network The collect point network.
collect_point_type The collect point type.
status Order-sharing status; new records default to pending.
attempt_count Number of sharing attempts; new records default to 0.
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

For pickup orders, the checkout shipping address is populated with collect-point details. At submission, the module also prepends carrier-specific routing data to the street field for supported DPD, UPS, and GB DHL networks. Use hbcc_order or hbcc_quote for the structured collect-point ID, network, and type rather than parsing the address. Order sharing is cron-driven through the hbcc cron group: authentication is generated every six hours, order sharing runs every ten minutes, and daily retention jobs remove old auth, order, and quote records. The module does not require Magento message queues or RabbitMQ.

Testing

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

In Stores > Configuration > HubBox > Click & Collect, set Environment to Sandbox and ensure the OAuth 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 > Click & Collect), change Environment to Production and verify the Client ID, Client Secret, and Config ID 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 hubbox/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 hubbox/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 are the `hbcc_quote` and `hbcc_order` tables and what data do they store?

The module uses hbcc_quote to store the checkout selection, including:

The hbcc_order table is an internal order-sharing queue. It stores:

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?

Implement product eligibility through HubBox\ClickAndCollect\Api\CollectableInterface. Create a custom implementation, configure a DI preference for the interface, and implement isCollectable() to inspect the active quote/cart according to your eligibility rules. Return false for ineligible carts.

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?

The HubBox module does not provide or filter Magento shipping methods. Implement availability and pricing in the retailer's carrier/rate logic. To determine whether a collect point is selected, query HubBox\ClickAndCollect\Api\HbccQuoteRepositoryInterface by Magento quote ID, for example with tryGetByMagentoQuoteId($quoteId, $hbccQuote). Filter only explicitly identified project carrier methods and preserve unrelated rates.

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: