STM Surcharge Max

Some products carry a fulfilment cost that the catalog price simply cannot express: pipes need to be cut to length, sheet metal needs to be sheared, glass needs edge-polishing, fabric needs hemming, parts need engraving or personalisation. The cost is real, recurring, and very often per-order rather than per-unit — but it does not belong in the product price (which would distort listings, comparisons and tier discounts) and it does not belong in the shipping rate (which is calculated by weight and destination, not by category or by SKU).

STM Surcharge Max is the surcharge engine that finally models this correctly. It surfaces the surcharge as its own clean line item in cart, checkout, order, invoice and credit memo — never silently bundled into the product price, never silently bundled into shipping.

Why STM Surcharge Max stands out

Most Marketplace surcharge extensions still operate one product at a time, or attach a flat amount to a category. STM Surcharge Max combines three capabilities that no other extension on the Marketplace bundles in one place:

1. Named, reusable surcharge rules — an unlimited catalogue of surcharges, each with its own cost, calculation mode, active flag and sort order. Rules live in their own admin grid and can be enabled, disabled and deleted in bulk.
2. Bulk-assign mass-action in the catalog product grid — pick the rule, tick the products, apply. Assign hundreds of SKUs in seconds without leaving the standard product grid.
3. A deterministic resolver chain that stacks per-product overrides, customer-group prices, quantity tiers and section defaults in a defined priority — so what the customer sees on the product detail page is always exactly what they pay in the cart.

Features

• Multi-Rule Engine — define an unlimited number of named, reusable surcharge rules, each with its own cost, calculation mode (per item or per order), active flag and sort order; rules are managed in their own admin grid under Catalog → STM Surcharge Rules with full CRUD plus mass-enable, mass-disable and mass-delete.
• Dedicated ACL resource STM_SurchargeMax::rules with separate sub-permissions for save, delete and bulk-assign — restrict rule management to specific admin roles.
• Bulk-assign mass-action in the standard Catalog → Products grid — select any number of products (column filters, search and select-all-across-pages all work), pick the rule from the chooser page and apply; rule binding is written in a single index-friendly pass via Magento's native attribute-update API, safe on huge catalogues, no row-by-row product save.
• "Clear (no rule)" option in the bulk-assign flow removes rule bindings from selected products in the same operation.
• Per-product Enable surcharge flag — marks an individual product as surcharge-eligible regardless of category, for one-off SKUs that do not belong to a surcharge category.
• Per-product Surcharge rule dropdown — bind the product directly to a named rule; the rule's cost beats customer-group, tier and section default.
• Per-product Surcharge amount override — explicit per-product cost that wins over rule, customer-group, tier and section default; perfect for premium SKUs that need a one-off rate.
• Quantity-based tier pricing (From Qty, To Qty, Surcharge Cost) that scales the cost with cart quantity; leave To Qty empty for an unbounded top tier.
• Customer-group pricing — per-group cost grid (for example B2B Wholesale at a discounted rate, Retail at the standard rate, Guest at a custom rate) that overrides default and tier pricing, with an optional per-group free threshold.
• Minimum surcharge amount — skip the surcharge entirely if the calculated value falls below the threshold ("skip small charges", not "raise to minimum").
• Maximum surcharge amount (cap) — cap the calculated surcharge at a configurable value so a large cart never blows up the surcharge.
• Free above cart subtotal — the surcharge drops to zero once the cart subtotal (excluding tax) reaches the threshold; classic "free above €500" pattern applied to the surcharge.
• Restrict by shipping country — multiselect of allowed shipping country ISO codes; apply the surcharge only to domestic orders, or only to specific countries.
• Product-page notice box — optional, fully styleable notice on every surcharge-eligible product detail page, with custom text, {{label}} and {{cost}} placeholders (currency- and locale-aware) and three independent hex colours for background, border and text; rendered server-side from a dedicated view-model that runs the same resolver as the cart, so the displayed amount always matches what the customer pays.
• End-to-end persistence — declarative schema columns on quote, sales_order, sales_invoice and sales_creditmemo with standard fieldset mappings, plus a safety-net observer that guarantees no silent data loss on partial invoices or partial refunds.
• Full storefront and admin coverage — surcharge displayed on cart, mini-cart, checkout summary, admin order view, admin invoice and credit-memo views, and on order confirmation, invoice and credit-memo email templates, out of the box.
• Tax-aware — the surcharge participates in tax calculation using the relevant product tax class context; VAT is computed and displayed consistently with the rest of the order, correct on both gross and net store configurations.
• Store-view scope — every section setting can be overridden per website or per store view (default surcharge rates, rule pools, notice colours, free-threshold values), so different markets can run different configurations without installing the module twice.
• Deterministic resolver priority chain — per-product amount override → rule cost → customer-group price → tier price → section default cost; the first match wins, lower priorities are skipped.
• Eligibility OR-chain — product is in a configured surcharge category, OR has the stm_surcharge_enabled flag, OR is bound to an active rule; a rule alone is a self-sufficient activation path.
• Filterable rule column in the product grid — new EAV attribute stm_surcharge_rule_id exposed as a visible, filterable column in the standard product grid, so admins can see and filter by surcharge rule without leaving the catalog.
• Compatibility with Magento Open Source / Adobe Commerce 2.4.x, PHP 8.1, 8.2, 8.3 and 8.4, the default Luma frontend, Hyva Themes (dedicated hyva_* layout handles for the cart-totals template and the product-page notice) and IA24 OnePageCheckout (supported via the PHP-Cart variant with client-side recalculation on shipping-method change).
• Zero external dependencies — no core rewrites, no third-party CDN calls, no external service dependencies, no license-server callout at runtime.
• Internationalization — complete German translation (de_DE, 119 strings) ships with the module; every user-facing string is translatable via the standard Magento i18n CSV format.
• Adobe EQP-compliant — PHPCS Magento2 standard 0 errors / 0 warnings, PHPCompatibility for PHP 8.1+ 0 errors / 0 warnings; PSR-4 autoloading under the STM\SurchargeMax\ namespace, declare(strict_types=1) throughout, service contracts only, three EAV attributes grouped together in their own product-edit attribute group.

