Box Builder (Mix & Match): complete guide
Install, configure and run Box Builder on PrestaShop 8 and 9: boxes filled by item count or by weight, slots as steps, 5 pricing models including price per weight, gift options, availability, catalog display, editing from the cart, stock and analytics.
Overview
Box Builder (Mix & Match) (dfboxbuilder) adds a page where your customers build their own box from the products you select. They pick items in a grid, follow a progress bar, see the box price and the savings update, then add the box to the cart. The box is filled by number of items or by weight. Each box is one cart line with its own price; its contents stay readable in the cart, on the order and on the invoice.
Create as many boxes as you need, each with its own products, rules, pricing model and sale period. The same catalog can feed very different boxes (aperitif box, Christmas box, chocolate box sold by weight, discovery pack…).
Compatibility
- PrestaShop 8.x and 9.x
- PHP 7.4 to 8.x
- Single shop and multistore
- Interface in 5 languages: FR, EN, ES, DE, IT
- Classic, Hummingbird and custom themes (builder in plain JavaScript, no jQuery)
- No dependencies (no Composer, no framework)
Installation and update
- In the back office, open Modules > Module Manager.
- Click Upload a module and select
dfboxbuilder.zip. - Open the Box Builder tab added to the menu to create your first box.
To update, upload the new ZIP the same way: the upgrade scripts run automatically (new columns, new hooks, clean URLs generated from the box names). Existing boxes stay filled by number of items.
When a box is saved for the first time, the module creates a technical product that carries the box in the cart. It is hidden by default; you can show it in your categories (see Catalog display). Its product page always redirects to the builder. Deleting a box also deletes this product.
Module settings
The Settings panel above the box list has three options:
- Show the boxes on the home page: a “Build your own box” block on the
displayHomehook. - Accent color: color of the progress bar, step tabs and highlights. Enter the main color of your theme (for example
#8a5a2b); leave empty for the default blue. The text color on top of it is chosen automatically for readability. - After adding a box to the cart: go to the cart page (default) or stay on the builder. When staying, the theme’s cart block is refreshed and opens its confirmation window, then the customer can compose another box.
In the box list, the menu of each row offers Open the builder page and Duplicate. The copy takes the prices, degressive rates, slots, sources, templates, constraints and groups; it is created inactive. For a box filled by weight, the Min and Max columns show the weights.
Creating a box
The box form has six tabs.
General
- Name, description, button label: per language.
- Friendly URL: per language, generated from the name when left empty. With PrestaShop friendly URLs enabled, the box page address is
/box/ID-friendly-url. - Fill the box by: Number of items (default) or Weight (see Boxes by weight).
- Min / max items (filled by number of items): limits of the composition (0 = no maximum).
- Minimum / maximum weight (filled by weight): in the shop weight unit; 0 = no maximum, the same value for an exact weight.
- Allow the same item several times and max units per item.
- Hide out-of-stock products: otherwise they stay visible but cannot be added.
- Enable “Surprise me”, Enable save & share, Active.
Availability
- Available from / until: sale period. Before the start date, the box page shows “This box will be available from …”; after the end date, the box is removed from the carts that still contain it.
- Limited stock (boxes): maximum number of boxes sold across all shops, cancelled orders excluded (0 = unlimited). The form shows how many are sold and left; the box page shows “Limited edition: N left”.
- Show in the catalog: nowhere (default), categories and search, categories only or search only, with the categories to list the box in.
- Customer groups: no group checked = everyone. Otherwise only the checked groups see and order the box.
- Suggest the box on product pages: adds “Compose a box with this product” on the page of each product the box contains.
Pricing
All prices are entered tax excluded, in the default currency. The box has its own tax rule, applied in the cart according to the customer’s address.
- Fixed price: one price whatever the contents.
- Volume tiers: the price depends on the number of items (e.g. from 3 items: 25, from 6: 45). The customer sees “Add 2 more item(s) and your box drops to …”.
- Sum of products with discount: sum of the item prices minus a percentage. Item prices are then shown in the grid.
- Price per slot: each slot has a price per item (requires slots).
- Price per weight: total weight of the items times a price per weight unit (per kg when the shop uses kg). Optional degressive rates change this price from a given box weight, and the whole box is then charged at the new rate: with 30 per kg, then 26 per kg from 1 kg, a 1.05 kg box costs 27.30. The customer sees the current price per kg and “Add 100 g more and the price drops to 26.00 / kg”. This model also works with boxes filled by number of items.
Show the savings compares the box price with the price of the items bought separately, at the current prices of your catalog: “Instead of 34.00: you save 5.20 (-15 %)”.
Rewards when the box is complete: free product and/or free shipping, granted by a secret-code, single-use cart rule that only applies while the box is in the cart. The reward label is shown in the builder.
Gift options:
- Gift message with a maximum length (1 to 500 characters). The message appears on the order in the back office and on the invoice.
- Gift wrap with its tax-excluded price (0 = free), added to the box price.
Composition
Eligible products come from products added one by one (search by name, reference or ID) or from whole categories. Each combination of a product becomes a selectable item, with its own stock, price and weight.
Use slots structures the box, for example “2 savoury + 1 sweet”. Each slot has a name per language, a minimum, a maximum, a price per item (per-slot model) and its own sources. On the front, slots become numbered steps.
Templates
Ready-made boxes the customer applies in one click and then adjusts. Template products must also be eligible in the box.
Constraints
Product pairs that cannot be in the same box. The builder prevents the combination and the server refuses it.
Boxes by weight
For a box of chocolates, a tea assortment or a bulk box, the customer fills the box up to a weight instead of counting items.
- General tab: Fill the box by = Weight, then a minimum and/or maximum weight. Example: 1 and 1.2 for a 1 to 1.2 kg box; 1 and 1 for exactly 1 kg. At least one of the two is required.
- Pricing tab: every pricing model works. Price per weight charges the box per kg, with degressive rates if needed; a fixed price suits a box sold at 35 whatever the assortment.
- Check the product weights: product page, Shipping tab, and the weight impact of each combination.
- Item weight: product weight + combination impact, the same value PrestaShop uses for shipping.
- Products without a weight: they are not offered in a box filled by weight, nor in a box priced per weight, and the product page block does not suggest the box on their page. The box form shows how many eligible products are affected.
- Builder: weight on each card, in the summary and in the quick view; counter and progress bar in g / kg (“800 g / 1.2 kg”, minimum marked); an item that would go over the maximum is disabled with “Does not fit in the weight left”; until the minimum is reached, the customer sees “Add 200 g more to complete your box”.
- Item rules: in weight mode, the box min / max items do not apply; slots, duplicates, max units per item and incompatibilities stay active.
- Surprise me fills the box within the weight window.
- Cart, order and invoice: the total weight is shown with the contents.
- Weight display: in grams below 1 kg, in kilograms above, with the decimal separator of the visitor’s language.
On the front
The builder
- Steps: with slots, numbered tabs show progress (“Savoury 2/3”). When a step is full, the builder moves on to the next one; a “Next” button appears as soon as a step is complete.
- Grid: above 8 products, a search field (accents ignored), a category filter and sorting by name or price appear. Clicking the image or name opens the quick view (image, description, link to the product page, Add button). Chosen items have a “-” button.
- Summary: counter with the rule (min. 5, max. 6, or in weight for a box filled by weight), progress bar with the minimum marked, visual preview of the box (one cell per item), price, savings, reward to unlock and gift options. What is still missing is shown in blue (“Add 2 more items…”); red is kept for real blocking issues.
- Mobile: two-column grid, templates and steps scrolling horizontally, sticky bar with the item count (or weight) and price that turns into “Add to cart” when the box is valid.
- Surprise me fills the box at random within the rules; Save & share creates a link that reloads the composition.
The price is always recomputed by the server from your catalog; a composition sent by the browser is checked again (products, combinations, slots, weight, stock) before it is added to the cart.
Editing a box from the cart
In the cart and the checkout, the box contents are followed by an Edit this box link. It reopens the builder with the contents and gift options; the button becomes “Update my box”. When confirmed, the box is replaced in place with the same quantity. In the Classic theme, the contents and the link are in the “Product customization” window of the cart line.
Display and acquisition
- Box page: “Open the builder page” link in the form and in the list. Address
/box/ID-friendly-urlwith friendly URLs, canonical tag, language switcher pointing to the URL of the chosen language. - Home page: block listing the available boxes (module setting).
- Widget: the block can be hooked on any display hook (Design > Positions) or placed in a template:
{widget name='dfboxbuilder'},{widget name='dfboxbuilder' id_dfbox=3}or{widget name='dfboxbuilder' title='Our boxes'}. - Product pages: “Compose a box with this product” block (up to 3 boxes), which opens the builder with the product already added.
- Catalog: with “Show in the catalog”, the box appears in the chosen categories and/or search results. The price shown is the “from” price (cheapest valid composition, tax and group discount included; for a box by weight, at the minimum weight or at the most favourable degressive rate); a fixed-price box shows its price. The link opens the builder and there is no add-to-cart button.
Layered navigation price filters and price sorting use the stored price of the technical product, which is 0: a visible box comes first when sorting by ascending price.
Only active boxes, within their sale period, not sold out and allowed for the visitor’s group appear in the blocks. Disabling a box also disables its technical product, which leaves the listings.
Cart, orders and stock
- Price per line: the box price is stored on its cart line; two boxes with different contents keep their own price. Customer group discounts apply; catalog price rules and quantity discounts do not apply to boxes.
- Component stock: checked when adding, across the whole cart (other boxes and products bought on their own). If the customer raises a box quantity beyond the stock, it is brought back to the maximum possible on the cart page, with a message.
- Orders: the stock of each component is taken when the order is validated, given back if the order moves to cancelled or payment error, and taken again if it is reactivated. An order created directly in error takes no stock.
- Unavailable boxes: a box that is deleted, disabled, ended, not started yet or kept for another group is removed from the cart on the cart and checkout pages, including after “Reorder”.
- Back office and invoice: contents (per slot), gift wrap, gift message and, for a box filled by weight, the total weight are shown on the order and the invoice.
Analytics
The Analytics button of the list opens a dashboard with a period selector (7, 30, 90 or 365 days):
- boxes ordered, revenue tax excluded, average items per box, conversion (orders / views);
- per box: builder views, added to cart, orders, boxes, add rate, conversion, revenue and average price;
- most chosen items and most ordered combinations.
Views and additions are counted from version 1.2.0, robots excluded; cancelled orders are excluded.
Google Analytics 4 tracking
After a box is added, the builder pushes an add_to_cart event to window.dataLayer (when Google Tag Manager or gtag.js is present) with currency, value and the item dfbox-ID. A dfbox:added event is also dispatched on document with the same data, for other tools.
FAQ and troubleshooting
Buttons do nothing or the page stays empty
Clear the PrestaShop cache (Advanced parameters > Performance) and, while testing, disable JS/CSS file combining. Check that the box is active, associated with the shop and has at least one product source.
The grid is empty
Sources must contain products that are active and available for order in the current shop. With “Hide out-of-stock products” enabled, products without stock are not shown. In a box filled by weight or priced per weight, products without a weight are not shown either.
A product does not appear in a box by weight
It has no weight. Enter it on the product page, Shipping tab, or in the weight impact of its combinations. The warning at the top of the box form tells you how many eligible products are affected.
A box shown in a category displays 0.00
Update the module to 1.2.1 or later: listings then show the “from” price.
The box does not appear for a customer
Check the sale dates, the limited stock and the customer groups in the Availability tab.
The “Edit this box” link does not appear
It is only shown in the cart and the checkout, for a box that is still available. In the Classic theme, open the customization window of the cart line.
Component stock does not go down
It is taken when the order is validated, not when adding to the cart, and only when stock management is enabled. A cancelled order gives the stock back.