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 Declaration of Conformity 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 − (occupied volume / box internal volume)

• Box internal volume comes from the box's internal dimensions (L × W × H in mm) in your catalog.
• Occupied volume is the sum of every line item's effective product volume, multiplied by its quantity.

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

Effective volume, padding, and the PPWR exemption

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 marked exempt from empty space implements the PPWR rule that protective filler for fragile goods does not count as void space: the padding volume is added to the occupied side of the formula, not the air side. Your empty space ratio does not get worse because a product legitimately needs bubble wrap.
• 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, maximum weight) 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 thresholds are deliberately stricter than the law today: PPWR Article 24 enforces a 50% limit from January 2030, so the defaults let you see trouble (warnings at 50%) years before it becomes a fine. 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 compliance story stays honest: the dashboard counts the order as a violation, and the log carries the justification for the audit.

Where the Declaration of Conformity numbers come from

The declaration (PPWR Article 11, mandatory from August 2026) 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 compliance criterion, 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 declaration without meaningful compliance 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 declarations.
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.