The Bulk-Assign workflow in five clicks

1. Open Catalog → STM Surcharge Rules and create one or more rules, for example: "Cutting Premium / 35.00 € / per item", "Engraving Flat / 9.90 € / per order", "Edge Polish / 5.00 € / per item".
2. Open the standard Catalog → Products grid, filter by category, brand, attribute set or SKU pattern, and select the rows.
3. From the Actions dropdown choose "Assign STM Surcharge Rule".
4. On the chooser page pick the target rule from the dropdown and click Apply to N product(s).
5. The grid now shows the chosen rule in the Surcharge Rule column. The rule kicks in immediately on the next add-to-cart.

The resolver priority chain

Per cart item the surcharge cost is resolved server-side along a strict, deterministic priority chain. The first match wins; lower priorities are skipped:

1. Per-product amount override (stm_surcharge_amount) — beats everything if > 0.
2. Rule cost — named rule via stm_surcharge_rule_id.
3. Customer-group price — matching customer_group_id.
4. Tier price — matching cart quantity in [from, to].
5. Section default cost — configured in the section settings.

Eligibility is itself an OR of three signals: the product is in a configured surcharge category, OR has the stm_surcharge_enabled flag, OR is bound to an active rule. Rule-bound products are eligible even without a category and without the enabled flag, so a rule alone is a self-sufficient activation path.

Built for shops that ship made-to-order or finishing services

• Pipes & tubing. One rule for thin-wall cutting, another for thick-wall cutting, bulk-assigned across the relevant product sets — tier pricing layered on top for bulk orders.
• Sheet metal & aluminium. Shearing rule per material thickness, B2B customers receive a reduced rate via customer-group pricing, country restriction limits the surcharge to the domestic market.
• Custom textile & fabric. Per-item hemming rule plus a friendly product-page notice that explains the lead time; free-threshold makes the surcharge disappear above a configurable cart total.
• Glass & mirror. Edge-polishing rule per piece, retail customers see the notice on the PDP so the cart total is never a surprise.
• Made-to-order furniture. A one-time per-order handling rule regardless of quantity, capped at a maximum amount, with a brand-aligned notice box.
• Engraving & personalisation. Per-item rule with quantity tiers for batch orders; a min-amount setting prevents micro-charges on single-item orders.
• Print, framing & finishing. Multiple rules for different finishing levels, bulk-assigned per finishing-class category, with customer-group pricing for trade accounts.

