Box Builder (Mix & Match) — Complete Guide
Install, configure and use the "Mix & Match" box builder: product/category sources, 4 pricing models, categorical slots, pre-composed templates, surprise, save & share, gamification and analytics for PrestaShop 8 and 9.
Overview
The Box Builder (Mix & Match) module (dfboxbuilder) adds a page where your customers compose their own box from a selection of products you curate. They pick items from a grid, follow a progress bar, watch the price update live, then add the complete box to the cart in one click. Ideal for gourmet boxes, beauty boxes, hampers, “buy 3” packs, discovery subscriptions and more.
You create as many boxes as you want, each with its own products, its own rules (minimum / maximum items) and its own pricing model. A single catalogue can feed several very different boxes.
Compatibility
- PrestaShop 1.7.6 to 8.x and 9.x
- PHP 7.4 to 8.x
- Single shop and multistore
- 5 languages: FR, EN, ES, DE, IT (fully translated, no fallback)
- Classic theme and custom themes (builder in native JavaScript, no jQuery dependency)
- No dependencies (no Composer, no framework)
Installation
- In the back office, open Modules > Module Manager.
- Click Upload a module and select the
dfboxbuilder.zipfile. - Once installed, open the Box Builder tab added to the menu to create your first box.
On installation, the module creates its tables, registers its hooks (displayHeader, actionFrontControllerSetMedia, displayHome and actionValidateOrder) and adds a Box Builder admin tab. On the first save of a box, a hidden container product is generated automatically: it carries the box line in the cart and is not visible in the catalogue.
Configuring a box
The box edit form is organised into five tabs.
General tab
- Name, description, button label: translatable in all 5 languages.
- Min / max items: bounds of the composition. The maximum drives the progress bar target.
- Allow duplicates and max units per item: allow (or not) adding the same product several times, with a per-product cap.
- Hide out-of-stock products: removes unavailable products from the grid (respecting each product’s out-of-stock setting).
- Enable “Surprise me” and Enable save & share: show or hide these customer actions.
- Active: publishes the box or not.
Pricing tab
Four pricing models are available:
- Fixed price: a single price for the box, whatever its contents.
- Volume tiers: the price changes with the number of items (e.g. 3 items = €25, 6 items = €45). You define as many “from X items” tiers as needed.
- Sum of products with discount: the price is the sum of the products in the box, minus a discount percentage.
- Price per slot: each slot contributes a fixed unit price; the total depends on the filled slots.
This tab also drives gamification: free gift when the box is complete (choose the gift product, added free to the cart) and free shipping on completion.
The base / fixed price is entered tax excluded. The module then applies the container product’s tax and shows the tax-included price to the customer.
Composition tab (sources & slots)
You define the eligible products that will appear in the builder grid, via two source types:
- Products: added one by one through an autocomplete search.
- Categories: every active product in the category becomes eligible.
The Use categorical slots option enables a “step-based” composition. Each slot has its own name, its min / max bounds, an optional slot price and its own sources. You can require, for example, “2 mains + 3 sides + 1 dessert”. Without slots, the customer picks freely from the global list.
Templates tab (pre-composed boxes)
You offer ready-made boxes the customer picks in one click, then tweaks at will. Each template has a name, a description and a product list (added through autocomplete search). Ideal to guide the undecided customer or highlight a best-selling assortment.
Constraints tab
You declare incompatible product pairs that cannot appear together in the same box. The builder then prevents their joint selection and the server validation rejects it.
Customer-facing usage
The interactive builder
The composition page shows the product grid (image, name, “low stock” warning where relevant) and a sticky summary panel: progress bar, list of selected items, live computed price (optimised AJAX call) and validation messages. The add-to-cart button only activates once the composition meets every rule.
Categorical slots
When slots are enabled, tabs guide the customer from one slot to the next, each showing its counter (for example “Mains 2/3”) and its own product selection.
Surprise me
The Surprise me button automatically fills the box with eligible products, respecting the maximum items, each slot’s bounds and the incompatibilities. The customer can then adjust the suggested selection.
Save & share
The customer can save their composition and get a share link. Anyone opening that link finds the box pre-filled, ready to adjust and order.
Add to cart and order
On add to cart, the composition is stored as a customization of the line (and stays visible in the cart and on the order), and the computed box price is applied. If gamification is enabled, the gift is added free. On order validation, the module decrements the stock of each component product in the box and records the sale for analytics.
Analytics (back office)
The Analytics tab aggregates ordered boxes: revenue, number of orders, average items per box, performance per box and most popular combinations. Everything you need to identify your winning assortments and refine your sources.
Home page display (optional)
An optional home block lists your active boxes with a direct link to their builder. A box page is also reachable directly via its address: index.php?fc=module&module=dfboxbuilder&controller=builder&id_dfbox=ID. You can link to it from your menu, a CMS page or a banner.
How it works (technical)
For each box, a hidden container product (visibility “nowhere”, not browsable) carries the line in the cart. The box price is applied through a cart-scoped specific price, so the container’s catalogue price is never shown. The composition is stored as a customization, and the components’ stock is decremented on order validation.
In the Sum with discount model, if a customer adds two boxes of the same box definition with differently priced compositions, the last computed price applies to both lines (the specific price is carried by the container product). With fixed, tiered or per-slot pricing at an equal item count, there is no impact.
Deleting a box does not automatically delete its hidden container product (v1). If you delete a test box, you can remove the associated container product manually from the catalogue.
FAQ and troubleshooting
The builder does not display or the buttons do not respond
Clear the PrestaShop cache (Advanced Parameters > Performance) and, while testing, disable file combination/compression (CCC). Make sure the box is active and has at least one product source.
The grid is empty
Check that the sources (products or categories) contain active products for the current shop. If “Hide out-of-stock products” is enabled, unavailable products do not appear.
The displayed price is not what I expected
Check the chosen pricing model: fixed price ignores the contents, tiers depend on the number of items, sum with discount depends on the products’ prices, and price per slot depends on the filled slots. The base price is entered tax excluded.
Component stock is not decremented
The decrement happens on order validation (hook actionValidateOrder), not on add to cart. Check that the order reaches a valid state.
Can I require a precise structure (by categories)?
Yes: enable slots and define a minimum / maximum and its sources for each. You get a guided composition such as “2 + 3 + 1”.
Is it compatible with PrestaShop 9?
Yes. The module is compatible with PrestaShop 8 and 9, in multistore and multilingual setups (FR, EN, ES, DE, IT).