# Box Builder (Mix & Match) — Complete Guide

> 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…

- Page: <https://www.datafirefly.com/en/documentation/dfboxbuilder/>
- Language: en
- Last updated: 2026-06-25
- Other languages: [fr](https://www.datafirefly.com/documentation/dfboxbuilder/index.md), [es](https://www.datafirefly.com/es/documentation/dfboxbuilder/index.md), [de](https://www.datafirefly.com/de/documentation/dfboxbuilder/index.md), [it](https://www.datafirefly.com/it/documentation/dfboxbuilder/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfboxbuilder/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfboxbuilder/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfboxbuilder/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

## 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

1. In the back office, open **Modules > Module Manager**.
2. Click **Upload a module** and select the `dfboxbuilder.zip` file.
3. 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).