Section configuration at a glance

All section settings live under Stores > Configuration > STM > Category Surcharge and are scope-aware down to the store-view level. Six logical groups: General (module on / off toggle); Surcharge Configuration (surcharge category IDs, default cost, label, per-order vs per-item calculation); Tier Pricing (toggle plus from-qty / to-qty / cost grid); Customer Group Pricing (toggle plus customer-group / cost grid that overrides defaults and tiers); Conditions & Limits (min amount, max amount, free-shipping threshold, country restriction with multiselect of allowed countries); Product Page Notice (toggle, optional custom text with placeholders, three hex colours for background, border and text). Rule management lives separately under Catalog → STM Surcharge Rules, with its own ACL resource and sub-permissions for save, delete and bulk-assign.

What's new in 2.4.0

Version 2.4.0 is the first public Adobe Commerce Marketplace release and consolidates everything previously distributed internally. Highlights compared to earlier 2.x lines:

• Brand-new Multi-Rule Engine with its own admin grid, full CRUD and mass-actions — the headline 2.4.0 feature.
• Bulk-assign mass-action in the catalog product grid — the second headline 2.4.0 feature, the fastest way to bind a rule to hundreds of SKUs.
• New EAV attribute stm_surcharge_rule_id exposed as a visible, filterable column in the product grid.
• Resolver priority chain extended to consider rule cost between per-product override and customer-group / tier price — deterministic, no surprise stacking.
• 60 new translation keys for the rule engine and bulk-assign UI, in both English and German.
• EQP-clean codebase — PHPCS Magento2 standard 0 errors / 0 warnings, PHPCompatibility for PHP 8.1+ 0 / 0.
• Refactored for Marketplace conventions — PSR-4 autoloading, strict types throughout, no third-party dependencies, no Alpine.js, no external CDN, no license-server callout.

Compatibility

• Magento Open Source / Adobe Commerce 2.4.x
• PHP 8.1, 8.2, 8.3 and 8.4
• Default Luma frontend — works out of the box with the standard storefront.
• Hyva Themes — dedicated hyva_* layout handles for the cart-totals template and the product-page notice.
• STM Smart OnePageCheckout — supported via the PHP-Cart variant, with client-side recalculation on shipping-method change.
• No core rewrites, no third-party CDN calls, no external service dependencies, no license-server callout at runtime.

What's in the box

• The full module source under app/code/STM/SurchargeMax/.
• Installation Guide (PDF) — requirements, Composer / manual install, verification, troubleshooting, uninstall.
• User Guide (PDF, 12 pages, 13 figures) — end-to-end walkthrough of every feature with annotated screenshots.
• Reference Manual (PDF) — technical reference for developers: admin routes, configuration paths, EAV attributes, database schema, ACL resources, resolver chain, calculation modes, setup patches.
• LICENSE.txt at the module root — the Storetown Media Software License (English adaptation, with reference to the canonical German version).
• i18n CSVs for English and German with 119 strings each.

Licensing

STM Surcharge Max is distributed as a commercial extension under the Storetown Media Software License (EULA). The licence grants a perpetual, non-exclusive, non-transferable right to install and use the software on one (1) production domain plus an unlimited number of staging, development and test environments associated with that production domain. Source-code modification for the licensee's own use within the licensed installation is permitted; redistribution, sublicensing and use on a second production domain are not.

Every licence purchase includes a 12-month maintenance period from the purchase date covering all software updates and technical support. After the maintenance period the perpetual right of use remains intact — the most recently received version may continue to be used without time limit; new updates and continued support require a renewal. A 30-day money-back guarantee applies to first-time purchases. The full licence terms are published at https://www.storetown-media.de/licence/.

Support and updates

Support is provided by Storetown Media through the Adobe Commerce Marketplace support link on this listing. Expected response time is within two business days. Documentation, installation guide and reference manual ship with the extension as PDF and are kept in sync with each release. Questions or pre-sales enquiries: write to info@storetown-media.de or visit https://www.storetown-media.de.