README

A Magento 2 module that shows a "Minimum Order Fee" as a separate total row on orders, invoices and credit memos — in the admin panel, on the storefront, in sales emails and in invoice/credit memo PDFs.

The module is designed for setups where orders are created outside the Magento checkout (e.g. written directly to the Magento database by an external backend). It therefore does not calculate the fee; it only:

1. Schema — adds fee columns to sales_order, sales_invoice and sales_creditmemo.
2. Display — renders the fee row between Subtotal and Grand Total on admin order/invoice/credit memo screens, storefront order view/print, order emails and PDFs.
3. Consistency — registers invoice and credit memo total collectors so that invoices/credit memos created in the admin include the fee in their grand_total.
4. API — exposes the fee via extension attributes on the order, invoice and credit memo REST/SOAP APIs.

Requirements

• Magento 2.3.x / 2.4.x (tested on 2.4.7)
• PHP 7.4+

Installation

Via Composer (Packagist)

In your Magento root directory:

composer require cdmanager/magento-min-order-fee

Via Composer (directly from GitHub)

If the package is not (yet) available on Packagist, add the repository to your Magento project's composer.json first:

composer config repositories.magento-min-order-fee vcs https://github.com/cdmanager/magento-min-order-fee
composer require cdmanager/magento-min-order-fee

Enable the module

bin/magento module:enable Chefsdeal_MinOrderFee
bin/magento setup:upgrade
bin/magento setup:di:compile   # production mode
bin/magento cache:flush

setup:upgrade applies the declarative schema (etc/db_schema.xml) and creates the fee columns.

Data contract

The external system that creates orders must populate the following columns on sales_order:

Rules:

• The fee is not an order item. sales_order.subtotal contains products only; grand_total includes the fee:

  grand_total = subtotal + shipping + tax − discount + min_order_fee
  

• The fee is tax-free — it must not affect tax_amount.

• In a single-currency setup, min_order_fee == base_min_order_fee.

• Do not write the sales_invoice / sales_creditmemo columns yourself: the module's total collectors derive them from sales_order when an invoice or credit memo is created in the admin.

Verification

After deploying:

1. Check that the columns exist: SHOW COLUMNS FROM sales_order LIKE 'min\_order\_fee%'.
2. Create an order with a fee via the external backend; verify that the "Minimum Order Fee" row appears between Subtotal and Grand Total on the admin order view and that grand_total reconciles.
3. Create an invoice in the admin → the fee row appears in the invoice totals and grand_total matches the order.
4. Create a full/partial credit memo → the fee appears in the credit memo totals and is not double-counted (order fee − already refunded).
5. Verify the fee row in the order confirmation email and the invoice PDF.
6. For multi-brand orders, hover over the row label → the tooltip shows the per-brand breakdown from min_order_fee_details.

File map

├── registration.php
├── etc/
│   ├── module.xml
│   ├── db_schema.xml                      # fee columns
│   ├── db_schema_whitelist.json
│   ├── extension_attributes.xml           # order/invoice/creditmemo API fields
│   ├── sales.xml                          # invoice & creditmemo total collectors
│   └── config.xml                         # PDF (invoice/creditmemo) total row
├── Model/Total/
│   ├── Invoice/MinOrderFee.php            # adds the fee to invoice grand_total
│   └── Creditmemo/MinOrderFee.php         # adds the fee to creditmemo grand_total
├── Block/
│   ├── Adminhtml/Totals/MinOrderFee.php   # admin order/invoice/creditmemo totals
│   └── Order/Totals/MinOrderFee.php       # storefront + email totals
└── view/
    ├── adminhtml/
    │   ├── layout/                        # sales_order_view, invoice view/new, creditmemo view/new
    │   └── templates/order/totals/min_order_fee.phtml
    └── frontend/
        ├── layout/                        # sales_order_view, sales_order_print, sales_email_order_items
        └── templates/order/totals/min_order_fee.phtml

Notes

• Email/PDF block names can be theme-dependent. The order_totals layout reference works with the standard themes; a customized theme may need extra layout handles for invoice/credit memo emails (sales_email_order_invoice_items, sales_email_order_creditmemo_items).

• Tooltip is currently a plain title attribute (native browser tooltip). A rich tooltip requires a theme-side JS/CSS component.

• If you add new columns, regenerate the whitelist with:

  bin/magento setup:db-declaration:generate-whitelist --module-name=Chefsdeal_MinOrderFee

License

GPL-3.0-only — see LICENSE.