Product & Order Surcharges — Documentation

This is the complete documentation for STM Surcharge Max (version 2.4.0), listed on the Adobe Commerce Marketplace as Product & Order Surcharges. Everything on this page is free to read — no registration, no account.

User Guide

Overview

STM Surcharge Max adds a category- and product-level surcharge to your Magento 2 / Adobe Commerce store as its own line item, distinct from shipping and tax. Shop owners can define an unlimited number of named, reusable rules through a dedicated admin grid, bulk-assign rules to products directly from the catalog product grid, layer per-product overrides on top, configure quantity tiers and customer-group pricing, and cap the result with min-amount, max-amount, free-threshold and country-restriction conditions. The extension is configuration-driven, fully translatable, and compatible with Luma-based themes, Hyva Themes (via dedicated hyva_* layout handles) and Smart One Page Checkout (via the PHP-Cart variant). All admin settings are scope-aware down to the store-view level.

Surcharge Rules

Open Catalog > STM Surcharge Rules for the rule listing. Each rule has its own cost, calculation mode (per item or per order), active flag and sort order. The grid supports column filters, full-text search, pagination and bookmarks; mass actions include Mass Delete, Mass Enable and Mass Disable.

(€35.00 per item), Engraving Flat (€9.90 per order), Edge Polish (€5.00 per item) and Hemming Premium (€12.50 per item). Click Edit on any row — or Add New Rule — to open the rule edit form:

highest matching per-unit cost in the order.

Bulk-Assign from the Product Grid

Once you have at least one active rule, open Catalog > Products, filter or search as needed, tick the rows you want to bind, and pick Assign STM Surcharge Rule from the Actions dropdown:

the menu opens the chooser page. The chooser page shows the number of selected products and a drop-down with all active rules. Pick the target rule and click Apply to N product(s):

stm_surcharge_amount per-product override is independent and is not affected by the bulk-assign. After apply, the Surcharge Rule column in the product grid shows the bound rule name. Use the column header to filter or sort by rule:

rule name for each row.

Per-Product Configuration

Open any product under Catalog > Products. A new STM Surcharge Max attribute group is available on the product edit page with three store-scope fields:

• Enable surcharge for this product (stm_surcharge_enabled) — when enabled, this product carries the surcharge regardless of its category assignment. Use it for individual SKUs that do not belong to a surcharge category.
• Surcharge rule (stm_surcharge_rule_id) — optional binding to a named rule. Active rules are listed in the dropdown ordered by sort_order then by name. The rule’s cost beats customer-group, tier and section default; it is itself overridden by an explicit per-product amount.
• Surcharge amount override (stm_surcharge_amount) — when set to a value greater than zero, this overrides every lower priority rate for this product, including the rule cost.

per-product amount override of €30.00 that supersedes the rule’s €35.00 cost.

Section Configuration

All section-level settings live under Stores > Configuration > STM > Category Surcharge and are scope-aware down to the store-view level. The section is split into six logical groups.

label, calculation mode).

Tier Pricing

Quantity-based tiers that scale the surcharge cost with the number of surcharge-eligible items in the cart. Each tier has From Qty, To Qty (leave empty for unlimited) and Surcharge Cost. The active tier wins over the section default cost.

Customer Group Pricing

Per-customer-group cost overrides for the surcharge. Useful for B2B / Wholesale flat rates, retail markup, or guest-vs-logged-in differentiation. Customer-group pricing wins over both default and tier pricing.

Conditions & Limits

Four caps that apply to the calculated surcharge:

• Minimum Surcharge Amount — if the calculated surcharge is below this amount, no surcharge is applied (“skip small charges”, not “raise to minimum”).
• Maximum Surcharge Amount (Cap) — if the calculated surcharge exceeds this amount, it is capped at this value.
• Free Above Cart Subtotal — the surcharge is dropped entirely once the cart subtotal (excluding tax) reaches the threshold. Classic “free shipping above X” pattern, applied to the surcharge.
• Restrict by Shipping Country — apply the surcharge only when the shipping address is in one of the selected countries. Country source is the standard Magento country directory.

Product Page Notice

