# TrolleyBox: Magento 2 Multi-Order Trolley Picking > Group orders into trolleys and boxes so warehouse pickers process multiple orders in a single efficient round. --- ## Overview TrolleyBox brings multi-order trolley picking to your Magento 2 admin. Instead of picking one order at a time, pickers load a trolley with labelled boxes, scan a picklist barcode, and pick items from every order on that trolley simultaneously. Each order is automatically assigned a trolley letter, a box number, and a full BoxTag (for example `A-2`). Packers then verify each box tag before dispatch, keeping fulfilment accurate even at high volume. ![TrolleyBox configuration overview](images/overview.png) This module helps you: - Set up multi-order trolley picking so warehouse staff process several orders per round - Generate BoxTag barcode labels and attach them to physical trolley boxes before scanning starts - Auto-assign incoming orders to picklists and route them to available pickers automatically - Print TrolleyBox picklist PDFs directly from the orders grid - individually or in batch - Connect picking data to PickPack packing sheets and ShipEasy shipping tags --- ## When to use this Use TrolleyBox when you want to: - Speed up picking by having staff service multiple orders per warehouse walk - Reduce missed items by scanning barcodes at every stage - pick, box, and pack - Let Magento assign orders to pickers automatically based on availability and order priority - Track which picklist, box, and trolley an order belongs to across your sales order grid - Generate a fresh set of BoxTag labels whenever you reconfigure trolley counts or box sizes --- ## Key capabilities - **Multi-order picking** - groups orders into picklists so one picker handles an entire trolley of boxes in a single pass - **BoxTag assignment** - every order receives a unique `{letter}-{number}` tag (e.g. `B-3`) stored on the order record - **Shelf-route optimisation** - sorts items across a picklist by a product attribute you choose, minimising warehouse travel - **Automated picklist assignment** - a cron job checks every minute for eligible orders and assigns them to available, recently-active pickers - **BoxTag label PDF** - generates a printable barcode sheet covering every trolley and box combination you configure - **TrolleyBox picklist PDF** - extends PickPack PDF templates with trolley-specific columns; prints from the orders grid - **Conflict detection** - the scan UI alerts pickers when a box tag belongs to a different picklist before any packing begins - **Daily counter reset** - packed picklists reset at midnight automatically so IDs stay manageable --- ## Installation TrolleyBox installs via Composer, then activates with a license key from your Moogento.com account. The whole flow takes about 5 minutes. > **Dependency note.** TrolleyBox requires **PicknScan** and **PickPack** to already be installed and enabled - install those first if you haven't already. ### Step 1: Get your Composer keys from Moogento.com 1. Sign in at **https://www.moogento.com** and open **My Plugins** in your account menu. 2. Find **TrolleyBox** in the list of plugins you own. 3. Generate (or reveal) the Composer access keys for that plugin - a **public key** and a **private key**. 4. **Add your install domain to the key.** Each Composer key is tied to a specific domain - if you're installing on `yourstore.com`, add `yourstore.com` to the key's allowed domains. The Composer download will be rejected on any other domain. If you run staging and production on different domains, add both - separate keys per environment are fine too. ### Step 2: Install the module with Composer From your Magento 2 root directory: ``` composer require moogento/module-trolleybox ``` When Composer asks for credentials, paste the **public key** as the username and the **private key** as the password. They'll be cached in `~/.composer/auth.json` for future runs. ### Step 3: Enable the module in Magento ``` php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento cache:clean ``` If you run `php bin/magento module:status Moogento_Trolleybox` you should see it listed as enabled. ### Step 4: Add your license key in the Moogento admin 1. Still on **https://www.moogento.com > My Plugins**, copy the **license key** for TrolleyBox (separate from the Composer keys you used above). 2. In your Magento admin, go to **Stores > Configuration > Moogento > Licenses**. 3. Find the row for **TrolleyBox** and paste the license key. 4. Click **Save Config**, then run `php bin/magento cache:clean` once. The license validates within a few seconds. You should see the module's status flip to active. If it stays inactive, double-check the domain on the license matches where you've installed - domain mismatch is the most common cause. --- ## Setup overview Most setup happens in: Stores > Configuration > Moogento > TrolleyBox You'll mainly work with: - **General** - enable the module, set boxes per trolley, choose the shelf attribute for pick-route sorting - **Customise: Orders Page** - show or hide the TrolleyBox button on the orders grid - **Customise: Scanning Pages** - control the multi-box clicker interface during picking - **Automate: Assign Orders** - configure automatic picklist creation and user assignment - **Connect: PickPack** - link TrolleyBox picklist PDFs to a PickPack template - **Connect: ShipEasy** - update ShipEasy tags when a picklist is completed - **Generate: BoxTag Labels** - configure and print the BoxTag barcode sheet - **Reset: Picklist ID Counter** - manually reset the picklist counter or schedule a midnight auto-reset --- ## Common setups ### Enable TrolleyBox and set your trolley size The first thing to configure is how many boxes fit on each trolley. This number drives how many orders are grouped into each picklist. #### How to set it up 1. Go to: Stores > Configuration > Moogento > TrolleyBox > General 2. Set: - **Enable** = Yes - **General: Number of boxes in each trolley** = your physical trolley capacity (e.g. `4`) - **General: 'Shelf' attribute** = the product attribute that identifies warehouse shelf location (e.g. `shelf`) 3. Save config ![General configuration group](images/config-general.png) #### Notes - The shelf attribute is used to sort items across all orders in the same trolley - pick items from the same shelf section together to reduce warehouse walking. - If you have no shelf attribute set up yet, you can leave it blank and add it later. Picking will still work; items just won't be sorted by location. --- ### Show the TrolleyBox button on the orders grid and enable auto-assignment Pickers access TrolleyBox mode from the orders grid via a dedicated button. You can also enable a slider within that button that triggers automatic picklist creation every minute. #### How to set it up 1. Go to: Stores > Configuration > Moogento > TrolleyBox > Customise: Orders Page 2. Set: - **Enable Button: TrolleyBox** = Yes 3. Save config, then return to: Stores > Configuration > Moogento > TrolleyBox > Automate: Assign Orders → to TrolleyBox Picklists → to Users 4. Set: - **Add in TrolleyBox Button: Auto-assign switch** = Yes - **Set Switch to: Enabled** = Yes (to start auto-assignment immediately without a picker having to toggle the switch manually) 5. Save config ![Orders Page configuration group](images/config-orders-page.png) #### Notes - Auto-assignment runs every minute via cron. It picks up orders that are in Processing status and not yet assigned to a user, then assigns them to any picker who has been active in the last two hours and is marked as Auto-Assignable (TrolleyBox) in the PicknScan user table. - If two admins control the slider switch - one via config and one physically toggling it in the UI - the last write wins. Coordinate with your team to avoid unexpected state changes. --- ### Generate and print BoxTag labels Before pickers can scan boxes, you need a printed set of BoxTag labels - one per box position across all your trolleys. Configure the count and size here, then generate the PDF. #### How to set it up 1. Go to: Stores > Configuration > Moogento > TrolleyBox > Generate: BoxTag Labels 2. Set: - **Trolleys: How many are in use?** = number of trolleys (e.g. `3`) - **Boxes: How many in each trolley?** = boxes per trolley for label generation (e.g. `4`) - **Page: Size** = `A4` (or `custom` if you use non-standard label stock) - If custom: **Page: Width (mm)** and **Page: Height (mm)** 3. Save config 4. Click **Generate: BoxTag labels** to download the barcode PDF 5. Print and stick a label on each physical box before your next picking session ![BoxTag Labels configuration group](images/config-barcode-generation.png) #### Notes - The label set covers every combination - for 3 trolleys × 4 boxes you get labels A-1 through A-4, B-1 through B-4, C-1 through C-4. - The **Boxes: How many in each trolley?** field here is separate from **General: Number of boxes in each trolley**. The General setting drives picklist grouping logic; this one only controls how many labels to generate. - Save config before clicking Generate or the PDF will reflect the previously saved values. --- ### Connect TrolleyBox to PickPack for picklist PDFs TrolleyBox adds a `trolleybox_picklist` PDF type to PickPack. Assign a template so your picklist PDFs carry trolley-specific columns (BoxTag, qty per box, trolley letter). #### How to set it up 1. Go to: Stores > Configuration > Moogento > TrolleyBox > Connect: PickPack 2. Set: - **Assign: PDF Template** = `TrolleyBox Picklist` (or any custom template you've built in PickPack) - **Add an order comment when creating this PDF?** = Yes (recommended - adds an order history entry for traceability) - **Also Print: Order-combined Picklist PDF?** = Yes if you also want a combined single-document picklist per trolley - **Also Print: 'Packing Sheet' or 'Invoice' PDFs?** = set to whichever document your packers need at the same time 3. Save config ![PickPack connection group](images/config-pickpack.png) #### Notes - The TrolleyBox picklist PDF template is installed automatically on `setup:upgrade` for new installs. If the template is already configured, the data patch skips it. - PickPack integration requires Growth plan or higher. --- ## Features reference ### Customise: Scanning Pages Controls how the PicknScan scan UI behaves during a TrolleyBox picking session. - **What it does:** When **Pick: Show multi-box clicker?** is enabled, the scan screen shows a per-box breakdown whenever the same SKU appears in more than one box on the same trolley. The picker scans the product once, then taps each box tile to confirm they've placed the right quantity in each box. - **When to use it:** Enable this when you routinely have the same product in multiple boxes per trolley. Disable it for simpler operations where each SKU stays in one box. - Config path: `moogento_trolleybox/scanning_page/pick_show_multi_boxes` --- ### Connect: ShipEasy Updates a ShipEasy order tag when a TrolleyBox picklist event occurs (for example, when a picklist is packed and dispatched). - **What it does:** Choose which ShipEasy tag to update (**Update: Which ShipEasy tag?**) and then choose the specific flag or value within that tag. Supports flags, calls, and printed tag types. - **When to use it:** When your post-picking workflow relies on ShipEasy tags to trigger label printing or carrier handoff. Requires Pro plan. - Config path: `moogento_trolleybox/shipeasy/szy_tag_to_update` and related sub-fields --- ### Reset: Picklist ID Counter Resets the sequential picklist ID counter so IDs start from 1 again. - **What it does:** Each picklist gets an incrementing numeric ID during the day. The **Picklist ID: Reset now** button resets that counter immediately. **Picklist ID: Auto reset at midnight?** (default: Yes) runs the same reset automatically via cron at 00:05 each night for fully packed picklists. - **When to use it:** Use the manual reset button if you need to re-start IDs mid-day (e.g. after a test run or system migration). Leave the auto-reset enabled for routine daily operations. - Config path: `moogento_trolleybox/reset_counter/reset_btn` (button), `moogento_trolleybox/reset_counter/auto_reset_packed_picklist` --- ## Advanced configuration ### Auto-assignment priority matching #### What it does When auto-assignment is active, TrolleyBox groups orders in the pick pool by their **OrderTag: Priority** value before creating picklists. It then matches each priority group to a picker who has been configured (in the PicknScan user table) with an **AA Order Priority** equal to or higher than the group's priority value. This means high-priority orders are always assigned to your most senior or most capable pickers first. #### Setup 1. In PicknScan config, open the **Assign: Users** table and set **Auto-Assignable** to `Yes (TrolleyBox)` for each eligible picker. 2. Optionally set an **AA Order Priority** level per picker. 3. In TrolleyBox config (Stores > Configuration > Moogento > TrolleyBox > Automate: Assign Orders), enable the auto-assign switch and set it to Enabled. 4. Ensure cron is running - the assignment job fires every minute. #### Notes - A picker is only eligible if they have logged in, or have PicknScan activity, within the previous two hours. - Auto-unassignment also runs on a cron (every 5 minutes) to release orders when a picker logs out or becomes unavailable. - When a picker logs out of the admin, TrolleyBox immediately releases their assigned orders back to the pool. --- ### Shelf-route optimisation #### What it does When a shelf attribute is configured, TrolleyBox sorts all items across every order in the same picklist by that attribute value before presenting them in the scan UI. Pickers walk the warehouse aisle by aisle rather than bouncing between locations, reducing pick time and errors. #### Setup 1. Create or identify a product attribute in your catalogue that stores a shelf or location code (e.g. `shelf`, `bin_location`). 2. Go to Stores > Configuration > Moogento > TrolleyBox > General and set **General: 'Shelf' attribute** to that attribute. 3. Save config. #### Notes - The attribute must be a standard dropdown or text product attribute visible at the admin level. - Orders with items spanning multiple shelf zones are still grouped into a single picklist - the sort determines the picking sequence within the trolley, not whether the order is included. --- ## Tips & best practices - Set the **General: Number of boxes in each trolley** to match your physical trolleys exactly. If the number drifts (e.g. you add a box to a trolley), update this setting and regenerate BoxTag labels before the next shift. - Print a full fresh set of BoxTag labels whenever you change trolley or box counts - old labels with mismatched codes cause scan conflicts. - Enable logging (`moogento_trolleybox/general/enable_log`) during initial setup and after any configuration change. Disable it in steady-state to reduce server I/O. - Let the **Picklist ID: Auto reset at midnight?** cron run rather than resetting manually - it only resets fully packed picklists, so no in-progress work is lost. - Keep the **Boxes: How many in each trolley?** field in the Generate: BoxTag Labels group in sync with the General setting. They serve different purposes but pickers get confused if the label set doesn't match actual trolley capacity. - Before relying on auto-assignment for a live shift, run a dry-run via CLI to confirm orders would be assigned correctly: `php bin/magento moogento:trolleybox --action=picklist:auto-assign --dry-run`. --- ## Troubleshooting ### TrolleyBox button does not appear on the orders grid Pickers cannot see the TrolleyBox button on the Sales > Orders page. - **Cause:** The button is disabled in configuration. - **Check:** Go to Stores > Configuration > Moogento > TrolleyBox > Customise: Orders Page and confirm **Enable Button: TrolleyBox** is set to Yes. - **Resolution:** Set it to Yes, save config, and run `php bin/magento cache:clean`. --- ### Orders are not being auto-assigned to pickers The pick pool fills up but no picklists are created automatically. - **Cause:** Either cron is not running, no pickers are marked as auto-assignable, or no pickers have been active in the past two hours. - **Check:** Confirm the `moogento_trolleybox/auto_assign/auto_assign_trolleybox_orders_to_users_slider_yn` and `*_value_yn` settings are both Yes. In PicknScan config, check the Assign: Users table for at least one picker with **Auto-Assignable: Yes (TrolleyBox)**. Check `var/log/moogento_trolleybox.log` for assignment logic entries. - **Resolution:** Enable the auto-assign switch, mark at least one active picker as auto-assignable, and verify the Magento cron schedule is running. --- ### BoxTag scan returns a conflict warning The scan UI shows a conflict modal when a picker scans a box. - **Cause:** The scanned BoxTag is already associated with a different picklist. This happens when box labels are reused across shifts without resetting, or when a label is misapplied to the wrong box. - **Check:** The conflict modal shows the conflicting picklist ID. Compare it against the current picklist the picker is working on. - **Resolution:** Use the correct box for this picklist, or reset the picklist ID counter and re-assign the box. If labels are being applied to wrong boxes, retrain staff or print a clearer labelling guide. --- ### Picklist PDFs do not include TrolleyBox columns PDFs printed from the orders grid show standard PickPack columns but no BoxTag, trolley letter, or qty-per-box data. - **Cause:** The PickPack PDF template is not set to the TrolleyBox picklist type, or no template has been assigned. - **Check:** Go to Stores > Configuration > Moogento > TrolleyBox > Connect: PickPack and confirm **Assign: PDF Template** is set to `TrolleyBox Picklist` (or a custom template that uses TrolleyBox columns). - **Resolution:** Select the correct template, save config, and re-print. --- ### Orders are not grouped by shelf location during picking Items appear in arbitrary order in the scan UI rather than sorted by warehouse aisle. - **Cause:** The **General: 'Shelf' attribute** setting is blank or set to an attribute that has no data on your products. - **Check:** Go to Stores > Configuration > Moogento > TrolleyBox > General and note the selected shelf attribute. Open a product in the catalogue and confirm that attribute has a populated value. - **Resolution:** Select an attribute that actually has warehouse location data on your products and save config. --- ## FAQs ## How do I start picking multiple orders at once with TrolleyBox? Enable TrolleyBox in Stores > Configuration > Moogento > TrolleyBox > General, set your box count, then show the TrolleyBox button on the orders grid via Customise: Orders Page. Pickers select orders (or use auto-assign), scan their trolley barcode, and pick items box by box - the scan UI guides them through each order in one pass. See [Common setups](#common-setups) for the step-by-step walkthrough. ## What is a BoxTag and how does it work? A BoxTag is a short code like `A-2` that identifies a specific box on a specific trolley (trolley A, box 2). TrolleyBox assigns a BoxTag to each order, and you print matching barcode labels to stick on your physical boxes. Pickers scan the label at the start of a picking session to confirm which trolley and box they're working on. ## How do I print BoxTag barcode labels? Go to Stores > Configuration > Moogento > TrolleyBox > Generate: BoxTag Labels, enter how many trolleys and boxes per trolley you use, choose your page size, save config, then click **Generate: BoxTag labels** to download the PDF. Print it and stick each label on the matching physical box before the next shift. ## How does automatic order assignment to pickers work? When the auto-assign switch is enabled, a cron job runs every minute and groups eligible Processing orders into picklists, then assigns each picklist to a picker who is marked as Auto-Assignable (TrolleyBox) in PicknScan and has been active in the past two hours. See [Advanced configuration](#advanced-configuration) for details on priority matching. Auto-assignment requires Growth plan or higher. ## Does TrolleyBox work with PickPack? Yes - TrolleyBox adds a `TrolleyBox Picklist` PDF type to PickPack so your picklist PDFs include trolley letter, BoxTag, and per-box quantity columns. Assign the template in Stores > Configuration > Moogento > TrolleyBox > Connect: PickPack. PickPack integration requires Growth plan or higher. See the [PickPack user guide](../pickpack) for PDF template setup. ## Does TrolleyBox work with ShipEasy? Yes - on the Pro plan, TrolleyBox can update a ShipEasy order tag (flags, calls, or printed status) when a picklist event occurs. Configure which tag and value to update in Stores > Configuration > Moogento > TrolleyBox > Connect: ShipEasy. **ShipEasy** - ShipEasy integration is available on Pro plan only. ## What happens when I disable TrolleyBox? Disabling the module (setting Enable to No) hides the TrolleyBox button from the orders grid and stops all auto-assignment cron jobs. Existing BoxTag and picklist data stored on orders is not deleted, and PicknScan continues to work normally in its standard (non-trolley) mode. ## Which plan do I need for TrolleyBox features? Basic multi-box picking and BoxTag assignment are available on all plans. Multi-order picklists, BoxTag PDFs, and PickPack integration require Growth plan or higher. ShipEasy integration and custom PDF templates require Pro plan. Check your current plan at Stores > Configuration > Moogento > Licenses or visit moogento.com to upgrade. ## Is TrolleyBox compatible with Hyvä, Luma, and Porto themes? TrolleyBox operates entirely within the Magento admin panel - it has no storefront component - so it is compatible with Hyvä, Luma, Porto, and any other frontend theme. Theme choice has no effect on TrolleyBox functionality. ## Why does my picklist ID reset to 1 unexpectedly? The **Picklist ID: Auto reset at midnight?** setting is enabled by default and resets IDs for fully packed picklists at 00:05 each night. If you also see mid-day resets, check whether another admin is clicking the **Picklist ID: Reset now** button manually in Stores > Configuration > Moogento > TrolleyBox > Reset: Picklist ID Counter. --- ## Related guides - [PickPack](../pickpack) - configure the PDF templates that TrolleyBox picklist PDFs are built on - **PicknScan** - the scan UI and user assignment system that TrolleyBox extends (guide not yet published) - **ShipEasy** - connect dispatch tags to TrolleyBox picklist events on Pro plan (guide not yet published) --- ## Need help? - moo@moogento.com - Include: - Magento version - Module name - What you're trying to do