Concepts

This page explains how PackGuard thinks: how the empty space ratio is calculated, how boxes are ranked, what the three thresholds mean, and where the Packaging Efficiency Report gets its numbers. Nothing here is required to use the plugin — but it makes the numbers on the dashboard and the order card predictable instead of magic.

The empty space ratio

For every order, PackGuard computes one number per box in your catalog:

empty space ratio = 1 − (product volume / box internal volume)

• Box internal volume comes from the box's internal dimensions (L × W × H in mm) in your catalog.
• Product volume is the sum of every line item's own L × W × H, multiplied by its quantity. Padding is not part of it.

A ratio of 33% means a third of the box would be air. Lower is better.

Effective volume and padding

The starting point is Shopware's built-in product dimension fields (length, width, height — millimetres, set per product or per variant). PackGuard never asks you to enter dimensions a second time.

Packaging profiles can transform those raw dimensions before the volume is summed:

• A padding constraint grows each side by a configured amount — a fragile product measuring 200 mm with 20 mm padding per side occupies 240 mm of box space.
• Padding always counts as empty space in the ratio. PPWR Article 24 treats space filled by filling material (paper, air cushions, bubble wrap, foam) as empty space, so PackGuard does the same: padding makes the product need a bigger box, and the extra room shows up as empty space.
• Products with missing or zero dimensions are skipped and counted — the order card and the dashboard both surface a "products missing dimensions" warning, because a skipped product makes every suggestion optimistic.

How the box suggestion ranks your catalog

For each active box in the catalog, PackGuard checks whether the order fits (volume) and whether the packaging profiles of the ordered products allow the box at all — an insulated constraint excludes non-insulated boxes, an allowed box types constraint excludes everything outside its list, an orientation constraint locks rotation. Excluded boxes are listed with the reason ("too small", constraint name) behind the boxes excluded toggle on the order card.

The boxes that survive are ranked by ascending empty space ratio — the top row, marked Best, is the smallest fitting box. Cost per box is displayed so a packer can see when the second-best box is meaningfully cheaper.

The three thresholds

One global set of three percentages (plugin configuration) drives everything:

Threshold	Default	Effect
Tracking	30%	The record floor. Orders whose ratio is below this are not persisted at all — dashboards stay focused on packaging worth reviewing.
Warning	50%	At or above: the order's packaging record is flagged as a warning (amber). Selection is allowed after a confirmation.
Block	70%	At or above: the record is a violation (red) and box selection is rejected. Only a documented override can proceed.

The defaults are set with the law in mind: PPWR Article 24 sets a 50% limit that applies from January 2030 at the earliest, so the defaults let you see trouble (warnings at 50%) years before it matters. All three are sliders in the configuration — adjusting them requires no code changes and applies immediately to new calculations.

Overrides and the audit trail

A blocked selection is not a dead end — real warehouses have gift wrap requests and one-off bulk orders. The override flow requires a written reason, which is written to the system log together with the user, order, box, and the ratio that was exceeded. The record stays honest: the dashboard counts the order as a violation, and the log carries the justification.

Where the Packaging Efficiency Report numbers come from

The report is generated per box type. It combines:

• the box's specifications from your catalog (dimensions, material, volume),
• the average empty space ratio across all recorded orders that used this box — real operational data, not an estimate,
• the configured block threshold as the benchmark, and
• your company name from the plugin configuration.

Because the average comes from recorded orders, a box that has never been used on an order produces a report without meaningful data — use boxes on real orders first.

Vocabulary

Term	Meaning
Box	One packaging type in your catalog (a carton size, a polybag, a padded envelope).
Packaging profile	A named, reusable set of packing rules assigned to products.
Constraint	One rule inside a profile: padding, orientation, insulation requirement, or an allow-list of box types.
Packaging record	The per-order row PackGuard stores (box, ratio, status) — the raw material of the dashboard and the Packaging Efficiency Reports.
Empty space ratio	The percentage of a box's internal volume not occupied by (effective) product volume.
Record floor	The tracking threshold's effect: efficient orders below it are not stored.