An optional, fully styleable notice box on every surcharge-eligible product page. Placeholders {{label}} and {{cost}} interpolate the configured surcharge label and the formatted price (currency- and locale-aware). Three independent hex colours control background, border and text.

Resolver Priority Chain

Per cart item, the surcharge cost is resolved server-side along a strict priority chain. The first match wins; the lower-priority rates are skipped. The same chain runs in the quote-total collector and in the product-page notice view-model, so what you see on the product detail page is what the customer pays in the cart. stm_surcharge_amount (per-product override, beats everything if > 0) → rule.cost (named rule via stm_surcharge_rule_id) → customer-group price → tier price → section default cost A cart item is eligible for the surcharge if any of the following is true: (a) the product is in one of the configured surcharge categories, (b) the product has stm_surcharge_enabled = Yes, or (c) the product is bound to an active rule via stm_surcharge_rule_id. Rule-bound products are eligible for the surcharge even without stm_surcharge_enabled and without any category assignment, so rules are a self-sufficient activation path.

Storefront Experience

On the product detail page, surcharge-eligible products carry an inline notice box that interpolates the label and amount from the resolver:

The displayed amount (€30.00) is the per-product override, which beats the rule cost (€35.00). In the cart, the surcharge appears as its own summary line, distinct from shipping and tax. The label (here: Cutting costs) is configured in the section.

End-to-End Persistence

The surcharge value is carried from quote to order, then to invoice and credit memo, via dedicated columns on each table:

• Declarative db_schema.xml adds stm_rohre_surcharge and base_stm_rohre_surcharge columns to quote, sales_order, sales_invoice and sales_creditmemo.
• fieldset.xml mappings carry the value through the standard sales_convert_quote and sales_convert_order conversion passes.
• A safety-net observer on sales_model_service_quote_submit_before guarantees the value persists from quote to order even when the fieldset mapping is inactive on a customised theme.
• Admin order, invoice and credit-memo views surface the surcharge as its own line between shipping and tax. Order-confirmation, invoice and credit-memo emails are pre-wired via sales_email_*_items layouts.

Internationalization

English is the base language. A German translation (i18n/de_DE.csv, 119 strings) is included. All user-facing strings are fully translatable via the standard Magento CSV format — drop additional files into the i18n/ directory.

Support

Support is provided by Storetown Media through the Adobe Commerce Marketplace support link on this listing. Expected response time is within two business days.

Installation Guide

Requirements

• Magento Open Source 2.4.x or Adobe Commerce 2.4.x
• PHP 8.1, 8.2, 8.3 or 8.4
• Composer 2.x (recommended) or SSH / FTP access for manual upload
• Magento in developer or production mode — default mode is also supported
• No third-party Composer dependencies. The module ships with Magento framework requirements only and does not pull any external libraries.
• No external service callout, no CDN dependency, no license-server check at runtime.

Installation via Composer (recommended)

Run the following commands from the Magento project root: composer require storetown-media/module-surcharge-max If Magento is in production mode, also run bin/magento setup:static-content:deploy for every active locale.

Manual Installation

Extract the ZIP archive so the module sources land under app/code/STM/SurchargeMax/, then run the same enable / upgrade / compile / flush sequence:

Verification

Confirm the module is active and the schema has been applied: bin/magento module:status STM_SurchargeMax # expected: Module is enabled Open the Magento admin and navigate to Stores > Configuration > STM > Category Surcharge. The configuration section must be visible with groups General, Surcharge Configuration, Tier Pricing, Customer Group Pricing, Conditions & Limits and Product Page Notice. Open the admin menu Catalog > STM Surcharge Rules — the rule listing grid should appear. From this grid you can create, edit, enable, disable and delete named surcharge rules. On any product edit page, scroll to the STM Surcharge Max attribute group and verify three fields: Enable surcharge for this product (yes / no), Surcharge rule (dropdown of active rules) and Surcharge amount override (decimal).

Add a surcharge-eligible product to the cart and confirm that the configured surcharge label and amount appear as a separate line in the cart summary, distinct from shipping and tax.

Troubleshooting

Class STM\SurchargeMax\... does not exist The module was extracted to the wrong folder. The path must be exactly app/code/STM/SurchargeMax/ (case-sensitive). Delete generated/ and var/cache/, then re-run setup:upgrade and setup:di:compile. Surcharge does not appear in the cart Confirm that the module is enabled under Stores > Configuration > STM > Category Surcharge > General > Enable Module. Verify that the cart contains either (a) a product in the configured surcharge category, (b) a product with stm_surcharge_enabled = Yes, or (c) a product bound to an active surcharge rule. If the Conditions & Limits group has a non-empty Free Above Cart Subtotal value, the surcharge is dropped once the subtotal exceeds that threshold. Tier or customer-group rates not applied The cost resolver follows a strict priority chain: per-product amount override > rule cost > customer-group price > tier price > section default. If a higher-priority match exists (for example, a non-zero stm_surcharge_amount on the product), the lower priority rates are ignored by design. See section 6 of the User Guide for the full priority chain. Surcharge Rule column empty in the product grid By default, Magento’s catalog product listing only joins EAV attributes that are filtered or made visible via the column picker. If the column shows blank for bound products, open the Filters panel and apply a Surcharge Rule filter, or add the column from the Columns picker once — Magento will then join the EAV value into the listing query and populate the cells. Production mode: changes don’t take effect After every code or schema change in production mode, complete the full deploy sequence: setup:upgrade, remove generated/code, generated/metadata, var/cache, var/page_cache and var/view_preprocessed; then run setup:di:compile, setup:static-content:deploy <locales> -f –no-html-minify and cache:flush.

Uninstall

To temporarily disable the module without removing data: bin/magento module:disable STM_SurchargeMax To fully uninstall via Composer: bin/magento module:uninstall STM_SurchargeMax The shipped SetupUninstall hook removes the module’s configuration rows from core_config_data (current stm_surchargemax/* paths plus the legacy stm_rohreshipping/* and carriers/stmrohreshipping/* paths for backward compatibility). The module table stm_surchargemax_rule is dropped by Magento’s declarative-schema uninstall pass. The surcharge columns on quote, sales_order, sales_invoice and sales_creditmemo are kept on uninstall to preserve historical order data.

Licensing

STM Surcharge Max is distributed as a commercial Magento 2 / Adobe Commerce extension under the Storetown Media Software License (EULA). A valid licence, acquired through the Adobe Commerce Marketplace or directly from Storetown Media, grants the licensee 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 directly 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 to use the most recently received version remains fully intact; new updates and continued support require renewal. Within ten (10) business days of purchase, the licence must be registered with Storetown Media at info@storetown-media.de by sending the production domain URL and the project name. Adobe Commerce Marketplace customers should include their Marketplace order number in the registration e-mail. An English-language adaptation of the EULA is included as LICENSE.txt in the module root. The canonical, legally binding German version is published at https://www.storetown-media.de/licence/; in case of any conflict between the two, the German version prevails. Governing law is German law (excluding CISG); place of jurisdiction is Hamburg, Germany.

Support

Support is provided by Storetown Media through the Adobe Commerce Marketplace support link on this listing. Expected response time is within two business days.

Frequently Asked Questions

Which Magento and Adobe Commerce versions are supported?

Magento Open Source and Adobe Commerce 2.4.4 and higher, on PHP 8.1 or higher. Declarative schema only, no core rewrites.

How does a surcharge appear to the customer?

As its own line item in cart, checkout, order, invoice and credit memo. It is never folded into the product price and never folded into the shipping rate.

What happens when several rules could apply to the same product?

A deterministic resolver chain decides, in a fixed priority: per-product override, then customer-group price, then quantity tier, then section default. What the customer sees on the product detail page is what lands in the cart.

Can a surcharge apply per order instead of per item?

Yes. Each rule carries its own calculation mode — per item or per order — so a cutting fee can be charged once per order while an engraving fee is charged per piece.

Does it work with multiple store views and currencies?

Yes. Every section setting can be overridden per website and per store view. A complete German translation ships with the module; further languages need no code changes.

Who can create and assign surcharge rules?

Access is governed by the dedicated ACL resource STM_SurchargeMax::rules, with separate sub-permissions for save, delete and bulk-assign — so rule creation can be delegated without handing over deletion rights.

Support

Questions about this extension are answered through the support link on the Marketplace listing. For pre-sales questions and custom requirements, get in touch.

← All documentation